机器人第三方接口调用指南

一.使用场景

智齿客服机器人除了可以进行基于知识库内容的问答外,还能够进行基于第三方接口的信息调用。
比如快递公司希望用户可以在与机器人沟通时自助查询快递情况,就可以针对此场景在知识库中设立一个机器人调用快递查询接口的问题。
当用户交互时若触发该问题,机器人就可以将用户希望查询的快递单号传递给查询接口,s再将查询接口返回的信息发送给用户,实现用户的自助查询。
比如,用户输入“订单查询:12345678”,机器人就会调用订单查询接口,并将用户信息以及用户输入的订单号“12345678”传递给查询接口,若查询接口正常返回了查询结果,机器人将会把查询结果展示给用户。

二.如何设置

1.设置项说明

对于企业版以及更高级版本的用户,在知识库中点击添加问题时,可以看到能够选择“接口调用”类型。选择后,将出现相关的设置项。

图片

其中各设置项的含义如下:

标准问法:用户输入中触发接口查询的关键字。该关键字必须在一次输入的开头。比如,设置标准问法为“订单查询”,则“订单查询:12345”可以正确触发接口调用,“能不能订单查询”将不会触发接口调用。接口调用问法的匹配优先级会高于其他问法,为关键字匹配,但为了避免造成知识库维护的混乱,请尽量避免与其他问题的标准问法一致或有包含关系。

接口URL:调用接口的地址。比如,http://www.test.com/Order

参数:需要机器人从用户输入内容中抽取的参数,并在调用接口时进行传递。

参数名称:传递该参数时使用的参数名,比如,OrderID,机器人在调用接口时将给OrderID参数赋值,并进行传递。

长度限制:限制此参数的长度,若用户输入的参数超过此长度,机器人将向用户展示调用说明。

参数说明:对此参数的备注说明信息。机器人不会使用此信息。

分隔符:与前一个参数或标准问法关键字区分开的符号,可以设置为空格,冒号,逗号,下划线,括号等。

图片

Token:调用接口时传递的Token,可随机生成,也可自定义。可作为智齿客服机器人在调用接口时的身份认证。

调用说明:当用户触发了接口调用,但未正确输入需要的参数时,机器人将把此处设定的内容展示给用户。

超时说明:在调用接口时若返回错误信息或超时,机器人将把此处设定的内容展示给用户。

选择分类:该问题在知识库中的分类。

生效时间:该问题的生效时间。

启用状态:该问题的启用状态。

2.设置示例

标准问法:天气查询

接口URL:http://www.test.com/weather/query?

添加参数:

参数名称 长度限制 参数说明 分隔符
key 40 调用接口 #
cityname 10 查询城市名称 #

Token:de8devfjtf8cj7eogi9el(随机生成)

调用说明:如果您想天气查询请按照如下格式提问:天气查询#ddXXXXXXXXXXXXXXXX12dd#上海

超时说明:网络连接超时,请稍后重试

3.触发调用说明

对于上例,用户在输入不同内容时的情况说明。

“查一下天气”(不触发接口调用)

“怎么天气查询呢?”(不触发接口调用)

“天气查询”(触发接口调用,但参数输入错误,机器人返回调用说明内容给用户)

“天气查询:北京”(触发接口调用,但参数输入错误,机器人返回调用说明内容给用户)

“天气查询#123456#上海”(触发接口调用,机器人将调用第三方接口,并将123456作为key参数值,上海作为cityname参数值进行传递)

4.参数传递

在进行接口调用时,机器人会以POST方式传递参数。

固定参数

固定参数是指无论如何进行设置,在调用接口时机器人都会传递的参数。包括:

partnerID:用户对接ID,有关信息可以查询《智齿客服接入指南》

Token:在设置时填写的Token字段

自定义参数

自定义参数是指在设置时添加的参数,机器人将按照用户输入顺序及分隔符提取参数,若参数提取正确,将向接口进行传递。

三.接口返回格式

接口返回结果应为JSON格式,应包含以下参数:

名称 类型 说明
ret_code int 查询状态返回码,0为查询正确返回,1为查询错误返回
ret_message string 查询返回结果,即展示给用户的信息,支持基本的html标签,包括图片、文字字体及排版代码等。

接口返回数据示例:

{
    "ret_code": 0,
    "ret_message": "今天是星期3,农历二月初四,现在温度为:5℃,湿度为:12,风向为:北风,风力为:3级。"   
}

四.其他注意事项

1.接口调用超时时长

当调用接口在2000毫秒内没有返回有效结果时,机器人将判定接口调用超时,向用户展示调用超时说明。

2.编码格式

在进行接口调用时,机器人将以UTF-8格式进行编码传递参数。对于接口返回数据,也应使用UTF-8编码。

3.返回答案长度

建议返回的答案内容长度在2000字以内。过长的答案会影响用户阅读的效率,也不利于进行展示。

4.接口调用问题创建数量

对于单个机器人最多创建20个接口调用类型的问题。

results matching ""

    No results matching ""