版权声明 腾讯云版权所有本文档著作权归腾讯云单独所有, 未经腾讯云事先书面许可, 任何主体不得以任何形式复制 修改 抄袭 传播全部或部分本文档内容 商标声明 及其它腾讯云服务相关的商标均为腾讯云计算 ( 北京 ) 有限责任公司及其关联公司所有 本文档涉及的第三方主体的商标, 依法

Transcription

1 金融智能客服 API 文档 产品文档 第 1 共 23 页

2 版权声明 腾讯云版权所有本文档著作权归腾讯云单独所有, 未经腾讯云事先书面许可, 任何主体不得以任何形式复制 修改 抄袭 传播全部或部分本文档内容 商标声明 及其它腾讯云服务相关的商标均为腾讯云计算 ( 北京 ) 有限责任公司及其关联公司所有 本文档涉及的第三方主体的商标, 依法由权利人所有 服务声明 本文档意在向客户介绍腾讯云全部或部分产品 服务的当时的整体概况, 部分产品 服务的内容可能有所调整 您所购买的腾讯云产品 服务的种类 服务标准等应由您与腾讯云之间的商业合同约定, 除非双方另有约定, 否则, 腾讯云对本文档内容不做任何明示或模式的承诺或保证 第 2 共 23 页

3 文档目录 API 文档 API 简介 API 概览调用方式请求结构公共参数接口鉴权接口调试工具返回结果正确返回结果错误返回结果错误码相关接口查询欢迎语查询热点知识问答会话 第 3 共 23 页

4 API 文档 API 简介 最近更新时间 : :11:45 腾讯云 FICS 为您提供智能 便捷的金融智能客户服务, 您在腾讯云控制台完成机器人实例创建和知识库配置上线 后, 即可使用云 API 接口将机器人接入到您的客服渠道中 第 4 共 23 页

5 API 概览 最近更新时间 : :11:47 接口 Action ID 功能描述 查询欢迎语 WelcomeMessage 用于查询某个渠道的欢迎语 查询热点知识 HotKnowledge 用于查询系统自动生成或者自定义的热点知识 问答会话 Query 用于问答会话 第 5 共 23 页

6 调用方式 请求结构 最近更新时间 : :12:06 服务地址腾讯云 API 接口按照功能划分成了不同的功能模块, 每个模块使用不同的域名访问, 腾讯云 FICS 的域名为 athena.api.qcloud.com 通信协议腾讯云 API 的所有接口均通过 HTTPS 进行通信, 提供高安全性的通信通道 请求方法同时支持 POST 和 GET 请求, 需要注意不能混合使用 即如果使用 GET 方式, 则参数均从 QueryString 取得 ; 如果使用 POST 方式, 则参数均从 Request Body 中取得,QueryString 中的参数将忽略 两种方式参数格式规则相同, 一般使用 GET, 当参数字符串过长时使用 POST, 请见各接口详细描述 字符编码均使用 UTF-8 编码 API 请求结构 名称描述备注 API 入口 API 调用的 WebService 入口 https: // athena.api.qcloud.com/v2/index.php 公共 参数 每个接口都包含的通用参数 详见公共参数页面 接口 名称 API 要执行的指令的名称, 这里使用 Action 指定, 例如 Action= Query 完整的接口名称列表请见 API 概览 指令 参数 每个特定的接口需要的参数 详见每个接口的文档 第 6 共 23 页

7 公共参数 最近更新时间 : :13:38 公共参数是用于标识用户和接口鉴权目的的参数, 如非必要, 在每个接口单独的接口文档中不再对这些参数进行说明, 但每次请求均需要携带这些参数, 才能正常发起请求 参数名称是否必填类型描述 Action 是 String 具体操作的接口名称, 例如想要调用 查询欢迎语 接口, 则 Action 参数为 WelcomeMessage Timestamp 是 UInt 当前 UNIX 时间戳, 可记录发起 API 请求的时间 Nonce 是 UInt 随机正整数, 与 Timestamp 联合起来, 用于防止重放攻击 SecretId 是 String Signature 是 String 在云 API 密钥上申请的标识身份的 SecretId, 一个 SecretId 对应唯一的 SecretKey, 而 SecretKey 会用来生成请求签名 Signature 具体可参考接口鉴权页面 请求签名, 用来验证此次请求的合法性, 需要用户根据实际的输入参数计算得出 计算方法可参考接口鉴权页面 SignatureMethod 否 String 签名方式, 目前支持 HmacSHA256 和 HmacSHA1 只有指定此参数为 HmacSHA256 时, 才使用 HmacSHA256 算法验证签名, 其他情况均使用 HmacSHA1 验证签名 签名计算方法可参考接口鉴权页面 假设您要查询欢迎语, 则请求链接形式类似如下 : &Timestamp= &Nonce= &SecretId= XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX &Signature=xxxxxxxx &InstanceId=4d8573a2-ff42-11e bb7b8b &AccessChannelCode=default 第 7 共 23 页

8 接口鉴权 最近更新时间 : :27:05 腾讯云 API 会对每个访问请求进行身份验证, 即每个请求都需要在公共请求参数中包含签名信息 (Signature) 以验证请求者身份 签名信息由安全凭证生成, 安全凭证包括 SecretId 和 SecretKey; 若您还没有安全凭证, 请前往云 API 密钥页面申请, 否则无法调用云 API 接口 申请安全凭证 在第一次使用云 API 之前, 请前往云 API 密钥页面申请安全凭证 安全凭证包括 SecretId 和 SecretKey: SecretId 用于标识 API 调用者身份 ; SecretKey 用于加密签名字符串和服务器端验证签名字符串的密钥 您必须严格保管安全凭证, 避免泄露 申请安全凭证的具体步骤如下 : 1 登录腾讯云管理中心控制台 2 前往云 API 密钥的控制台页面 3 在云 API 密钥页面, 单击 新建 即可创建一对 SecretId/SecretKey 注意 : 开发商帐号最多可以拥有两对 SecretId / SecretKey 第 8 共 23 页

9 被开发商添加为子用户的 QQ 帐号, 在不同开发商控制台, 可以申请不同的安全凭证 子用户的安全凭证, 目前仅可调用 CDN 的云 API 生成签名串 有了安全凭证 SecretId 和 SecretKey 后, 就可以生成签名串了 假设您的 SecretId 和 SecretKey 分别是 : SecretId: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX SecretKey: YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY 注意 : 这里只是示例, 请请根据您实际申请的 SecretId 和 SecretKey 进行后续操作! 以查询欢迎语 (WelcomeMessage) 请求为例, 当您调用这一接口时, 请求参数可能如下 : 参数名称参数描述参数值 Action 接口名称 WelcomeMessage Timestamp 当前时间戳 Nonce 随机正整数 SecretId 密钥 ID XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX InstanceId 机器人实例 ID 4d8573a2-ff42-11e bb7b8b AccessChannelCode 接入渠道代码 default 上表中, 公共参数有 4 个 :Action Timestamp Nonce SecretId 而在公共参数介绍中有 5 个必输公共参 数, 事实上, 第 5 个公共参数 Signature( 签名串 ) 是由其他参数 ( 包括指令参数 ) 共同生成的, 具体步骤如下 : 对参数排序首先对所有请求参数按参数名做字典序升序排列, 所谓字典序升序排列, 直观上就如同在字典中排列单词一样, 按照字母表或数字表里递增顺序的排列顺序, 即先考虑第一个 字母, 在相同的情况下考虑第二个 字母, 依此类推 您可以借助编程语言中的相关排序函数来实现这一功能, 如 php 中的 ksort 函数 上述示例参数的排序结果如下 : "AccessChannelCode": "default", "Action": "WelcomeMessage", "InstanceId": "4d8573a2-ff42-11e bb7b8b", "Nonce": , "SecretId": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", 第 9 共 23 页

10 } "Timestamp": 使用其它程序设计语言开发时, 得到的结果一致即可 拼接参数字符串将上一步排序好的请求参数格式化成 参数名称 = 参数值 的形式, 如对 Action 参数, 其参数名称为 Action, 参数值为 WelcomeMessage, 因此格式化后为 Action= WelcomeMessage 然后将格式化后的各个参数用 & 拼接在一起, 最终生成的字符串为 : AccessChannelCode=default&Action=WelcomeMessage&InstanceId=4d8573a2-ff42-11e 注意 : 参数值 为原始值, 而非 url 编码后的值, 若输入参数中包含下划线, 则需要将其转化为. 拼接请求字符串请求字符串由以下几个参数构成 : 请求方法 : 支持 POST 和 GET 方式, 这里以 GET 方式举例, 注意请求方法为全大写 ; 请求域名 : 腾讯云 FICS 的请求域名为 athena.api.qcloud.com; 请求路径 : 云 API 的请求路径固定为 /v2/index.php; 参数字符串 : 即上一步生成的参数字符串 请求字符串的拼接规则为 : 请求方法 + 请求域名 + 请求路径 +?+ 参数字符串 前述示例的请求字符串拼接结果为 : GETathena.api.qcloud.com/v2/index.php?AccessChannelCode=default&Action=WelcomeMessage&Inst 生成签名串首先使用 HMAC-SHA1 算法对上一步中得到的拼接请求字符串进行签名, 然后将生成的签名串使用 Base64 进行编码, 即可得到签名串 具体代码如下, 以 PHP 语言为例 : $secretkey = 'YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY'; $srcstr = 'GETathena.api.qcloud.com/v2/index.php?AccessChannelCode=default&Action=WelcomeMes $signstr = base64_encode(hash_hmac('sha1', $srcstr, $secretkey, true)); echo $signstr; 最终得到的签名串为 : 第 10 共 23 页

11 XuWWOe2NqxNxZD+6agJdOgi0EQU= 使用其它程序设计语言开发时, 得到的结果一致即可 签名串编码 前述生成的签名串并不能直接作为请求参数, 需要对其进行 URL 编码 如前述生成的签名串为 XuWWOe2NqxNxZD+6agJdOgi0EQU= 其 URL 编码后为 XuWWOe2NqxNxZD+6agJdOgi0EQU= 该字符串即为最终的请求签名 Signature 注意 : 如果请求方式给 GET, 则需要对所有请求参数值都进行 URL 编码 拼接最终请求链接 将所有参数拼接在一起, 得到的最终请求链接为 : &Timestamp= &Nonce= &SecretId= XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX &Signature=&Signature=XuWWOe2NqxNxZD+6agJdOgi0EQU= &InstanceId=4d8573a2-ff42-11e bb7b8b &AccessChannelCode=default 第 11 共 23 页

12 接口调试工具 最近更新时间 : :12:22 请前往云 API 接口调试工具进行接口测试 第 12 共 23 页

13 返回结果 正确返回结果 最近更新时间 : :12:41 若云 API 调用成功, 则返回结果中的错误码 code 为 0, 模块错误信息 message 为空, 错误码描述 codedesc 为 空, 并且返回相应的结果数据, 示例如下 : } "code": 0, "message": "", "codedesc": "", < 返回结果数据 > 第 13 共 23 页

14 错误返回结果 最近更新时间 : :12:44 若云 API 调用失败, 则返回结果中的错误码 code 不为 0,message 字段会显示具体模块相关的详细错误信息, codedesc 字段会显示与 code 相关的英文错误描述信息, 示例如下 : } "code": 4104, "message": "SecretId 不存在 ", "codedesc": "SecretidNotExit" 第 14 共 23 页

15 错误码 最近更新时间 : :12:47 公共错误码 返回结果中的错误码表示了用户调用云 API 的结果 其中,code 为公共错误码, 适用于所有腾讯云产品的 API 接 口 若 code 为 0, 表示调用成功, 否则表示调用失败 当调用失败后, 用户可以根据下表确定错误原因并采取相应 措施 错误代码错误类型描述 4000 请求参数非法 4100 身份认证失败 缺少必要参数, 或者参数值格式不正确, 具体错误信息请查看错误描述 message 字段 身份认证失败, 一般是由于签名计算错误导致的, 请参考文档中接口鉴权部分 4101 未授权访问接 口 子账号未被主账号授权访问该接口, 请联系主帐号管理员开通接口权限 4102 未授权访问资 源 子账号未被主账号授权访问特定资源, 请联系主帐号管理员开通资源权限 4103 未授权访问当 前接口所操作 的资源 子账号没有被主账户授权访问该接口中所操作的特定资源, 请联系主帐号管理员 开通资源权限 4104 密钥不存在用于请求的密钥不存在, 请确认后重试 4105 token 错误 token 错误 4106 MFA 校验失 败 MFA 校验失败 4110 其他 CAM 鉴 权失败 其他 CAM 鉴权失败 4300 拒绝访问帐号被封禁, 或者不在接口针对的用户范围内等 4400 超过配额请求的次数超过了配额限制, 请参考文档请求配额部分 4500 重放攻击 请求的 Nonce 和 Timestamp 参数用于确保每次请求只会在服务器端被执行一 次, 所以本次的 Nonce 和上次的不能重复,Timestamp 与腾讯服务器相差不 能超过 5 分钟 第 15 共 23 页

16 错误代码错误类型描述 4600 协议不支持协议不支持, 当前 API 仅支持 https 协议, 不支持 http 协议 5000 资源不存在 5100 资源操作失败 资源标识对应的实例不存在, 或者实例已经被退还, 或者访问了其他用户的资源 对资源的操作失败, 具体错误信息请查看错误描述 message 字段, 稍后重试或者联系客服人员帮忙解决 5200 资源购买失败购买资源失败, 可能是不支持实例配置, 资源不足等等 5300 余额不足用户帐号余额不足, 无法完成购买或升级 5400 部分执行成功批量操作部分执行成功, 详情见方法返回值 5500 用户资质审核 未通过 购买资源失败, 用户资质审核未通过 6000 服务器内部错 误 服务器内部出现错误, 请稍后重试或者联系客服人员帮忙解决 6100 版本暂不支持本版本内不支持此接口或该接口处于维护状态等 6200 接口暂时无法 访问 当前接口处于停服维护状态, 请稍后重试 注意 : 出现 6100 错误时, 请先确定接口的域名是否正确, 不同的模块, 域名可能不一样 模块错误码 message 字段表示与具体模块相关的错误信息,codeDesc 字段表示与 code 相关的英文错误信息 如错误返回示例 : } "code": 5100, "message": "(XXXXXX)YYYYYY", "codedesc": "ZZZZZZ" 其中,message 的值由 错误代码 和 错误描述 两部分组成, XXXXXX 为具体模块错误代码, YYYYYY 为具体模块 错误描述, 具体信息详见对应产品 API 接口中的错误码列表 第 16 共 23 页

17 相关接口 查询欢迎语 最近更新时间 : :12:59 接口描述 本接口 (WelcomeMessage) 用于查询某个机器人实例中某个接入渠道下的欢迎语 接口请求域名 :athena.api.qcloud.com 输入参数 以下请求参数列表仅列出了接口请求参数, 正式调用时需要加上公共请求参数, 具体请见公共参数页面 其中, 本 接口的 Action 字段为 WelcomeMessage 参数名称是否必选类型描述 InstanceId 是 String 机器人实例 ID, 可以在云控制台机器人列表中查到 AccessChannelCode 是 String 要获取的欢迎语所属的接入渠道代码 输出参数 参数名称类型描述 code Int 公共错误码,0 表示成功, 其他值表示失败, 详见公共错误码页 面 message String 模块错误信息描述, 与接口相关 codedesc String 错误码对应的错误信息描述 welcomemessagetypename String 欢迎语类型名字 welcomemessagetypecode String 欢迎语类型代码 welcomemessagecontent String 欢迎语内容 第 17 共 23 页

18 错误码列表 错误码 描述 1001 请求参数不符合要求 1002 机器人不存在 示例 机器人实例为 4d8573a2-ff42-11e bb7b8b, 接入渠道代码为 default( 表示系统默认的接入渠 道 ) 请求参数 &InstanceId=4d8573a2-ff42-11e bb7b8b &AccessChannelCode=default &< 公共请求参数 > 返回参数 "code": 0, "message": "", "codedesc": "", "welcomemessagetypename": " 文本 ", "welcomemessagetypecode": "text", "welcomemessagecontent": " 您好, 请问有什么可以帮您 ~" } 第 18 共 23 页

19 查询热点知识 最近更新时间 : :13:02 接口描述 本接口 (HotKnowledge) 用于查询某个机器人实例中的热点知识 接口请求域名 :athena.api.qcloud.com 输入参数 以下请求参数列表仅列出了接口请求参数, 正式调用时需要加上公共请求参数, 具体请见公共参数页面 其中, 本 接口的 Action 字段为 HotKnowledge 参数名称是否必选类型描述 InstanceId 是 String 机器人实例 ID, 可以在云控制台机器人列表中查到 HotKnowledgeCode 否 String Count 是 Int 要获取的热点知识代码, 为空时表示获取系统自动生成的热点知识, 有值时表示获取该代码对应的自定义热点知识 要获取的热点知识条数, 实际返回条数依情况而定, 不会超过该值 输出参数 参数名称类型描述 code Int 公共错误码,0 表示成功, 其他值表示失败, 详见公共错误码页 面 message String 模块错误信息描述, 与接口相关 codedesc String 错误码对应的错误信息描述 hotknowledge.n Array 热点知识组 hotknowledge.n.knowledge String 热点知识 hotknowledge.n.hittimes Int 热点知识命中次数 第 19 共 23 页

20 错误码 错误码 描述 1001 请求参数不符合要求 1002 机器人不存在 示例 机器人实例为 4d8573a2-ff42-11e bb7b8b, 热点知识代码不上送, 热点知识条数为 3 请求参数 &InstanceId=4d8573a2-ff42-11e bb7b8b &Count=3 &< 公共请求参数 > 返回参数 "code": 0, "message": "", "codedesc": "", "hotknowledge": [ "knowledge": " 信用卡申请 ", "hittimes": "100" }, "knowledge": " 信用卡激活 ", "hittimes": "99" }, "knowledge": " 信用卡挂失 ", "hittimes": "98" } ] } 第 20 共 23 页

21 问答会话 最近更新时间 : :13:06 接口描述 本接口 (Query) 用于进行问答会话 接口请求域名 :athena.api.qcloud.com 输入参数 以下请求参数列表仅列出了接口请求参数, 正式调用时需要加上公共请求参数, 具体请见公共参数页面 其中, 本 接口的 Action 字段为 Query 参数名称是否必选类型描述 InstanceId 是 String 机器人实例 ID, 可以在云控制台机器人列表中查 到 AccessChannelCode 是 String 问答会话发起渠道代码 SessionId 是 Int 问答会话 ID, 同一通会话需保持一致 Query 是 String 会话问题 RelatedKnowledgeMaxNum 否 Int 允许返回的关联知识最大值, 默认为 10 输出参数 参数名称类型描述 code Int 公共错误码,0 表示成功, 其他值表示失败, 详见公共错误 码页面 message String 模块错误信息描述, 与接口相关 codedesc String 错误码对应的错误信息描述 第 21 共 23 页

22 参数名称类型描述 responsetype String 本次问答结果类型 :MATCHED 表示命中了知识 ; ASKBACK 表示反问 ;NOMATCH 表示没有命中知识 ; NOANSWER 表示命中了知识, 但对应渠道没有配置答案 matchedknowledge String 命中的知识, 当 ResponseType 为 MATCHED 时有值 matchconfidence Double 命中知识的置信度, 当 ResponseType 为 MATCHED 时有 值 answertypename String 回答结果类型名字 answertypecode String 回答结果类型代码 answercontent String 回答结果内容 labelset.n Array 反问标签, 当 ResponseType 为 ASKBACK 时有值 labelset.n.label String 反问标签, 当 ResponseType 为 ASKBACK 时有值 relatedknowledge.n Array 关联知识组 relatedknowledge.n.knowledge String 关联知识 relatedknowledge.n.confidence Double 关联知识置信度 错误码列表 错误码 描述 1000 服务异常, 请稍后再试 1001 请求参数不符合要求 1002 机器人不存在 1003 渠道不存在 示例 机器人实例为 4d8573a2-ff42-11e bb7b8b, 接入渠道代码为 default, 问答会话 ID 为 ,, 问题为 信用卡申请, 允许返回的关联知识最大值为 3 第 22 共 23 页

23 请求参数 &InstanceId=4d8573a2-ff42-11e bb7b8b &AccessChannelCode=default &SessionId= &Query= 信用卡申请 &RelatedKnowledgeMaxNum=3 &< 公共请求参数 > 返回参数 "code": 0, "message": "", "codedesc": "", "responsetype": "MATCHED", "matchedknowledge": " 信用卡申请 ", "matchconfidence": 1, "answertypename": " 文本 ", "answertypecode": "text", "answercontent": " 您可以通过我行 APP 申请信用卡 ~", "labelset": [] "relatedknowledge": [ "knowledge":" 信用卡激活 ", "confidence":0.6 }, "knowledge":" 信用卡挂失 ", "confidence":0.58 }, "knowledge":" 信用卡补卡 ", "confidence":0.55 } ] } 第 23 共 23 页