# 机器人
# 服务先知-常见问题
当访客链接七鱼机器人时,七鱼服务器会调用第三方预判接口,获取企业对该访客的预判信息,该预判信息会展示在热门问题处。调用时会将访客的第三方标识id和访客当前所处页面作为参数调用企业预判接口,调用方式如下: 1·使用POST方式请求企业预判接口 2·接口请求的Content-Type为:application/x-www-form-urlencoded;charset=utf-8 3·调用校验,在调用预判接口时,七鱼会将appSecret,time,nonce三个参数使用sha1哈希算法生成checkSum校验和(同消息接口checksum校验和示例代码),其中timestamp为精确到秒的时间戳,nonce为一串随机生成的字符串,参数放在Http Request Header中传输 请求参数说明:
参数 | 参数类型 | 参数说明 |
---|---|---|
appId | String | 企业分配给七鱼的appId |
nonce | String | 描述信息 |
time | Long | 当前UTC时间戳,精确到秒数 |
checkSum | String | SHA1(appSecret + nonce + time),将三个参数按appSecret、nonce、 time,并转化成16进制的小写字符串作为checkSum |
userId | String | 开发者的应用里的用户ID,通过CRM接入同步给七鱼 |
fromPage | String | 访客进入机器人的页面链接 |
content | String | 访客在机器人会话中发送的单条消息内容 |
keyword | String | 触发机器人会话转接的关键词 |
- 企业接口返回说明
返回类型为JSON,同时进行UTF-8编码
参数 | 数据类型 | 必填 | 说明 |
---|---|---|---|
guide | String | 否 | 进入机器人时的引导语,字数上限200个字。如果当前值为空,将依次选择服务先知引导语、常见问题引导语之一作为引导语。当接口仅返回引导语不返回问题时,结果无效。 |
faq | Array | 否 | 对于放置在问题列表的数据,放在faq这一参数内返回。如果企业faq参数返回不为空并且在20个以上,展示faq参数结果;如果faq参数不为空且返回在20个以下,则由置顶问题补全至20个;如果企业faq参数返回为空,若设置了常见问题则展示常见问题,若未设置常见问题则展示置顶问题。 |
例:
{
"guide":"欢迎引导语",
"faq": [
"热门问题1",
"热门问题2",
"热门问题3"
]
}
# 服务先知-快捷短语
当访客链接七鱼机器人时,七鱼服务器会调用第三方预判接口,获取企业对该访客的预判信息,该预判信息会展示在输入框上方。调用时会将访客的第三方标识id和访客当前所处页面作为参数调用企业预判接口,调用方式同服务先知-常见问题:
- 企业接口返回说明
返回类型为JSON,同时进行UTF-8编码
参数 | 数据类型 | 必填 | 说明 |
---|---|---|---|
bot | Array | 否 | 对于放置在服务直达的数据,放在bot这一参数内返回。最后按顺序依次展示企业返回bot参数、服务先知算法接口(需要开启先知算法开关)、企业运营后台配置参数,重复问题将会被过滤。 |
例:
{
"bot": [
"查物流",
"查退款",
"查订单"
]
}
# 一触即达
本文档为一触即达接入文档,企业根据不同业务模块,使用一触即达功能需要实现对应模块的http查询接口。 根据企业是否允许匿名访客查询,调用查询接口方式分为匿名访客查询和有名访客查询,匿名访客是指企业未做过CRM信息对接的访客,匿名访客查询是允许所有连接到机器人客服的访客使用该查询接口,有名访客查询是只允许做过CRM信息对接的访客才可使用该查询。但查询某些信息时(如查订单等需要用户唯一标识的查询)必须要企业提供访客唯一标识,即企业需通过CRM信息对接提供给七鱼。
# 对接方式
说明:所有接口均需符合七鱼对企业接口的请求格式规范和返回格式规范,其规范见下文。 目前七鱼调用第三方接口时会加上的鉴权方式有两种,一是token校验(复用CRM信息对接里获取token的接口,若能获取到token则使用该token,获取不到token则不使用,此种需企业提供appId,appSecret和获取token的接口),另一种是checkSum校验,需企业提供appId和appSecret,生成checkSum方式见下文。企业可依据不同模块情况采用任意校验方式,或不使用身份校验。
- 企业接口请求说明
- 获取token接口的请求方式同CRM对接文档里相同;
- 一触即达的所有接口请求均为POST请求;
- 一触即达的所有接口请求的Content-Type类型均为:application/x-www-form-urlencoded;charset=utf-8。 例:
POST https://qiyeserver/... HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8
- 企业接口返回说明
返回字段定义:
参数 | 是否必填 | 参数说明 |
---|---|---|
code | 是 | 请求的返回码 |
desc | 否 | 描述信息 |
result | 是 | 接口调用结果 |
- 所有一触即达企业接口的返回类型为JSON,同时进行UTF-8编码;
- 接口的返回值在result字段里,可以是任何对象,只有code=200时才认为调用成功,并使用result字段里的内容做后续操作。 例:
{
"code": 200,
"desc": "success",
"result": {
"id": "123456",
"name": "hello world",
"address": "浙江省杭州市滨江区长河街道网商路599号网易大厦"
}
}
- 接口调用流程
- 若接口不需请求校验并对所有人开放,则接口只需符合上文所列的请求和返回规范即可。
- 分配appId和appSecret,企业需在页面:接入设置->信息对接->CRM信息对接处填写给七鱼分配的appId和appSecret用于获取token和生成checkSum校验;
- 若企业设置了获取token接口,并且七鱼成功获取到token后,会在七鱼调用企业一触即达接口时将token作为参数带上;
- 七鱼在调用企业接口时,将appSecret,time,nonce三个参数使用sha1哈希算法生成checkSum校验和(同消息接口checksum校验和示例代码),其中time为精确到秒的时间戳,nonce为一串随机生成的字符串,参数放在Http Request Header中传输;
- POST请求调用第三方接口,七鱼会带上的请求参数有:userId(String字符串类型),plgCode(String字符串类型),params(Map键值对类型,包含请求所需参数,需要企业在一触即达查询节点里进行设置),请求参数放在请求体里。
- 参数说明
参数 | 是否必填 | 参数说明 |
---|---|---|
appId | 是 | 企业分配给七鱼的appId |
nonce | 是 | 随机字符串(最大长度128个字符) |
time | 是 | 当前UTC时间戳,精确到秒数 |
checkSum | 是 | SHA1(appSecret + nonce + time),将三个参数按appSecret、nonce、 time顺序拼接成的字符串计算SHA1哈希值,并转化成16进制的小写字符串作为checkSum |
userId | 是 | 开发者的应用里的用户ID,通过CRM接入同步给七鱼 |
plgCode | 是 | 七鱼要调用的对应模块名称 |
params | 是 | 调用第三方接口的参数列表,企业在一触即达的查询节点里进行配置 |
token | 否 | 获取到的企业token |
# 对接示例
模板id | 说明 | SDK支持版本 |
---|---|---|
01 | 文本 | 不限 |
02 | 文本+按钮列表 | 不限 |
drawer_list | 抽屉列表 | >=5.1.0 |
bubble_list | 气泡列表 | >=5.1.0 |
bubble_node_list | 气泡节点列表 | >=5.1.0 |
horizontal_sliding_list | 横滑卡片 | >=5.1.0 |
注:其他端不受版本限制
# 示例 1:文本
在一触即达的流程中,根据企业在节点中设置的提取变量,结合企业接口地址,获取文本消息并填充到模板中,返回示例为:
{
"code": 200,
"desc": "success",
"result": {
"data": {
"item_list": [
{
"item_type": 0,
"label": "七鱼客服bot对接"
},
{
"item_type": 1,
"label": "<a href="http://qiyukf.netease.com/">七鱼客服</a>"
}
]
}
}
}
- 字段说明
参数 | 类型 | 必传 | 说明 |
---|---|---|---|
item_type | Int | 是 | 文本类型,0-普通文本,1-富文本 |
label | String | 是 | 文本内容 |
- xml模板填充样式
<template id="01">
#if(${data.item_list} && ${data.item_list.size()} > 0)
#foreach($item in $!{data.item_list})
<LinearLayout>
#if($!{item.item_type} == 0)
<text name="label">$!{item.label}</text>
#else
<richText name="label">$!{item.label}</richText>
#end
</LinearLayout>
#end
#end
</template>
# 示例 2:文本+按钮列表
本模板为文本模板升级版,支持文本+按钮列表的样式。在一触即达的流程中,根据企业在节点中设置的提取变量,结合企业接口地址,获取文本消息并填充到模板中,返回示例为:
{
"code": 200,
"desc": "success",
"result": {
"data": {
"introducer": "引导语",
"item_list": [
{
"item_type": "0",
"label": "按钮1",
"params": "orderNo=0"
},
{
"item_type": "1",
"label": "按钮2",
"target": "http://qiyukf.netease.com",
"params": "orderNo=0"
}
]
}
}
}
- 字段说明
参数 | 类型 | 必传 | 说明 |
---|---|---|---|
introducer | String | 否 | 引导语文案 |
item_list | Array | 是 | 按钮列表 |
- 按钮字段说明
参数 | 类型 | 必传 | 说明 |
---|---|---|---|
item_type | Int | 是 | 按钮类型,0-跳转至下一个节点,1-跳转至外部链接 |
label | String | 是 | 按钮文案 |
params | String | 否 | 点击item跳转时携带的参数 |
target | String | 否 | 跳转至下一个节点时可不传target,跳转至外部链接时需配置链接地址 |
- xml模板填充样式
<template id="02">
<LinearLayout>
<text name="label">$!{data.introducer}</text>
</LinearLayout>
#if(${data.item_list} && ${data.item_list.size()} > 0)
#foreach(${item} in $!{data.item_list})
#if($!{item.item_type} == 0)
<LinearLayout>
<link type="block" style="button" target="${xml_nfid_block_1}" params="$!{item.params}">
<text name="label">$!{item.label}</text>
</link>
</LinearLayout>
#else
<LinearLayout>
<link type="url" style="button" target="$!{item.target}" params="$!{item.params}">
<text name="label">$!{item.label}</text>
</link>
</LinearLayout>
#end
#end
#end
</template>
# 示例 3:抽屉列表
抽屉列表可以用于展示订单列表或商品列表,支持展示图文内容,也支持仅展示文字内容,样式如图:
如果需要返回抽屉列表内容,企业需要在一触即达查询节点内配置接口,并加入固定入参tabId,currentPage(代表当前要请求第几页),pageSize(代表每页的大小是多少)。拉取抽屉列表时,七鱼调用企业服务器,例如:tabId=1,currentPage=1,pageSize=5,代表拉取第1个分组的第1页共5条数据(注意:若params包含的参数为空,默认拉取第1个分组的第1页共5条数据,即相当于tabId=1,currentPage=1,pageSize=5)。企业可以自定义pageSize,默认值为5,最大不超过10。tabId和currentPage可以根据访客的点选动态赋值。在一触即达查询节点中的配置如下:
result返回值为企业订单列表的JSON数组,返回示例:
{
"code": 200,
"desc": "success",
"result": {
"data": {
"tab_id": 1,
"current_page": 1,
"page_size": 5,
"introducer": "请选择您想咨询的订单",
"banner": "选择咨询的订单",
"empty_list_hint": "无数据返回提示文案aaa",
"tab1":{
"name": "分组1",
"item_list": [
{
"item_type": "1",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "考拉海购",
"sub_title": "卖家已发货"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克777",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克888",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
},
{
"item_type": "1",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "网易严选",
"sub_title": "卖家已发货"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克999",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克000",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
}
]
},
"tab2":{
"name": "分组2",
"item_list": []
},
"tab3":{
"name": "分组3",
"item_list": []
},
"tab4":{
"name": "分组4",
"item_list": []
}
}
}
}
- 字段说明
参数 | 类型 | 必传 | 说明 |
---|---|---|---|
tab_id | Int | 是 | 当前列表分组id,从params中获取,若params为空,默认为1 |
current_page | Int | 是 | 当前页,从params中获取,若params为空,默认为1 |
page_size | Int | 是 | 每页数据条数,从params中获取,若params为空,默认为5,最多不超过10条 |
introducer | String | 是 | 引导语,不可为空值 |
banner | String | 否 | 提示语 |
empty_list_hint | String | 是 | 无数据返回提示文案,不可为空值 |
tab1 | Object | 是 | 列表分组1,对应分组id为1 |
tab2 | Object | 否 | 列表分组2,对应分组id为2 |
tab3 | Object | 否 | 列表分组3,对应分组id为3 |
tab4 | Object | 否 | 列表分组4,对应分组id为4 |
列表分组tab格式说明:
参数 | 类型 | 必传 | 说明 |
---|---|---|---|
name | String | 否 | 列表分组名称,如果不传则不展示该行内容 |
item_list | Array | 是 | 列表分组中item分组数据和item详细数据 |
item分组数据(item_type=1
)格式说明:
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
item_type | String | 是 | 值固定为1 |
img | String | 否 | 缩略图地址 |
title | String | 否 | 标题,可以为空 |
sub_title | String | 否 | 副标题 |
item详细数据(item_type=0
)格式说明:
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
item_type | String | 是 | 值固定为0 |
img | String | 否 | 缩略图地址 |
title | String | 否 | 标题 |
sub_title | String | 否 | 副标题 |
attr_1 | String | 否 | 属性1 |
attr_2 | String | 否 | 属性2 |
attr_3 | String | 否 | 属性3 |
params | String | 否 | 点击item跳转时携带的参数 |
target | String | 否 | 点击item的跳转目标地址或目标节点,若仅展示列表内容可以为空 |
注意事项:
<1> 为了降低企业对接难度和简化分页处理,item分组与item采用混排平铺的方式实现分组效果,item分组被当做一个特殊的item,两者的区别是item_type不同
<2> 抽屉列表要求至少包含一个列表分组,即tab1。当包含多个分组时,每次返回结果只需包含当前请求分组的item_list字段,但是需要填充其他分组的name字段。例如存在3个列表分组的情况下,在请求分组1的数据时,除了要填充tab1.name,tab1.item_list外,还需要填充tab2.name,tab3.name。
- xml模板填充样式
<template id="drawer_list">
<LinearLayout>
<text name="label">$!{data.introducer}</text>
<text name="empty_list_hint">$!{data.empty_list_hint}</text>
<text name="tab_id">$!{data.tab_id}</text>
<text name="title">$!{data.banner}</text>
</LinearLayout>
<group>
<tab>
<text name="tab_name">$!{data.tab1.name}</text>
</tab>
#if(1 == ${data.tab_id} && ${data.tab1.item_list} && ${data.tab1.item_list.size()} > 0)
#foreach(${item} in $!{data.tab1.item_list})
<LinearLayout>
<text name="p_item_type">$!{item.item_type}</text>
<link type="block" style="button" target="${xml_nfid_block_1}" params="$!{item.params}">
<image name="p_img" url="$!{item.img}"/>
<text name="p_title">$!{item.title}</text>
<text name="p_sub_title">$!{item.sub_title}</text>
<text name="p_attr_1">$!{item.attr_1}</text>
<text name="p_attr_2">$!{item.attr_2}</text>
<text name="p_attr_3">$!{item.attr_3}</text>
</link>
</LinearLayout>
#end
#end
#if(1 == ${data.tab_id})
#set($page_1 = ${data.current_page} + 1)
#else
#set($page_1 = 1)
#end
<action>
<link type="block" style="button" target="${xml_nfid_block_self}" params="tabId=1¤tPage=$!{page_1}&pageSize=5" >
<text name="label">查看更多</text>
</link>
</action>
</group>
<group>
<tab>
<text name="tab_name">$!{data.tab2.name}</text>
</tab>
#if(2 == ${data.tab_id} && ${data.tab2.item_list} && ${data.tab2.item_list.size()} > 0)
#foreach(${item} in $!{data.tab2.item_list})
<LinearLayout>
<text name="p_item_type">$!{item.item_type}</text>
<link type="block" style="button" target="${xml_nfid_block_2}" params="$!{item.params}">
<image name="p_img" url="$!{item.img}"/>
<text name="p_title">$!{item.title}</text>
<text name="p_sub_title">$!{item.sub_title}</text>
<text name="p_attr_1">$!{item.attr_1}</text>
<text name="p_attr_2">$!{item.attr_2}</text>
<text name="p_attr_3">$!{item.attr_3}</text>
</link>
</LinearLayout>
#end
#end
#if(2 == ${data.tab_id})
#set($page_2 = ${data.current_page} + 1)
#else
#set($page_2 = 1)
#end
<action>
<link type="block" style="button" target="${xml_nfid_block_self}" params="tabId=2¤tPage=$!{page_2}&pageSize=5" >
<text name="label">查看更多</text>
</link>
</action>
</group>
<group>
<tab>
<text name="tab_name">$!{data.tab3.name}</text>
</tab>
#if(3 == ${data.tab_id} && ${data.tab3.item_list} && ${data.tab3.item_list.size()} > 0)
#foreach(${item} in $!{data.tab3.item_list})
<LinearLayout>
<text name="p_item_type">$!{item.item_type}</text>
<link type="display" style="button" >
<image name="p_img" url="$!{item.img}"/>
<text name="p_title">$!{item.title}</text>
<text name="p_sub_title">$!{item.sub_title}</text>
<text name="p_attr_1">$!{item.attr_1}</text>
<text name="p_attr_2">$!{item.attr_2}</text>
<text name="p_attr_3">$!{item.attr_3}</text>
</link>
</LinearLayout>
#end
#end
#if(3 == ${data.tab_id})
#set($page_3 = ${data.current_page} + 1)
#else
#set($page_3 = 1)
#end
<action>
<link type="block" style="button" target="${xml_nfid_block_self}" params="tabId=3¤tPage=$!{page_3}&pageSize=5" >
<text name="label">查看更多</text>
</link>
</action>
</group>
<group>
<tab>
<text name="tab_name">$!{data.tab4.name}</text>
</tab>
#if(4 == ${data.tab_id} && ${data.tab4.item_list} && ${data.tab4.item_list.size()} > 0)
#foreach(${item} in $!{data.tab4.item_list})
<LinearLayout>
<text name="p_item_type">$!{item.item_type}</text>
<link type="url" style="button" target="$!{item.target}" params="$!{item.params}">
<image name="p_img" url="$!{item.img}"/>
<text name="p_title">$!{item.title}</text>
<text name="p_sub_title">$!{item.sub_title}</text>
<text name="p_attr_1">$!{item.attr_1}</text>
<text name="p_attr_2">$!{item.attr_2}</text>
<text name="p_attr_3">$!{item.attr_3}</text>
</link>
</LinearLayout>
#end
#end
#if(4 == ${data.tab_id})
#set($page_4 = ${data.current_page} + 1)
#else
#set($page_4 = 1)
#end
<action>
<link type="block" style="button" target="${xml_nfid_block_self}" params="tabId=4¤tPage=$!{page_4}&pageSize=5" >
<text name="label">查看更多</text>
</link>
</action>
</group>
</template>
# 示例 4:气泡列表
气泡列表可以用于展示订单列表或商品列表,支持展示图文内容,也支持仅展示文字内容,样式如图:
如果需要返回气泡列表内容,企业需要在一触即达查询节点内配置接口,并加入固定入参currentPage,pageSize。拉取列表时,七鱼调用企业服务器,例如:currentPage=1,pageSize=5,代表拉取第1页共5条数据(注意:若params包含的参数为空,默认拉取的第1页共5条数据,即相当于currentPage=1,pageSize=5)。企业可以自定义pageSize,默认值为5,最大不超过10。currentPage可以根据访客的点选动态赋值。一触即达查询节点的配置请参看上文抽屉列表示例部分。
result返回值为企业订单列表的JSON数组,返回示例:
{
"code": 200,
"desc": "success",
"result": {
"data": {
"current_page": 1,
"page_size": 5,
"introducer": "请选择您想咨询的订单",
"banner": "选择咨询的订单",
"empty_list_hint": "无数据返回提示文案aaa",
"tab1":{
"item_list": [
{
"item_type": "1",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "item分组",
"sub_title": "卖家已发货"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克777",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克888",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
},
{
"item_type": "1",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "item分组",
"sub_title": "卖家已发货"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克999",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克000",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
}
]
}
}
}
}
- 字段说明
参数 | 类型 | 必传 | 说明 |
---|---|---|---|
current_page | Int | 是 | 当前页,从params中获取,若params为空,默认为1 |
page_size | Int | 是 | 每页数据条数,从params中获取,若params为空,默认为5,最多不超过10条 |
introducer | String | 是 | 引导语,不可为空值 |
banner | String | 否 | 提示语 |
empty_list_hint | String | 是 | 无数据返回提示文案,不可为空值 |
tab1 | Object | 是 | 列表分组,气泡列表仅支持一个列表分组 |
列表分组格式说明:
参数 | 类型 | 必传 | 说明 |
---|---|---|---|
item_list | Array | 是 | 列表分组中item分组数据和item详细数据 |
item分组数据(item_type=1
)格式说明:
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
item_type | String | 是 | 值固定为1 |
img | String | 否 | 缩略图地址 |
title | String | 否 | 标题,可以为空 |
sub_title | String | 否 | 副标题 |
item详细数据(item_type=0
)格式说明:
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
item_type | String | 是 | 值固定为0 |
img | String | 否 | 缩略图地址 |
title | String | 否 | 标题 |
sub_title | String | 否 | 副标题 |
attr_1 | String | 否 | 属性1 |
attr_2 | String | 否 | 属性2 |
attr_3 | String | 否 | 属性3 |
params | String | 否 | 点击item跳转时携带的参数 |
target | String | 否 | 点击item的跳转目标地址或目标节点,若仅展示列表内容可以为空 |
- xml模板填充样式
<template id="bubble_list">
<LinearLayout>
<text name="label">$!{data.introducer}</text>
<text name="empty_list_hint">$!{data.empty_list_hint}</text>
<text name="title">$!{data.banner}</text>
</LinearLayout>
<group>
#if(${data.tab1.item_list} && ${data.tab1.item_list.size()} > 0)
#foreach(${item} in $!{data.tab1.item_list})
<LinearLayout>
<text name="p_item_type">$!{item.item_type}</text>
<link type="block" style="button" target="${xml_nfid_block_1}" params="$!{item.params}">
<image name="p_img" url="$!{item.img}"/>
<text name="p_title">$!{item.title}</text>
<text name="p_sub_title">$!{item.sub_title}</text>
<text name="p_attr_1">$!{item.attr_1}</text>
<text name="p_attr_2">$!{item.attr_2}</text>
<text name="p_attr_3">$!{item.attr_3}</text>
</link>
</LinearLayout>
#end
#end
#set($page = ${data.current_page} + 1)
<action>
<link type="block" style="button" target="${xml_nfid_block_self}" params="currentPage=$!{page}&pageSize=5" >
<text name="label">查看更多</text>
</link>
</action>
</group>
</template>
# 示例 5:横滑卡片列表
横滑卡片列表可以用于展示商品列表,支持展示图文内容,样式如下:
如果需要返回横滑卡片列表内容,企业需要在一触即达查询节点内配置接口,并加入固定入参currentPage,pageSize。拉取列表时,七鱼调用企业服务器,例如:currentPage=1,pageSize=5,代表拉取第1页共5条数据(注意:若params包含的参数为空,默认拉取的第1页共5条数据,即相当于currentPage=1,pageSize=5)。企业可以自定义pageSize,默认值为5,最大不超过10。currentPage可以根据访客的点选动态赋值。一触即达查询节点的配置请参看上文抽屉列表示例部分。
result返回值为企业订单列表的JSON数组,返回示例:
{
"code": 200,
"desc": "success",
"result": {
"data": {
"current_page": 1,
"page_size": 5,
"introducer": "引导语aaa",
"empty_list_hint": "无数据返回提示文案aaa",
"tab1":{
"item_list": [
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克777",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克888",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/TB2Zo._a5GO.eBjSZFjXXcU9FXa_!!2228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克999",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
},
{
"item_type": "0",
"img": "https://img.alicdn.com/imgextra/i2/2228361831/12228361831.jpg",
"title": "1ZARA 女装 加大码飞行员夹克000",
"sub_title": "1ZARA 女装 加大码飞行员夹克",
"attr_1": "100",
"attr_2": "100",
"attr_3": "100",
"target": "http://www.baidu.com",
"params": "orderNo=0"
}
]
}
}
}
}
- 字段说明
参数 | 类型 | 必传 | 说明 |
---|---|---|---|
current_page | Int | 是 | 当前页,从params中获取,若params为空,默认为1 |
page_size | Int | 是 | 每页数据条数,从params中获取,若params为空,默认为5,最多不超过5条 |
introducer | String | 是 | 引导语,不可为空值 |
empty_list_hint | String | 是 | 无数据返回提示文案,不可为空值 |
tab1 | Object | 是 | 列表分组,横滑卡片列表仅支持一个列表分组 |
列表分组格式说明:
参数 | 类型 | 必传 | 说明 |
---|---|---|---|
item_list | Array | 是 | 列表分组中的item详细数据 |
item分组数据(item_type=1
)格式说明:
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
item_type | String | 是 | 值固定为1 |
img | String | 否 | 缩略图地址 |
title | String | 否 | 标题,可以为空 |
item详细数据(item_type=0
)格式说明:
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
item_type | String | 是 | 值固定为0 |
img | String | 否 | 缩略图地址 |
title | String | 否 | 标题 |
sub_title | String | 否 | 副标题 |
attr_1 | String | 否 | 属性1 |
attr_2 | String | 否 | 属性2 |
attr_3 | String | 否 | 属性3 |
params | String | 否 | 点击item跳转时携带的参数 |
target | String | 否 | 点击item的跳转目标地址或目标节点,若仅展示列表内容可以为空 |
注意事项:
<1> 横滑卡片的数据填充企业可以按两种模式处理:一种是传统的分页模式,此时currentPage代表页码;一种是随机模式,此时currentPage代表轮次,可以随机返回item。企业可以根据不同场景选择合适的模式。
- xml模板填充样式
<template id="horizontal_sliding_list">
<LinearLayout>
<text name="label">$!{data.introducer}</text>
<text name="empty_list_hint">$!{data.empty_list_hint}</text>
</LinearLayout>
#if(${data.tab1.item_list} && ${data.tab1.item_list.size()} > 0)
#foreach(${item} in $!{data.tab1.item_list})
<LinearLayout>
<link type="block" style="button" target="${xml_nfid_block_1}" params="$!{item.params}">
<image name="p_img" url="$!{item.img}"/>
<text name="p_title">$!{item.title}</text>
<text name="p_sub_title">$!{item.sub_title}</text>
<text name="p_attr_1">$!{item.attr_1}</text>
<text name="p_attr_2">$!{item.attr_2}</text>
<text name="p_attr_3">$!{item.attr_3}</text>
</link>
</LinearLayout>
#end
#end
#set($page = ${data.current_page} + 1)
<action>
<link type="block" style="button" target="${xml_nfid_block_self}" params="currentPage=$!{page}&pageSize=5" >
<text name="label">换一批</text>
</link>
</action>
</template>
# 示例 6:气泡节点列表
气泡节点列表可以实现类似时间轴列表的效果,可以用于展示物流信息,企业也可以根据自己的需求灵活定制,样式如下:
拉取气泡节点列表时,七鱼调用企业服务器,目前不用在一触即达查询节点的接口配置中设置固定入参。result返回值为订单列表的JSON数组,返回示例为:
{
"code": 200,
"desc": "success",
"result": {
"data":
{
"introducer": "引导语",
"empty_list_hint": "无数据返回提示文案",
"banner": "标题",
"footer": "查看更多",
"target": "https://qiyukf.com",
"item_list": [
{
"title": "业务员二片区岸上蓝山正在第1次派件",
"desc": "2017-05-17 18:01:38",
"is_current": "1"
},
{
"title": "业务员二片区岸上蓝山正在第2次派件",
"desc": "2017-05-17 18:01:38",
"is_current": "0"
},
{
"title": "业务员二片区岸上蓝山正在第3次派件",
"desc": "2017-05-17 18:01:38",
"is_current": "0"
},
{
"title": "业务员二片区岸上蓝山正在第4次派件",
"desc": "2017-05-17 18:01:38",
"is_current": "0"
},
{
"title": "业务员二片区岸上蓝山正在第5次派件",
"desc": "2017-05-17 18:01:38",
"is_current": "0"
},
{
"title": "业务员二片区岸上蓝山正在第6次派件",
"desc": "2017-05-17 18:01:38",
"is_current": "0"
},
{
"title": "业务员二片区岸上蓝山正在第7次派件",
"desc": "2017-05-17 18:01:38",
"is_current": "0"
}
]
}
}
}
- 字段说明
参数 | 类型 | 必传 | 说明 |
---|---|---|---|
introducer | String | 是 | 引导语,不可为空值 |
banner | String | 否 | 标题 |
footer | String | 否 | 自定义底部按钮的提示语,默认“查看更多” |
target | String | 否 | 如果底部按钮的跳转事件设置为跳转到外链,此处传入外链的链接地址 |
empty_list_hint | String | 是 | 无数据返回提示文案,不可为空值 |
item_list | Array | 是 | 列表 |
item数据格式说明:
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
title | String | 否 | 标题 |
desc | String | 否 | 描述 |
is_current | String | 是 | 是否停留在当前节点:1-是 0-否 |
- xml模板填充样式
<template id="bubble_node_list">
<LinearLayout>
<text name="label">$!{data.introducer}</text>
<text name="empty_list_hint">$!{data.empty_list_hint}</text>
<text name="title">$!{data.banner}</text>
</LinearLayout>
<LinearLayout>
<text name="label">$!{data.title}</text>
</LinearLayout>
#if(${data.item_list} && ${data.item_list.size()} > 0)
#foreach($item in $!{data.item_list})
<LinearLayout>
<text name="p_title">$!{item.title}</text>
<text name="p_desc">$!{item.desc}</text>
<text name="p_is_current">$!{item.is_current}</text>
</LinearLayout>
#end
</LinearLayout>
#end
<action>
<link type="url" style="button" target="$!{data.target}"">
<text name=\"label\">${data.footer}</text>
</link>
</action>
</template>
# Velocity语法赋值
如果企业需要定制一触即达输出的样式,企业需要与七鱼预先约定字段,并在一触即达中配置xml填充信息。配置xml时可参考以上xml模版填充样式。xml模版同时支持Velocity语法赋值,内容如下:
- 赋值
$!{参数名称}
- 遍历
#foreach ($item in $list)
#end
- 注:当接口返回结果的result结果为数组时,$list 可以直接是用 $result 赋值遍历。
#foreach ($item in $result)
#end
- 条件
#if($(orderDto))
订单对象有值
#else
订单对象为空
#end
#if(!$(orderDto))
订单对象为空
#else
订单对象有值
#end
- 变量约定
参数具体指代 | 约定在xml中的velocity的变量名称 | 样例 |
---|---|---|
跳转至节点本身 | xml_nfid_block_self | target="${xml_nfid_block_self}" |
跳转至其他节点 | 前缀:xml_nfid_block_+后缀:1-2位数字 | target="${xml_nfid_block_1}" |
跳转至url地址 | 前缀:xml_nfid_url_+后缀:1-2位数字 | params="nodeId=${xml_nfid_url_1}" target="http://www.baidu.com" |
# 移动SDK接入指南
- Android 接入指南
compile 'com.qiyukf.unicorn:unicorn:3.10.0'
2.在SDK初始化时,为 YSFOptions
的 onBotEventListener
赋值:
// ... your codes
// YSFOptions options = new YSFOptions();
options.onBotEventListener = new OnBotEventListener() {
@Override
public boolean onUrlClick(Context context, String url) {
// 加入处理一触即达url的代码
BrowserActivity.start(context, url);
return true;
}
};
// Unicorn.init(this, "appKey", options, new UnicornImageLoader());
// ... your codes
- IOS 接入指南
1.需要的 iOS SDK 版本是 v3.10.0 或以上
2.自定义 bot 点击事件处理:
QYCustomActionConfig *actionConfig = [[QYSDK sharedSDK] customActionConfig];
//botClick 是 bot 相关点击回调
actionConfig.botClick =【你的代码】
# 知识库管理
获取知识库接口为分页获取全量数据,一次获取全量数据可分多页请求进行。下一次获取全量数据时,限制请求间隔大于30分钟。
# 获取知识库的问题
POST请求格式:
https://qiyukf.com/openapi/robot/data/knowledge?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容如下:
{
"mid":0,
"size":500
}
接口参数说明:
参数 | 是否必须 | 参数说明 |
---|---|---|
mid | 否 | 分页批量拉取企业知识库数据,根据本页拉取到的记录中最大的id作为下一页数据起始点,默认值0 |
size | 否 | 每页拉取的知识库记录数量,一次最多拉取1000条,默认值200 |
返回值说明:
{
"code":200,
"message":"{..}"
}
其中message说明如下:
{
"total":1100, // 企业知识库记录总数
"isEnd":0, // 是否已全部读取完 0-还有数据待读取 1-已全部读取完
"data":[{ // 本次读取的数据内容
"id":123, // 七鱼知识库记录id
"question":"问题1", // 问题
"md5":"rfddewrdsa", // 问题的md5
"answer":"问题1-答案", // 问题的对外答案
"innerAnswer":"对内答案", // 问题的对内答案
"faqType":0, // 问题答案类型,0只有对外答案,1只有对内答案,2同时有对内和对外答案
"fromType":0, // 问题的来源,0:用户手动添加,1:寒暄库,2:文件导入
"updateTime":1522222222, // 问题更新时间
"type":1, // 问题类型,1:标准问题,10:相似问题
"refId":123, // 相似问题(type=10)对应的标准问题id
"connectIds":[1,2], // 关联的问题id列表
"categoryInfo":[{ // 知识点所属分类,从顶级分类到子级分类
"categoryId":101, // 分类id
"categoryName":"分类1" // 分类名
}],
"pointId":123, // 问题对应的知识点id
"enabled":0, // 是否有效标记位,0-失效,1-有效
"effectiveTime":"2018-01-13 16:01:50", // 问题的有效开始时间(enabled=1且有效时间为空说明永久有效,enabled=1且有效时间不为空说明该时间内有效)
"failureTime":"2018-08-13 16:01:50" // 问题的失效时间
}]
}
备注: 分页读取知识库数据,每页返回的数据按id从小到大排序; 读取下一页数据时,需要将本次读取的数据中最后一条记录id,作为读取下一页数据的参数mid传过来;
# 获取知识库的知识点
POST请求格式:
https://qiyukf.com/openapi/robot/data/kpoint?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容如下:
{
"mid":0,
"size":500
}
接口参数说明:
参数 | 是否必须 | 参数说明 |
---|---|---|
mid | 否 | 分页批量拉取企业知识库数据,根据本页拉取到的记录中最大的id作为下一页数据起始点,默认值0 |
size | 否 | 每页拉取的知识库记录数量,一次最多拉取1000条,默认值200 |
返回值说明:
{
"code":200,
"message":"{..}"
}
其中message说明如下:
{
"total":1100, // 企业知识库知识点记录总数
"isEnd":0, // 是否已全部读取完 0-还有数据待读取 1-已全部读取完
"data":[{ // 本次读取的数据内容
"id":123, // 七鱼知识点记录id
"title":"知识点标题", // 知识点标题
"content":"知识点详情", // 知识点详细内容
"categoryInfo":[{ // 知识点所属分类,从顶级分类到子级分类
"categoryId":101, // 分类id
"categoryName":"分类1" // 分类名
}],
"updateTime":1522222222, // 更新时间
"enabled":0, // 是否有效标记位,0-失效,1-有效
"effectiveTime":"2018-01-13 16:01:50", // 知识点的有效开始时间(enabled=1且有效时间为空说明永久有效,enabled=1且有效时间不为空说明该时间内有效)
"failureTime":"2018-08-13 16:01:50" // 知识点的失效时间
}]
}
# 通过分类名称获取当前分类下topN标准问
POST请求格式:
https://qiyukf.com/openapi/robot/data/getQuestionsByCategoryName?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容如下:
{
"robotId":70718,
"startTime":1634969077000,
"endTime": 1635487477000,
"limit":500,
"categoryName":["一级分类","二级分类","三级分类","四级分类","五级分类"]
}
接口参数说明:
参数 | 是否必须 | 参数说明 |
---|---|---|
robotId | 是 | 机器人id |
startTime | 否 | 查询开始时间,默认值6天前的0点0分0秒 |
endTime | 否 | 查询结束时间。默认值当前时间 |
limit | 否 | 获取排名的前limit条数据,一次最多拉取1000条,默认值10 |
categoryName | 是 | 分类名称(完全匹配,最多五级分类) |
备注: 起始时间和结束时间的值必须大于0,起始时间需小于结束时间,结束时间不能晚于当前时间,查询时间跨度不能超31天
返回值说明:
{
"code":200,
"message":"success",
"data": "{..}"
}
其中data说明如下:
{
"data":[{ // 本次读取的数据内容
"question":"问题1" // 问题名称
}]
}
# 通过标准问获取当前机器人默认答案
POST请求格式:
https://qiyukf.com/openapi/robot/data/queryStandardByEffectiveQuestion?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容如下:
{
"robotId":70718,
"questionName":"问题1"
}
接口参数说明:
参数 | 是否必须 | 参数说明 |
---|---|---|
robotId | 是 | 机器人id |
questionName | 是 | 标准问题名称(完全匹配) |
返回值说明:
{
"code":200,
"message":"success",
"data": "{..}"
}
其中data说明如下:
{
"data":{ // 本次读取的数据内容
"answer":"答案1" // 机器人默认答案
}
}
# 通过常见问题模板id获取常见问题列表
该接口仅获取模板下默认分组的问题列表
POST请求格式:
https://qiyukf.com/openapi/robot/data/queryStandardQuestionList?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
请求内容如下:
{
"robotId":70718,
"templateId":123
}
接口参数说明:
参数 | 是否必须 | 参数说明 |
---|---|---|
robotId | 是 | 机器人id |
templateId | 是 | 模板id |
返回值说明:
{
"code":200,
"message":"success",
"data": "{..}"
}
其中data说明如下:
{
"data":[{ // 本次读取的数据内容
"question":"问题1" // 该模板下的标准问
}]
}
# 知识库分类查询接口
POST请求格式:
https://qiyukf.com/openapi/ai/knowledge/getCategoryTree?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
频率限制:
- 1次/秒
请求内容如下:
{
"robotId":70718
}
接口参数说明:
参数 | 是否必须 | 参数说明 |
---|---|---|
robotId | 是 | 机器人id |
返回值说明:
{
"code":200,
"message":"success",
"data": "{..}"
}
其中data说明如下:
{
"data":[{
"id": 1756744,
"name": "一级分类",
"children": [
{
"id": 1754263,
"name": "二级分类",
"children": null
}
]
}]
}
# 获取问题列表
POST请求格式:
https://qiyukf.com/openapi/ai/knowledge/search?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
频率限制:
- 1次/秒
请求内容如下:
{
"robotId":70718,
"keyWord":"问题1",
"categoryId":46546,
"pageSize":10,
"curPage":1
}
接口参数说明:
参数 | 是否必须 | 参数说明 |
---|---|---|
robotId | 是 | 机器人id |
keyWord | 否 | 搜索关键词 |
categoryId | 否 | 分类id |
pageSize | 否 | 分页每页大小[默认10,最大50] |
curPage | 否 | 当前页[默认1] |
返回值说明:
{
"code":200,
"message":"success",
"data": "{..}"
}
其中data说明如下:
{
"data":[{
"id": 1756744, //标准问题id
"name": "问题1", //标准问题name
"answer": "答案1", //问题答案
"categoryId": 243433, //分类id
"updateTime": 1628045813054, //最后更新时间,精确到毫秒
"questionStatus": 1, //问题状态 1-永久有效,2-有效期有效,有效期至xxx,3-失效 4-未生效
"validitySwitch": 1, //有效性开关 0停用,1启用
"effectiveTime": 1628045812345, //生效时间,精确到毫秒
"failureTime": 1628045815678 //失效时间,精确到毫秒
}]
}
# 获取问题详情信息
POST请求格式:
https://qiyukf.com/openapi/ai/knowledge/getDetail?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
频率限制:
- 10次/秒
请求内容如下:
{
"robotId":70718,
"knowledgeId":46546
}
接口参数说明:
参数 | 是否必须 | 参数说明 |
---|---|---|
robotId | 是 | 机器人id |
knowledgeId | 是 | 标准问id |
返回值说明:
{
"code":200,
"message":"success",
"data": "{..}"
}
其中data说明如下:
{
"data":[{
"id": 1756744, //标准问题id
"name": "问题1", //标准问题name
"answer": "答案1", //问题答案
"categoryId": 243433, //分类id
"similarityList": [ //相似问
{
"id": 1754263,
"name": "相似问题1"
}
],
"relatives": [ //关联问题
{
"id": 1754263,
"name": "关联问题1"
}
],
"channelAnswer": { //渠道答案
"type": 1,
"data": [ //渠道答案列表详情
{
"ruleValue": 129873,
"ruleDesc": "VIP客户",
"answer": "这是标签规则答案-000001"
},
{
"ruleValue": 129880,
"ruleDesc": "3星级客户",
"answer": "这是标签规则答案-0002222"
}
]
},
"updateTime": 1628045813054, //最后更新时间
"validitySwitch": 1, //有效性开关 0停用,1启用
"questionStatus": 1, //问题状态 1-永久有效,2-有效期有效,有效期至xxx,3-失效 4-未生效
"effectiveTime": 1628045812345, //生效时间
"failureTime": 1628045815678 //失效时间
}]
}
当规则答案类型为标签答案时 type = 1,channelAnswer的data节点数据格式为:
{
"ids": [1754263, 123444], // 客户标签id列表
"ruleDesc": "VIP客户标签/5星级客户",
"answer": "标签答案规则答案1"
}
当规则答案类型为渠道来源答案时 type = 2,channelAnswer的data节点数据格式为:
{
"from": "微信公众号/IOS-测试APP-页面1", // 渠道来源名称
"answer": "渠道来源答案规则答案2"
}
当规则答案类型为时效答案时 type = 3,channelAnswer的data节点数据格式为:
{
"effectiveTime": 1628045812345, // 生效时间
"failureTime": 1628045815678 // 失效时间
"ruleDesc": "1628045812345,1628045815678" // 生效时间, 失效时间
"answer": "时效答案规则答案3"
}
# 删除问题
POST请求格式:
https://qiyukf.com/openapi/ai/knowledge/deleteKnowledges?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
频率限制:
- 1次/秒
请求内容如下:
{
"robotId":70718,
"knowledgeIds":[46546,34321]
}
接口参数说明:
参数 | 是否必须 | 参数说明 |
---|---|---|
robotId | 是 | 机器人id |
knowledgeIds | 是 | 标准问id的集合 |
返回值说明:
{
"code":200,
"message":"success",
"data": [46546,46547] //返回删除失败的knowledgeId
}
# 添加问题
POST请求格式:
https://qiyukf.com/openapi/ai/knowledge/addKnowledge?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
频率限制:
- 1次/秒
请求内容如下:
{
"robotId":70718,
"name":"问题1",
"answer":"答案1",
"similars":["相似问1", "相似问2"],
"validitySwitch":1,
"effectiveTime":1628045813054,
"failureTime":1628045819876,
"categoryId":46546
}
接口参数说明:
参数 | 是否必须 | 参数说明 |
---|---|---|
robotId | 是 | 机器人id |
name | 是 | 问题name |
answer | 是 | 机器人答案,最大长度限制为3500字 |
similars | 是 | 相似问,可多个,如:["相似问1", "相似问2"],单个标准问你最多设置200个相似问;单个相似问最大长度限制为50字符 |
validitySwitch | 是 | 0-无效,1-(生效时间和失效时间都不为空表示有效期有效,否则永久有效 |
effectiveTime | 否 | 生效时间 Long类型,精确到毫秒,与failureTime需同时存在或同时不存在 |
failureTime | 否 | 失效时间Long类型,精确到毫秒,与effectiveTime需同时存在或同时不存在 |
categoryId | 是 | 分类id |
返回值说明:
{
"code":200,
"message":"success",
"requestId":"F2BCDE1E9A9C1D",
"data": 343434 //问题id
}
# 更新问题
POST请求格式:
https://qiyukf.com/openapi/ai/knowledge/editKnowledge?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
频率限制:
- 1次/秒
请求内容如下:
{
"id":454543,
"robotId":70718,
"name":"问题1",
"answer":"答案1",
"similars":["相似问1", "相似问2"],
"validitySwitch":1,
"effectiveTime":1628045813054,
"failureTime":1628045819876,
"categoryId":46546
}
接口参数说明:
参数 | 是否必须 | 参数说明 |
---|---|---|
robotId | 是 | 机器人id |
id | 是 | 更新的问题id |
name | 是 | 问题name |
answer | 是 | 答案,最大长度限制为3500字 |
similars | 否 | 相似问,可多个,如:["相似问1", "相似问2"],单个标准问你最多设置200个相似问;单个相似问最大长度限制为50字符,传[]清空相似问,不传该字段不更新 |
validitySwitch | 是 | 0-无效,1-生效时间和失效时间都不为空表示有效期有效,否则永久有效 |
effectiveTime | 否 | 生效时间 Long类型,精确到毫秒 |
failureTime | 否 | 失效时间Long类型,精确到毫 |
categoryId | 是 | 分类id |
返回值说明:
{
"code":200,
"message":"success",
"requestId":"F2BCDE1E9A9C1D",
"data": true
}
# 更新问题规则答案
POST请求格式:
https://qiyukf.com/openapi/ai/knowledge/editChannelAnswer?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
频率限制:
- 10次/秒
请求内容如下:
{
"robotId": 75002,
"knowledgeId": 5402184,
"ruleType": 1,
"channelAnswers": [
{
"ids": [
117201,
118032,
116239,
117199
],
"answer": "<ol><li>【春】初二数学课程介绍(下册课程) 1.适合<b>学员: 其他难度都已经停售 【创新班】(5星,需入学诊断,得分70-100可报):适合校内优秀,希望在数学方面有所拓展,积累一定课</b>外知识的学员。 2.版本信息如下:【全国版】 3.开课时间:3.5日/3.6日/3.7日开课 课程价格: 创新班:春季班16讲2880元,每一讲180分钟左右,课程中间有20分钟休息时间,每周一讲 4.可以1点击以下链接查看课程内容和课程详情: >>>【春】初二数学课程介绍-链接</li></ol>"
},
{
"ids": [
117093,
118034,
116240
],
"answer": "客户标签渠道答案"
}
]
}
接口参数说明:
参数 | 参数类型 | 是否必须 | 参数说明 |
---|---|---|---|
robotId | Long | 是 | 机器人id |
knowledgeId | Long | 是 | 标准问id |
ruleType | Integer | 是 | 规则答案类型 1:标签答案 |
channelAnswers | List | 是 | 规则答案详情列表,不能超过20个。 1.规则答案为空数组时则清空该标准问的规则答案。 2.规则答案不为空时,将该问题的规则答案更新为本次传的内容,历史内容清空 |
channelAnswers节点详情
参数 | 参数类型 | 是否必须 | 参数说明 |
---|---|---|---|
ids | Array | 是 | 规则详情 答案类型为标签答案时,填写客户标签id列表。 [1223477, 1223993] |
answer | String | 是 | 规则答案,最大长度限制3500字 |
返回值说明:
{
"code":200,
"message":"success",
"data": true
}
# 更新问题忽略相似问接口
POST请求格式:
https://qiyukf.com/openapi/ai/knowledge/editKnowledgeNoSimilars?appKey=[APP_KEY]&time=[TIME]&checksum=[CHECKSUM]
Content-Type:application/json;charset=utf-8
频率限制:
- 10次/秒
请求内容如下:
{
"id":454543,
"robotId":70718,
"question":"问题1",
"answer":"答案1",
"validitySwitch":1,
"effectiveTime":1628045813054,
"failureTime":1628045819876,
"categoryId":46546,
"ruleType": 1,
"channelAnswers": [
{
"ids": [
117201,
118032,
116239,
117199
],
"answer": "<ol><li>【春】初二数学课程介绍(下册课程) 1.适合<b>学员: 其他难度都已经停售 【创新班】(5星,需入学诊断,得分70-100可报):适合校内优秀,希望在数学方面有所拓展,积累一定课</b>外知识的学员。 2.版本信息如下:【全国版】 3.开课时间:3.5日/3.6日/3.7日开课 课程价格: 创新班:春季班16讲2880元,每一讲180分钟左右,课程中间有20分钟休息时间,每周一讲 4.可以1点击以下链接查看课程内容和课程详情: >>>【春】初二数学课程介绍-链接</li></ol>"
},
{
"ids": [
117093,
118034,
116240
],
"answer": "客户标签渠道答案"
}
]
}
接口参数说明:
参数 | 是否必须 | 参数说明 |
---|---|---|
robotId | 是 | 机器人id |
id | 是 | 更新的问题id |
question | 是 | 问题 |
answer | 是 | 答案,最大长度限制为3500字 |
validitySwitch | 是 | 0-无效,1-生效时间和失效时间都不为空表示有效期有效,否则永久有效 |
effectiveTime | 否 | 生效时间 Long类型,精确到毫秒 |
failureTime | 否 | 失效时间Long类型,精确到毫 |
categoryId | 是 | 分类id |
ruleType | 是 | 规则答案类型 1:标签答案 |
channelAnswers | 是 | 规则答案详情列表,不能超过20个。 1.规则答案为空数组时则清空该标准问的规则答案。 2.规则答案不为空时,将该问题的规则答案更新为本次传的内容,历史内容清空 |
channelAnswers节点详情
参数 | 参数类型 | 是否必须 | 参数说明 |
---|---|---|---|
ids | Array | 是 | 规则详情 答案类型为标签答案时,填写客户标签id列表。 [1223477, 1223993] |
answer | String | 是 | 规则答案,最大长度限制3500字 |
返回值说明:
{
"code":200,
"message":"success",
"requestId":"F2BCDE1E9A9C1D",
"data": true
}
# 会话评价
机器人会话中,开发者可以通过七鱼开放接口,自己控制访客与机器人的交互行为。
# 获取机器人评价设置
该接口由七鱼提供给第三方调用,用于第三方自己实现机器人满意度评价功能并与七鱼系统进行对接的方式。机器人满意度评价选项配置在七鱼管理后台机器人模块内设置,第三方可以通过该接口拉取该配置,并自己实现用户信息评价功能。评价完成之后,第三方调用下面机器人会话评价接口将评价结果同步给七鱼系统。
POST请求为:
POST https://qiyukf.com/openapi/robot/evaluation/setting?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"robotId": 10001,
"fromType": "iOS"
}
请求参数说明如下:
参数 | 参数类型 | 是否必须 | 参数说明 |
---|---|---|---|
robotId | Long | 否 | 机器人id,未传值时取默认机器人 |
fromType | String | 是 | 访客终端类型:iOS,android,WEB |
响应示例如下:
{
"list": [{
"name": "非常不满意",
"tagList": [],
"value": 1,
"tagRequired":1,
"commentRequired":1
}, {
"name": "不满意",
"tagList": [],
"value": 25,
"tagRequired":0,
"commentRequired":0
}, {
"name": "一般",
"tagList": [],
"value": 50
}, {
"name": "满意",
"tagList": [],
"value": 75
}, {
"name": "非常满意",
"tagList": ["幽默","热情"],
"value": 100
}],
"messageThanks": "您对我们的服务评价为: ${评价结果}。非常感谢!",
"note": "五级评价模式",
"title": "模式三",
"type": 5,
"resolvedEnabled":1,
"resolvedRequired":1,
"enableEvaluationMuttimes":true,
"evaluationRounds":2
}
响应参数说明如下:
参数 | 数据类型 | 参数说明 |
---|---|---|
code | Integer | 错误码。200表示设置成功。 |
message | String | 错误提示信息 |
data | Json | 满意度配置信息 |
data.messageThanks | String | 满意度感谢评价文案 |
data.title | String | 评价模型名称 |
data.note | String | 评价模型备注 |
data.type | Integer | 评价模型类别(2,3,4,5级满意度模式) |
data.resolvedEnabled | Integer | 是否向访客收集“您的问题是否解决”0-关闭1-打开 |
data.resolvedRequired | Integer | resolvedEnabled开启后是否必填:0-非必填1-必填 |
data.enableEvaluationMuttimes | Boolean | 是否允许多次评价false-不允许true-允许 |
data.evaluationRounds | Integer | 评价回合数限制 |
data.list | List | 满意度评价选项 |
data.list.name | String | 评价选项对应名称 |
data.list.value | String | 评价选项对应值 |
data.list.tagList | List | 评价选项对应可选择的标签 |
data.list.tagRequired | Integer | 标签是否必选0-非必选1-必选 |
data.list.commentRequired | Integer | 备注是否必填0-非必填1-必填 |
# 提交机器人会话评价
该接口允许用户评价当前机器人服务。根据评价设置接口中返回的list数组显示满意度评价项,name 为评价项名称,value 为对应评价值,用户选择某评价项时,将对应 value 值作为下面接口参数 evaluation 的参数值。
POST 请求为:
POST https://qiyukf.com/openapi/robot/evaluation/comment?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"sessionId":62927,
"evaluation":100,
"evaluationResolved": 1,
"remarks":"你的服务非常棒",
"tagList":["幽默","热情"]
}
请求参数说明如下:
参数 | 是否必须 | 参数说明 |
---|---|---|
sessionId | 是 | 待评价的会话 ID。 |
evaluation | 是 | 评价值来自评价设置接口响应参数中 list 中的 value 值。 |
evaluationResolved | 否 | 用户上报问题解决状态,可以为空。0-未选择,1-已解决,2-未解决。 |
remarks | 否 | 评价备注信息,可以为空 |
tagList | 否 | 评价时给机器人会话打的标签信息 |
响应示例如下:
{
"code": 200
}
响应参数说明如下:
参数 | 参数说明 |
---|---|
code | 错误码。200表示评价成功。 |
# 统计接口
开发者可以通过七鱼开放接口,获取一段时间内的机器人统计数据。
# 获取机器人会话统计总揽数据
该接口获取指定时间范围内的机器人会话统计汇总数据,一次最多支持获取30天时间范围内的数据。
POST 请求为:
POST https://qiyukf.com/openapi/robot/statistic/summary?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
请求内容示例如下:
{
"robotId":2,
"startTime":1595952000000,
"endTime": 1596038399999
}
请求参数说明如下:
参数名 | 是否必选 | 类型 | 说明 |
---|---|---|---|
robotId | 否 | long | 机器人id,未传时取默认机器人 |
startTime | 是 | long | 起始时间(毫秒),实际取数时取该天开始时间 |
endTime | 是 | long | 结束时间(毫秒),实际取数时取该天结束时间 |
响应示例如下:
{
"code": 200,
"message": "哈哈",
"data": {
"robotId": 2,
"sumSessions": 673,
"invalidSessions": 502,
"validSessions": 171,
"solvenums": 102,
"unSolvenums": 43,
"solveRadio": 0.7034,
"transferKefu": 146,
"leave": 356,
"sumQuestions": 392,
"matchQuestions": 374,
"matchRadio": 0.9540,
"matcherFromRobot": 362,
"completeMatcher": 281,
"completeMatchRatio": 0.7762,
"similarMatcher": 81,
"similarMatchRatio": 0.2237,
"chosenMatcher": 32,
"similarMatchAcceptRatio": 0.3950,
"evaluateBad": 0,
"evaluateUngood": 0,
"evaluateNormal": 0,
"evaluateGood": 0,
"evaluateVeryGood": 0,
"evaluateJoinRatio": 0.0,
"evaluateGoodRatio": -1.0
}
}
响应参数说明如下:
参数 | 参数说明 |
---|---|
code | 错误码。200表示成功。 |
message | 错误信息。code!=200时的提示信息。 |
data | 数据内容 |
data字段说明如下:
参数名 | 类型 | 说明 |
---|---|---|
robotId | long | 机器人id |
sumSessions | long | 总会话量 |
invalidSessions | long | 无效会话量 |
validSessions | long | 有效会话量 |
solvenums | long | 有效会话解决量 |
unSolvenums | long | 有效会话未解决量 |
solveRadio | double | 有效会话解决率 |
transferKefu | long | 无效会话-直接转人工量 |
leave | long | 无效会话-直接离开量 |
sumQuestions | long | 提问总数 |
matchQuestions | long | 匹配提问数 |
matchRadio | double | 匹配率 |
matcherFromRobot | long | 机器人匹配提问数 |
completeMatcher | long | 机器人完全匹配数 |
completeMatchRatio | double | 机器人完全匹配率 |
similarMatcher | long | 机器人相似匹配数 |
similarMatchRatio | double | 机器人相似匹配率 |
chosenMatcher | long | 机器人相似匹配选择数 |
similarMatchAcceptRatio | double | 机器人相似匹配选择率 |
evaluateBad | long | 评价-非常不满意数 |
evaluateUngood | long | 评价-不满意数 |
evaluateNormal | long | 评价-一般数 |
evaluateGood | long | 评价-满意数 |
evaluateVeryGood | long | 评价-非常满意数 |
evaluateJoinRatio | double | 会话参评率 |
evaluateGoodRatio | double | 会话好评率 |
# 转人工会话统计
获取转人工会话数据,一次最多支持获取365天范围内的数据。
POST 请求为:
POST https://qiyukf.com/openapi/ai/statistic/transferHuman?appKey=1064deea1c3624c9ee26d1de5ce8481f&time=1463217187&checksum=2f13932c4b7c6888b12360a85261a11b8b543f64
Content-Type:application/json;charset=utf-8
频率限制:
- 1次/秒
请求内容示例如下:
{
"robotId":2,
"sessionType":0,
"startTime":1595952000000,
"endTime": 1596038399999
}
请求参数说明如下:
参数名 | 是否必选 | 类型 | 说明 |
---|---|---|---|
robotId | 否 | long | 机器人id,未传时取默认机器人 |
sessionType | 否 | int | 会话类型0-所有 1-有效 2-无效 默认:0 |
startTime | 是 | long | 起始时间(毫秒),实际取数时取该天开始时间,起止时间间隔不能超过365天 |
endTime | 是 | long | 结束时间(毫秒),实际取数时取该天结束时间,起止时间间隔不能超过365天 |
响应示例如下:
{
"code": 200,
"message": "哈哈",
"data": [
{
"type": 0,
"count": 7,
"sessionRatio": 0.0337
}
]
}
响应参数说明如下:
参数 | 参数说明 |
---|---|
code | 错误码。200表示成功。 |
message | 错误信息。code!=200时的提示信息。 |
data | 数据内容 |
data字段说明如下:
参数名 | 类型 | 说明 |
---|---|---|
type | int | 转人工会话类型 0:所有转人工。结果一定要按type过滤,因为以后会加其他类型。 |
count | long | 会话数量, -1表示该字段的值不存在 |
sessionRatio | long | 会话占比, -1表示该字段的值不存在 |
# 消息接口
七鱼除了提供在线客服+在线机器人一体化的对接方式以外,另外独立开放一套机器人能力接口,你可以在任意设备/终端/平台上,通过http调用方式,使用这套接口实现机器人对话能力。同时,这套接口里也提供了丰富的转人工事件,你可以基于这些事件,完成七鱼机器人和你的im平台/人工客服平台的无缝对接。
# 概念/名词解释
企业/调用方/接入方:使用七鱼平台的客户。
员工:使用七鱼的企业管理员。
访客/用户:在终端与机器人对话的企业用户。
会话:一位访客一次完整的机器人消息咨询(从访客开始咨询到访客结束本次咨询)
消息:会话中访客发送或机器人回复的每一条消息内容。
渠道:访客接入的终端,包括 WEB网页/APP客户端/微信公众号/wx小程序/微博等。
配置:企业员工在七鱼平台设置的内容,包括知识库配置/词库配置/访客端配置/人机协作设置等。
FAQ:企业员工在七鱼机器人模块“知识库-问题”里配置的知识。
寒暄:企业员工在七鱼机器人模块“知识库-自定义寒暄库”里配置的知识。
BOT:企业员工在七鱼机器人模块“知识库-一触即达”里配置的意图/流程。
# 接口通用说明
# 调用方式
开放平台接口开发者需通过HTTP/HTTPS POST方式调用,并按照接口声明,填充相应请求参数信息。发起请求调用后,七鱼系统会返回相应回复数据,如果请求不合法或发生异常,系统会返回相应的错误码,开发者可根据返回状态码自行排查问题。
# 鉴权认证方式
开放平台接口会做统一的鉴权认证,开发者在调用接口时,需要将以下鉴权信息字段填充到url参数中。
字段 | 类型 | 注释 |
---|---|---|
appKey | string | 七鱼分配给企业的appKey |
time | long | 当前 UTC 时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的秒数 |
checksum | string | 用于校验数据的完整性,SHA1(appSecret + md5 + time),由三个参数拼接的字符串,进行SHA1哈希计算,转化成16进制字符(String,小写) |
备注: appKey 和 appSecert 可在七鱼企业管理后台“系统-扩展与集成-开发者ID”页查看。 checksum 中的 md5 为 POST请求 的 body 内容字符串的 md5 哈希值(小写形式),即 md5 = MD5(bodyContent).toLowerCase(),如果是上传文件,则是整个文件内容的md5。 出于安全性考虑,每个 checksum 的有效期为 5 分钟,请确认发起请求的服务器是与标准时间同步的,比如有NTP服务。
计算 checksum 的 Java 示例代码如下:
public class QiyuPushCheckSum {
private static final char[] HEX_DIGITS = {'0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'};
public static String encode(String appSecret, String md5, String time) {
String content = appSecret + md5 + time;
try {
MessageDigest messageDigest = MessageDigest.getInstance("sha1");
messageDigest.update(content.getBytes());
return getFormattedText(messageDigest.digest());
} catch (Exception e) {
throw new RuntimeException(e);
}
}
private static String getFormattedText(byte[] bytes) {
int len = bytes.length;
StringBuilder buf = new StringBuilder(len * 2);
for (int j = 0; j < len; j++) {
buf.append(HEX_DIGITS[(bytes[j] >> 4) & 0x0f]);
buf.append(HEX_DIGITS[bytes[j] & 0x0f]);
}
return buf.toString();
}
}
# 返回状态码
code | 说明 |
---|---|
200 | 无错误 |
14001 | appKey不存在 |
14002 | checksum计算错误 |
14003 | time已过期 |
14004 | 内容错误,字段格式或字段值不合法 |
14008 | ip黑名单 |
14009 | 触发接口频率限制 |
14500 | 系统错误,通常是服务器内部错误 |
14501 | 内容长度限制 |
14515 | 无接口访问权限 |
# 对接场景示例
这里介绍一个基本的机器人会话对接流程,基于此流程可实现一个最基础的机器人对话能力对接。除了基本的会话流程接口外,我们还提供了其他丰富的功能接口,用于提高访客和人工客服咨询/答疑效率,接入方可在接口明细查看相应的接口介绍,自行对接在会话过程中,完善咨询体验。
# 对接前提
已经在七鱼机器人平台搭建了机器人。
# 调用时序图
# 对接步骤
1.调用/openapi/robot/session/create 创建会话接口,创建一个机器人会话。uid + productId 作为访客在七鱼系统里的唯一标志,一个访客同一时间最多只存在一个机器人会话,在这通会话生命周期内,该访客发送的问答消息都会记入这一通会话中。
2.调用/openapi/robot/session/chat 问答接口,机器人将根据配置的FAQ知识库/寒暄知识库/BOT流程,以及转人工策略和未知回复策略等,按照相应的处理优先级顺序,找到当前消息最佳回答。机器人回答主要可分为两大类,第一类是用来回复访客,接入方按机器人给的回答内容展示给访客;第二类是触发转人工事件,此事件表示该访客需要人工客服接入处理,接入方可实现人机无缝转接。
3.每一条回复访客的机器人消息,会带上是否允许评价等信息,接入方可基于这些信息实现消息评价功能,访客评价后接入方可通过/openapi/robot/session/msgEvaluation接口,将相应评价结果同步到七鱼,七鱼会生成对应的消息纬度数据报表,便于接入方管理数据和知识。
4.在访客输入消息过程中,接入方可基于/openapi/robot/session/msgAssociate 输入联想接口,实现访客输入提示,提高访客咨询效率和使用体验。该功能接入方按需对接即可。
5.访客发送一条消息后,除了正常的机器人回复流程外,接入方还可以根据/openapi/robot/session/msgPredict 服务先知接口,实现访客意图推荐功能,功能以按钮或卡片等形式给访客选择,提高咨询效率和使用体验。该功能接入方按需对接即可。
6.机器人服务过程中,接入方可基于机器人会话评价/openapi/robot/evaluation/setting接口,获取机器人支持的评价模式,实现评价功能,收集访客对这一通机器人会话整体的评价。并通过/openapi/robot/evaluation/comment接口,将访客对会话的评价上传到七鱼机器人平台,七鱼会生成相应的会话纬度满意度统计报表,便于接入方管理数据和知识。
7.若接入方在访客端实现了访客主动转人工功能,由于这种转人工场景并不是由机器人触发的,七鱼机器人对这种原因结束的会话没有感知,造成机器人历史数据的不完整。此时,接入方应对接 /openapi/robot/session/close 机器人会话关闭接口,主动告知机器人访客通过其他途径转到了人工客服。这样七鱼平台生成的机器人会话数据才能保证完整。若接入方未实现此接口,则七鱼系统会在访客10min未产生新的消息后,自动结束掉这一通机器人会话。
# 会话类接口
# 通用数据结构说明
对接中常见的数据结构说明。
# 通用知识结构:
- SimpleQuestion
字段 | 类型 | 注释 |
---|---|---|
question | string | 问题内容 |
type | integer | 问题类型 1-FAQ 2-内置寒暄 3-自定义寒暄 4-BOT 101-第三方自定义数据 |
- 备注:通用知识问题结构,用来描述会话流程中各种问题数据,包括 常见问题/关联问题/相似问题;
# 通用消息格式:
- CommonMsg:通用的消息描述
字段 | 类型 | 注释 |
---|---|---|
msgType | string | 消息类型 |
msgBody | object | 消息内容 |
# 枚举消息类型,及每种类型消息体格式:
- text/richtext:文本/富文本类型
字段 | 类型 | 注释 |
---|---|---|
content | string | 文本消息体 |
- image:图片类型
字段 | 类型 | 注释 |
---|---|---|
url | string | 图片资源地址 |
w | integer | 宽度 |
h | integer | 高度 |
size | integer | 大小 |
- video:视频类型
字段 | 类型 | 注释 |
---|---|---|
url | string | 视频资源地址 |
- audio:音频类型
字段 | 类型 | 注释 |
---|---|---|
url | string | 音频资源地址 |
- event_trans:转人工事件类型
字段 | 类型 | 注释 |
---|---|---|
closeReason | integer | 转人工事件触发原因 |
transGuide | string | 转人工引导语 |
- workflow:一触即达流程数据类型
字段 | 类型 | 注释 |
---|---|---|
params | string | 节点参数,取系统返回的数据 |
target | string | 节点跳转的目标节点id,取系统返回的数据 |
templateId | string | 样式模版id,可取值范围:qiyu_template_text、drawer_list、bubble_list、qiyu_template_item |
template | object | 模版数据 |
template数据格式由templateId决定,格式对应如下:
- templateId:qiyu_template_text文本模版
字段 | 类型 | 注释 |
---|---|---|
label | string | 文本文案,取系统返回数据 |
- templateId:qiyu_template_item卡片模版详情
字段 | 类型 | 注释 |
---|---|---|
p_attr_1 | string | 卡片属性1,取系统返回数据 |
p_attr_2 | string | 卡片属性2,取系统返回数据 |
p_attr_3 | string | 卡片属性3,取系统返回数据 |
p_img | string | 卡片图片,取系统返回数据 |
p_title | string | 卡片标题,取系统返回数据 |
p_sub_title | string | 卡片子标题,取系统返回数据 |
- templateId:drawer_list、bubble_list卡片列表加载更多
此时template传空即可
# 创建机器人会话
简要描述:
- 初始化机器人会话,用于记录访客当前咨询信息,在这一通会话结束(调用方主动调用关闭会话接口/访客消息触发转人工客服/访客长时间未说话自动超时关闭)前,这个访客与机器人的聊天消息都记录在这一通会话中。
- 对接入七鱼机器人会话的访客,七鱼也会给访客生成一个身份,用于在七鱼系统中标志该访客。七鱼的用户身份,由接入方传入的uid + productId 两个参数来唯一确定,其中uid表示访客身份,productId表示应用身份。每个七鱼用户在同一时间只会存在一个机器人会话。
- 创建成功后返回相应会话信息,欢迎语,常见问题数据;
请求URL:
/openapi/robot/session/create
请求方式:
- POST
参数:
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
uid | 是 | string | 访客在调用方系统里的标志,用于唯一确定用户身份 |
productId | 否 | string | 当前咨询应用唯一标识,可以是 Android 应用的包名,iOS 应用的 bundleid,微信公众号appid等。调用方系统如果有多个应用需要接入七鱼时,对不同应用需保证该字段值的唯一性。未指定时取默认值“qyopen” |
fromType | 否 | string | 当前访客咨询来源渠道。未指定时取默认值“WEB” |
robotId | 否 | long | 机器人id,存在多个机器人时指定当前接入的机器人,未指定时取设置的默认机器人 |
welcomeTemplateId | 否 | long | 指定七鱼机器人欢迎语模版id,如果指定了模版且模版生效,则取当前模版配置的欢迎语,否则按“fromType”取相应渠道默认模版 |
questionTemplateId | 否 | long | 指定七鱼机器人常见问题模版id,如果指定了模版且模版生效,则取当前模版配置的常见问题数据;否则按“fromType-productId-fromPage”来匹配相应模版; |
fromPage | 否 | string | 当前访客咨询来源页面 |
返回示例
{
"code": 200,
"message": "哈哈",
"data": {
"sessionId": 62927,
"userId": 43412123,
"robotId": 34351,
"robotName": "机器人昵称",
"robotLogoUrl": "http://ysf.nosdn.qiyukf.com/xxxxx",
"welcome":{
"msgType": "text",
"msgBody": {
"content": "这是欢迎语"
}
},
"commonQuestions": {
"questionGuide": "常见问题引导语文案",
"questionList": [
{
"id": 243244,
"question": "常见问题1",
"type": 1
}
]
}
}
}
返回data参数说明
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
sessionId | 是 | long | 当前访客咨询对应的七鱼会话id |
userId | 是 | long | 当前访客在七鱼系统里的用户id |
robotId | 是 | long | 当前会话所属机器人id |
robotName | 是 | string | 机器人名字 |
robotLogoUrl | 否 | string | 机器人头像图片地址 |
welcome | 是 | CommonMsg | 欢迎语内容,这里的消息类型支持:text/richtext,字段格式详细介绍见通用数据结构说明 |
commonQuestions | 否 | object | 机器人会话常见问题模版 |
commonQuestions.questionGuide | 是 | string | 常见问题引导语 |
commonQuestions.questionList | 是 | List<SimpleQuestion> | 常见问题列表,字段及含义见通用数据结构SimpleQuestion说明 |
# 常见问题
简要描述:
- 获取会话-常见问题列表。
- 一般用于访客开启机器人咨询时,给访客推送一些常见的问题,访客可以通过选择问题的方式来提高咨询效率。七鱼机器人常见问题模版,支持按访客的“咨询渠道-咨询应用-来源页面”分别配置,便于实现在不同场景下推送该场景相关的常见问题。调用方在对接时,可以选择传递这些信息到七鱼系统,实现按场景区分常见问题。
请求URL:
/openapi/robot/session/commonQuestions
请求方式:
- POST
参数:
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
robotId | 否 | long | 机器人id,未指定时取默认机器人 |
uid | 否 | long | 访客在调用方系统里的标志,用于唯一确定用户身份 |
templateId | 否 | long | 指定七鱼常见问题模版id,如果指定了模版且模版生效,则取当前模版配置的常见问题数据;否则按“fromType-fromApp-fromPage”来匹配相应模版; |
fromType | 否 | string | 当前访客咨询来源渠道 |
productId | 否 | string | 当前咨询应用标识,可以是 Android 应用的包名,iOS 应用的 bundleid,微信公众号appid等 |
fromPage | 否 | string | 当前访客咨询来源页面 |
返回示例
{
"code": 200,
"message": "哈哈",
"data": {
"robotId": 34351,
"questionGuide": "常见问题引导语文案",
"questionList": [
{
"question": "常见问题1",
"type": 1
}
]
}
}
返回参数说明
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
robotId | 否 | long | 机器人id |
questionGuide | 否 | string | 常见问题引导语 |
questionList | 否 | List<SimpleQuestion> | 常见问题列表,字段及含义见通用数据结构SimpleQuestion说明 |
# 快捷短语
简要描述:
- 获取快捷短语按钮列表接口。访客咨询机器人过程中,根据访客当前消息,实时预测访客真实意图。调用方可基于此接口,实现访客真实意图预测,以按钮等样式提示访客,提高访客端咨询体验。
请求URL:
/openapi/robot/session/msgPredict
请求方式:
- POST
参数:
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
uid | 否 | string | 访客在调用方系统里的标志,用于唯一确定用户身份 |
robotId | 否 | long | 机器人id,存在多个机器人时指定当前接入的机器人 |
question | 否 | string | 当前访客消息内容 |
fromType | 否 | string | 当前访客咨询来源渠道 |
productId | 否 | string | 当前咨询应用标识,可以是 Android 应用的包名,iOS 应用的 bundleid,微信公众号appid等 |
fromPage | 否 | string | 当前访客咨询来源页面 |
返回示例
{
"code": 200,
"message": "哈哈",
"data": [
{
"label": "快捷短语",
"action": 1,
"content": "真实意图内容"
}
]
}
返回data参数说明
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
label | 是 | string | 快捷短语标题 |
action | 是 | integer | 快捷操作行为,1-文本内容 2-url跳转 |
content | 是 | string | 具体内容,action=1时为文本内容,action=2时为跳转地址 |
# 输入联想
简要描述:
- 获取输入联想列表接口。访客在咨询机器人过程中,根据访客当前输入内容,实时联想访客想要输入的问句。接入方可基于此接口实现访客输入自动补齐/提示等功能,提高访客咨询效率。
请求URL:
/openapi/robot/session/msgAssociate
请求方式:
- POST
参数:
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
robotId | 否 | long | 机器人id,存在多个机器人时指定当前接入的机器人 |
content | 是 | string | 当前访客的输入内容 |
返回示例
{
"error_code": 0,
"data": {
"content": "访客当前输入内容",
"questionList": [
{
"question": "根据访客当前输入内容联想到的知识",
"type": 1
}
]
}
}
返回参数说明
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
content | 是 | string | 传入的访客内容 |
questionList | 是 | List<SimpleQuestion> | 联想到的问题列表,字段及含义见通用数据结构SimpleQuestion说明 |
# 获取机器人消息回复
简要描述:
- 获取机器人回复接口。根据访客输入的文本内容,或者点击的常见问题/相似问题/关联问题/输入联想问题/服务直达推荐问题等,或者点击的BOT流程节点,机器人通过理解用户消息返回最佳答复。
- 访客消息和机器人回复消息,均会记入该访客当前会话中,会话结束后可以查看会话历史记录,以及相应的统计数据。
- 若当前用户不在会话中,则默认为该访客创建一个新机器人会话。
请求URL:
/openapi/robot/session/chat
请求方式:
- POST
参数:
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
uid | 是 | string | 访客在调用方系统里的标志,用于唯一确定用户身份 |
productId | 否 | string | 当前咨询应用唯一标识,可以是 Android 应用的包名,iOS 应用的 bundleid,微信公众号appid等。调用方系统如果有多个应用需要接入七鱼时,对不同应用需保证该字段值的唯一性 |
fromType | 否 | string | 当前访客咨询来源渠道。当前会话不存在时用来创建新会话,若当前已经在会话中,则不用传该字段 |
robotId | 否 | long | 机器人id,存在多个机器人时指定当前接入的机器人,未指定时取设置的默认机器人 。当前会话不存在时用来创建新会话,若当前已经在会话中,则不用传该字段 |
msg | 是 | CommonMsg | 访客消息,目前仅支持 text,image,audio,workflow四种类型,字段格式详细介绍见通用数据结构说明 |
skipTrans | 否,默认值0 | int | 是否跳过转人工逻辑判断,0-不跳过1-跳过 |
返回示例1:精准回复(命中某个faq/寒暄/bot节点等)
{
"code": 200,
"message": "哈哈",
"data": {
"sessionId": 62927,
"userId": 43412123,
"robotId": 34351,
"answerList": [
{
"msgId": "21323",
"ansType": 1,
"ansContent": {
"answer": {
"msgType": "richText",
"msgBody": {
"content": "<p>这是一个富文本答案</p>"
}
},
"connectQuestions": [
{
"question": "关联问题1",
"type": 1
}
]
},
"msgEvaluation": {
"evaluation": 0,
"evaluationReason": 0,
"evaluationGuide": "消息评价引导语"
}
}
]
}
}
返回示例2:推荐回复(未能精准命中,给予相似度top3且在推荐阈值之上的相似问题,引导访客选择)
{
"code": 200,
"message": "哈哈",
"data": {
"sessionId": 62927,
"userId": 43412123,
"robotId": 34351,
"answerList": [
{
"msgId": "21323",
"ansType": 2,
"ansContent": {
"recommandGuide": "相似问题引导语",
"recommandQuestions": [
{
"question": "相似问题1",
"type": 1
}
]
},
"msgEvaluation": {
"evaluation": 0,
"evaluationReason": 0,
"evaluationGuide": "消息评价引导语"
}
}
]
}
}
返回示例3:未知回复(即未精准命中也无合适推荐,给予相应配置好的未知问题回复话术)
{
"code": 200,
"message": "哈哈",
"data": {
"sessionId": 62927,
"userId": 43412123,
"robotId": 34351,
"answerList": [
{
"msgId": "21323",
"ansType": 4,
"ansContent": {
"silence": 0,
"answer": {
"msgType": "richText",
"msgBody": {
"content": "<p>这是一个富文本答案</p>"
}
}
},
"msgEvaluation": {
"evaluation": 0,
"evaluationReason": 0,
"evaluationGuide": "消息评价引导语"
}
}
]
}
}
返回示例4:触发转人工事件
{
"code": 200,
"message": "哈哈",
"data": {
"sessionId": 62927,
"userId": 43412123,
"robotId": 34351,
"answerList": [
{
"msgId": "21323",
"ansType": 10,
"ansContent": {
"msgType": "event_trans",
"msgBody": {
"closeReason": 31,
"transGuide": "转人工引导语"
}
},
"msgEvaluation": {
"evaluation": 0,
"evaluationReason": 0,
"evaluationGuide": "消息评价引导语"
}
}
]
}
}
返回示例5:一触即达流程回复-回复节点应答样式
{
"code": 200,
"message": "哈哈",
"data": {
"sessionId": 62927,
"userId": 43412123,
"robotId": 34351,
"answerList": [
{
"msgId": "21323",
"ansType": 7,
"ansContent": {
"templateId": "static_union",
"templateData": {
"unions": [
{
"detail": {
"label": "按钮引导语生生世世"
},
"type": "richText"
},
{
"detail": {
"style": "button",
"label": "按钮11",
"params": "_preRequestId=f85aca12-fef3-4745-84b2-e6c8273489c4&_sessionId=6680535022&_preNodeId=1A1630EDEEB6C255-83da122764a43b0e&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-744D767F7EC3388A&nodeId=1A1630EDEEB6C255-6a4c2715295b9bc9",
"type": "url",
"target": "http://www.baidu.com"
},
"type": "link"
},
{
"detail": {
"style": "button",
"label": "按钮22",
"params": "_preRequestId=f85aca12-fef3-4745-84b2-e6c8273489c4&_sessionId=6680535022&_preNodeId=1A1630EDEEB6C255-83da122764a43b0e&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-744D767F7EC3388A",
"type": "block",
"target": "1A1630EDEEB6C255-ffce372763c07654"
},
"type": "link"
}
]
}
}
}
]
}
}
点击节点跳转按钮后,发送的workflow类型消息体格式:
{
"templateId": "qiyu_template_text",
"params": "_preRequestId=f85aca12-fef3-4745-84b2-e6c8273489c4&_sessionId=6680535022&_preNodeId=1A1630EDEEB6C255-83da122764a43b0e&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-744D767F7EC3388A",
"target": "1A1630EDEEB6C255-ffce372763c07654",
"template": {
"label": "按钮22"
}
}
返回示例6:一触即达流程回复-回复节点反问样式
{
"code": 200,
"message": "哈哈",
"data": {
"sessionId": 62927,
"userId": 43412123,
"robotId": 34351,
"answerList": [
{
"msgId": "21323",
"ansType": 7,
"ansContent": {
"templateId": "reply_asked",
"templateData": {
"label": "您是否想咨询?",
"list": [
{
"id": 7539893,
"params": "_preRequestId=1153f985-f4a2-4d8f-a567-ab8f4acc2119&_sessionId=6680534545&_preNodeId=1A1630EDEEB6C255-ee49135469802e9d&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-744D767F7EC3388A&knowledgeId=7539893&type=0&nodeId=1A1630EDEEB6C255-ee49135469802e9d",
"type": 0,
"knowledge": "特润体乳问题"
},
{
"id": 7501672,
"params": "_preRequestId=1153f985-f4a2-4d8f-a567-ab8f4acc2119&_sessionId=6680534545&_preNodeId=1A1630EDEEB6C255-ee49135469802e9d&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-744D767F7EC3388A&knowledgeId=7501672&type=0&nodeId=1A1630EDEEB6C255-ee49135469802e9d",
"type": 0,
"knowledge": "测试一下"
},
{
"id": 7542166,
"params": "_preRequestId=1153f985-f4a2-4d8f-a567-ab8f4acc2119&_sessionId=6680534545&_preNodeId=1A1630EDEEB6C255-ee49135469802e9d&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-744D767F7EC3388A&knowledgeId=7542166&type=0&nodeId=1A1630EDEEB6C255-ee49135469802e9d",
"type": 0,
"knowledge": "企业返回faq1"
}
]
}
}
}
]
}
}
用户点击反问问题后,直接发送text类型消息。
返回示例7:一触即达流程回复-对话节点样式
{
"code": 200,
"message": "哈哈",
"data": {
"sessionId": 62927,
"userId": 43412123,
"robotId": 34351,
"answerList": [
{
"msgId": "21323",
"ansType": 7,
"ansContent": {
"templateId": "radio_button",
"templateData": {
"button_type": "radio",
"label": "对话节点测试,请输入所在城市",
"list": [
{
"style": "button",
"label": "杭州",
"type": "radio"
},
{
"style": "button",
"label": "南京",
"type": "radio"
},
{
"style": "button",
"label": "武汉",
"type": "radio"
}
]
}
}
}
]
}
}
用户点击按钮后,直接发送text类型消息。
返回示例8:一触即达流程回复-查询节点-输出样式-抽屉列表样式
{
"code": 200,
"message": "哈哈",
"data": {
"sessionId": 62927,
"userId": 43412123,
"robotId": 34351,
"answerList": [
{
"msgId": "21323",
"ansType": 7,
"ansContent": {
"templateId": "drawer_list",
"templateData": {
"tab_id": "1",
"empty_list_hint": "无数据返回",
"label": "请选择您想咨询的商品",
"title": "请选择您想咨询的商品:",
"tabList": [
{
"tab_id": 1,
"tab_name": "页1",
"action": {
"label": "查看更多",
"type": "block",
"params": "_preRequestId=dfcd4e34-f54a-4b2e-9907-195d4954c380&_sessionId=6680534575&_preNodeId=1A1630EDEEB6C255-642316fac532aa13&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-C2020BB2C8A13C83&tabId=1¤tPage=2&pageSize=10",
"target": "1A1630EDEEB6C255-642316fac532aa13"
},
"list": [
{
"p_img": "https://ysf.nosdn.127.net/f4618cd19d780e94fc69402d51091e07?imageView",
"p_title": "【华为旗舰店】华为旗舰店",
"p_sub_title": "2020-04-14 14:00:00",
"p_item_type": "1",
"type": "block",
"params": "_preRequestId=dfcd4e34-f54a-4b2e-9907-195d4954c380&_sessionId=6680534575&_preNodeId=1A1630EDEEB6C255-642316fac532aa13&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-C2020BB2C8A13C83&",
"target": "1A1630EDEEB6C255-7ad486434ada4a44"
},
{
"p_attr_1": "¥1000",
"p_attr_2": "x100",
"p_img": "https://ysf.nosdn.127.net/faff3a003f3ec9ba47a89ce73f4d7a4a?imageView",
"p_title": "Xiaomi/小米小米9透明九se故宫版10尊享探索plus全新手机骁龙855",
"p_sub_title": "Xiaomi/小米",
"p_attr_3": "卖家已发货",
"p_item_type": "0",
"type": "block",
"params": "_preRequestId=dfcd4e34-f54a-4b2e-9907-195d4954c380&_sessionId=6680534575&_preNodeId=1A1630EDEEB6C255-642316fac532aa13&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-C2020BB2C8A13C83&kh1=qqqq&kh2=11&cg1=222&cg2=都是对的多所&kh5=辅导辅导辅导地方&kh6=&kh7=&kh8=''",
"target": "1A1630EDEEB6C255-7ad486434ada4a44"
},
{
"p_attr_1": "¥1000",
"p_attr_2": "x100",
"p_img": "https://ysf.nosdn.127.net/faff3a003f3ec9ba47a89ce73f4d7a4a?imageView",
"p_title": "Xiaomi/小米小米9透明九se故宫版10尊享探索plus全新手机骁龙855",
"p_sub_title": "Xiaomi/小米",
"p_attr_3": "卖家已发货",
"p_item_type": "0",
"type": "block",
"params": "_preRequestId=dfcd4e34-f54a-4b2e-9907-195d4954c380&_sessionId=6680534575&_preNodeId=1A1630EDEEB6C255-642316fac532aa13&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-C2020BB2C8A13C83&kh1=变量姓名更新&kh2=11&cg1=222&cg2=都是对的多所&kh5=辅导辅导辅导地方&kh6=&kh7=&kh8=''",
"target": "1A1630EDEEB6C255-7ad486434ada4a44"
}
]
},
{
"tab_id": 2,
"tab_name": "购物车2",
"action": {
"label": "查看更多",
"type": "block",
"params": "_preRequestId=dfcd4e34-f54a-4b2e-9907-195d4954c380&_sessionId=6680534575&_preNodeId=1A1630EDEEB6C255-642316fac532aa13&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-C2020BB2C8A13C83&tabId=2¤tPage=1&pageSize=10",
"target": "1A1630EDEEB6C255-642316fac532aa13"
},
"list": [
]
}
]
}
}
}
]
}
}
用户点击一个卡片后,发送的workflow类型消息体格式:
{
"templateId": "qiyu_template_item",
"params": "_preRequestId=dfcd4e34-f54a-4b2e-9907-195d4954c380&_sessionId=6680534575&_preNodeId=1A1630EDEEB6C255-642316fac532aa13&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-C2020BB2C8A13C83&kh1=qqqq&kh2=11&cg1=222&cg2=都是对的多所&kh5=辅导辅导辅导地方&kh6=&kh7=&kh8=''",
"target": "1A1630EDEEB6C255-7ad486434ada4a44",
"template": {
"p_attr_1": "¥1000",
"p_attr_2": "x100",
"p_img": "https://barry.qiyukf.net/faff3a003f3ec9ba47a89ce73f4d7a4a?imageView",
"p_title": "Xiaomi/小米小米9透明九se故宫版10尊享探索plus全新手机骁龙855",
"p_sub_title": "Xiaomi/小米",
"p_attr_3": "卖家已发货"
}
}
用户点击查看更多后,发送的workflow类型消息体格式:
{
"templateId": "drawer_list",
"target": "1A1630EDEEB6C255-642316fac532aa13",
"params": "_preRequestId=d9631b98-dcba-4fe2-9321-a046d27bb2cb&_sessionId=6680536008&_preNodeId=1A1630EDEEB6C255-642316fac532aa13&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-C2020BB2C8A13C83&tabId=2¤tPage=1&pageSize=10"
}
返回示例9:一触即达流程回复-查询节点-输出样式-气泡列表样式
{
"code": 200,
"message": "哈哈",
"data": {
"sessionId": 62927,
"userId": 43412123,
"robotId": 34351,
"answerList": [
{
"msgId": "21323",
"ansType": 7,
"ansContent": {
"templateId": "bubble_list",
"templateData": {
"label": "请选择您想咨询的商品",
"title": "请选择您想咨询的商品:",
"empty_list_hint": "无数据返回",
"action": {
"label": "查看更多",
"type": "block",
"params": "_preRequestId=5f2848c0-f011-4239-94f8-dc4d1b23a4ef&_sessionId=6680534583&_preNodeId=1A1630EDEEB6C255-89cbba8985628a58&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-1DC3A2CCCE948C0E¤tPage=2&pageSize=10",
"target": "1A1630EDEEB6C255-89cbba8985628a58"
},
"list": [
{
"p_img": "https://ysf.nosdn.127.net/f4618cd19d780e94fc69402d51091e07?imageView",
"p_title": "【华为旗舰店】华为旗舰店",
"p_sub_title": "2020-04-14 14:00:00",
"p_item_type": "1",
"type": "block",
"params": "_preRequestId=5f2848c0-f011-4239-94f8-dc4d1b23a4ef&_sessionId=6680534583&_preNodeId=1A1630EDEEB6C255-89cbba8985628a58&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-1DC3A2CCCE948C0E&",
"target": "1A1630EDEEB6C255-e874dd315aefc9a0"
},
{
"p_attr_1": "¥1000",
"p_attr_2": "x100",
"p_img": "https://ysf.nosdn.127.net/faff3a003f3ec9ba47a89ce73f4d7a4a?imageView",
"p_title": "Xiaomi/小米小米9透明九se故宫版10尊享探索plus全新手机骁龙855",
"p_sub_title": "Xiaomi/小米",
"p_attr_3": "卖家已发货",
"p_item_type": "0",
"type": "block",
"params": "_preRequestId=5f2848c0-f011-4239-94f8-dc4d1b23a4ef&_sessionId=6680534583&_preNodeId=1A1630EDEEB6C255-89cbba8985628a58&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-1DC3A2CCCE948C0E&kh1=qqqq&kh2=11&cg1=222&cg2=都是对的多所&kh5=辅导辅导辅导地方&kh6=&kh7=&kh8=''",
"target": "1A1630EDEEB6C255-e874dd315aefc9a0"
},
{
"p_attr_1": "¥1000",
"p_attr_2": "x100",
"p_img": "https://ysf.nosdn.127.net/faff3a003f3ec9ba47a89ce73f4d7a4a?imageView",
"p_title": "Xiaomi/小米小米9透明九se故宫版10尊享探索plus全新手机骁龙855",
"p_sub_title": "Xiaomi/小米",
"p_attr_3": "卖家已发货",
"p_item_type": "0",
"type": "block",
"params": "_preRequestId=5f2848c0-f011-4239-94f8-dc4d1b23a4ef&_sessionId=6680534583&_preNodeId=1A1630EDEEB6C255-89cbba8985628a58&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-1DC3A2CCCE948C0E&kh1=变量姓名更新&kh2=11&cg1=222&cg2=都是对的多所&kh5=辅导辅导辅导地方&kh6=&kh7=&kh8=''",
"target": "1A1630EDEEB6C255-e874dd315aefc9a0"
}
]
}
}
}
]
}
}
用户点击一个卡片后,发送的workflow类型消息体格式:
{
"templateId": "qiyu_template_item",
"params": "_preRequestId=5f2848c0-f011-4239-94f8-dc4d1b23a4ef&_sessionId=6680534583&_preNodeId=1A1630EDEEB6C255-89cbba8985628a58&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-1DC3A2CCCE948C0E&kh1=变量姓名更新&kh2=11&cg1=222&cg2=都是对的多所&kh5=辅导辅导辅导地方&kh6=&kh7=&kh8=''",
"target": "1A1630EDEEB6C255-e874dd315aefc9a0",
"template": {
"p_attr_1": "¥1000",
"p_attr_2": "x100",
"p_img": "https://barry.qiyukf.net/faff3a003f3ec9ba47a89ce73f4d7a4a?imageView",
"p_title": "Xiaomi/小米小米9透明九se故宫版10尊享探索plus全新手机骁龙855",
"p_sub_title": "Xiaomi/小米",
"p_attr_3": "卖家已发货"
}
}
用户点击查看更多后,发送的workflow类型消息体格式:
{
"templateId": "bubble_list",
"target": "1A1630EDEEB6C255-89cbba8985628a58",
"params": "_preRequestId=23e41c09-15d3-4d2d-bcf1-8dc24e3198e5&_sessionId=6680535044&_preNodeId=1A1630EDEEB6C255-89cbba8985628a58&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-1DC3A2CCCE948C0E¤tPage=2&pageSize=10"
}
返回示例10:一触即达流程回复-查询节点-输出样式-横滑卡片列表样式
{
"code": 200,
"message": "哈哈",
"data": {
"sessionId": 62927,
"userId": 43412123,
"robotId": 34351,
"answerList": [
{
"msgId": "21323",
"ansType": 7,
"ansContent": {
"templateId": "horizontal_sliding_list",
"templateData": {
"label": "请选择您想咨询的商品",
"empty_list_hint": "无数据返回",
"action": {
"label": "换一批",
"type": "block",
"params": "_preRequestId=2f63b0c4-6ce9-448e-9bad-bfc483086ed8&_sessionId=6680534596&_preNodeId=1A1630EDEEB6C255-17c082362a34a2b8&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-E540D1C13A9EB2F5¤tPage=2&pageSize=10",
"target": "1A1630EDEEB6C255-17c082362a34a2b8"
},
"list": [
{
"p_attr_1": "",
"p_attr_2": "",
"p_img": "https://ysf.nosdn.127.net/f4618cd19d780e94fc69402d51091e07?imageView",
"p_title": "【华为旗舰店】华为旗舰店",
"p_sub_title": "2020-04-14 14:00:00",
"p_attr_3": "",
"type": "block",
"params": "_preRequestId=2f63b0c4-6ce9-448e-9bad-bfc483086ed8&_sessionId=6680534596&_preNodeId=1A1630EDEEB6C255-17c082362a34a2b8&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-E540D1C13A9EB2F5&",
"target": "1A1630EDEEB6C255-9ada7700aeece672"
},
{
"p_attr_1": "¥1000",
"p_attr_2": "x100",
"p_img": "https://ysf.nosdn.127.net/faff3a003f3ec9ba47a89ce73f4d7a4a?imageView",
"p_title": "Xiaomi/小米小米9透明九se故宫版10尊享探索plus全新手机骁龙855",
"p_sub_title": "Xiaomi/小米",
"p_attr_3": "卖家已发货",
"type": "block",
"params": "_preRequestId=2f63b0c4-6ce9-448e-9bad-bfc483086ed8&_sessionId=6680534596&_preNodeId=1A1630EDEEB6C255-17c082362a34a2b8&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-E540D1C13A9EB2F5&kh1=qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq&kh2=11&cg1=222&cg2=都是对的多所&kh5=辅导辅导辅导地方&kh6=&kh7=&kh8=''",
"target": "1A1630EDEEB6C255-9ada7700aeece672"
},
{
"p_attr_1": "¥1000",
"p_attr_2": "x100",
"p_img": "https://ysf.nosdn.127.net/faff3a003f3ec9ba47a89ce73f4d7a4a?imageView",
"p_title": "Xiaomi/小米小米9透明九se故宫版10尊享探索plus全新手机骁龙855",
"p_sub_title": "Xiaomi/小米",
"p_attr_3": "卖家已发货",
"type": "block",
"params": "_preRequestId=2f63b0c4-6ce9-448e-9bad-bfc483086ed8&_sessionId=6680534596&_preNodeId=1A1630EDEEB6C255-17c082362a34a2b8&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-E540D1C13A9EB2F5&kh1=变量姓名更新&kh2=11&cg1=222&cg2=都是对的多所&kh5=辅导辅导辅导地方&kh6=&kh7=&kh8=''",
"target": "1A1630EDEEB6C255-9ada7700aeece672"
},
{
"p_attr_1": "¥1000",
"p_attr_2": "x100",
"p_img": "https://ysf.nosdn.127.net/faff3a003f3ec9ba47a89ce73f4d7a4a?imageView",
"p_title": "Xiaomi/小米小米9透明九se故宫版10尊享探索plus全新手机骁龙855",
"p_sub_title": "Xiaomi/小米",
"p_attr_3": "卖家已发货",
"type": "block",
"params": "_preRequestId=2f63b0c4-6ce9-448e-9bad-bfc483086ed8&_sessionId=6680534596&_preNodeId=1A1630EDEEB6C255-17c082362a34a2b8&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-E540D1C13A9EB2F5&kh1=变量姓名更新&kh2=11&cg1=222&cg2=都是对的多所&kh5=辅导辅导辅导地方&kh6=&kh7=&kh8=''",
"target": "1A1630EDEEB6C255-9ada7700aeece672"
},
{
"p_attr_1": "¥1000",
"p_attr_2": "x100",
"p_img": "https://ysf.nosdn.127.net/faff3a003f3ec9ba47a89ce73f4d7a4a?imageView",
"p_title": "Xiaomi/小米小米9透明九se故宫版10尊享探索plus全新手机骁龙855",
"p_sub_title": "Xiaomi/小米",
"p_attr_3": "卖家已发货",
"type": "block",
"params": "_preRequestId=2f63b0c4-6ce9-448e-9bad-bfc483086ed8&_sessionId=6680534596&_preNodeId=1A1630EDEEB6C255-17c082362a34a2b8&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-E540D1C13A9EB2F5&kh1=变量姓名更新&kh2=11&cg1=222&cg2=都是对的多所&kh5=辅导辅导辅导地方&kh6=&kh7=&kh8=''",
"target": "1A1630EDEEB6C255-9ada7700aeece672"
}
]
}
}
}
]
}
}
用户点击一个卡片后,发送的workflow类型消息体格式:
{
"templateId": "qiyu_template_item",
"params": "_preRequestId=2f63b0c4-6ce9-448e-9bad-bfc483086ed8&_sessionId=6680534596&_preNodeId=1A1630EDEEB6C255-17c082362a34a2b8&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-E540D1C13A9EB2F5&kh1=变量姓名更新&kh2=11&cg1=222&cg2=都是对的多所&kh5=辅导辅导辅导地方&kh6=&kh7=&kh8=''",
"target": "1A1630EDEEB6C255-9ada7700aeece672",
"template": {
"p_attr_1": "¥1000",
"p_attr_2": "x100",
"p_title": "Xiaomi/小米小米9透明九se故宫版10尊享探索plus全新手机骁龙855",
"p_img": "https://barry.qiyukf.net/faff3a003f3ec9ba47a89ce73f4d7a4a?imageView",
"p_sub_title": "Xiaomi/小米",
"p_attr_3": "卖家已发货"
}
}
用户点击查看更多后,发送的workflow类型消息体格式:
{
"template": {
"label": "换一批"
},
"templateId": "qiyu_template_text",
"target": "1A1630EDEEB6C255-17c082362a34a2b8",
"params": "_preRequestId=2f63b0c4-6ce9-448e-9bad-bfc483086ed8&_sessionId=6680534596&_preNodeId=1A1630EDEEB6C255-17c082362a34a2b8&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-E540D1C13A9EB2F5¤tPage=2&pageSize=10"
}
返回示例11:一触即达流程回复-查询节点-输出样式-气泡节点列表样式
{
"code": 200,
"message": "哈哈",
"data": {
"sessionId": 62927,
"userId": 43412123,
"robotId": 34351,
"answerList": [
{
"msgId": "21323",
"ansType": 7,
"ansContent": {
"templateId": "bubble_node_list",
"templateData": {
"label": "引导语",
"title": {
"label": "banner标题"
},
"empty_list_hint": "无数据返回提示文案",
"action": {
"label": "查看更多",
"type": "url",
"params": "_preRequestId=d9322b0c-03fe-4469-9482-e5f3063afdf1&_sessionId=6681684506&_preNodeId=1A1630EDEEB6C255-aa1ef9707ee38676&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-8B261AFF7FF91CD5&nodeId=1A1630EDEEB6C255-f518e7de44485d1f",
"target": "https://qiyukf.com"
},
"list": [
{
"p_title": "业务员二片区岸上蓝山正在第1次派件",
"p_desc": "2017-05-17 18:01:38",
"p_is_current": "1"
},
{
"p_title": "业务员二片区岸上蓝山正在第2次派件",
"p_desc": "2017-05-17 18:01:38",
"p_is_current": "0"
},
{
"p_title": "业务员二片区岸上蓝山正在第3次派件",
"p_desc": "2017-05-17 18:01:38",
"p_is_current": "0"
},
{
"p_title": "业务员二片区岸上蓝山正在第4次派件",
"p_desc": "2017-05-17 18:01:38",
"p_is_current": "0"
},
{
"p_title": "业务员二片区岸上蓝山正在第5次派件",
"p_desc": "2017-05-17 18:01:38",
"p_is_current": "0"
},
{
"p_title": "业务员二片区岸上蓝山正在第6次派件",
"p_desc": "2017-05-17 18:01:38",
"p_is_current": "0"
},
{
"p_title": "业务员二片区岸上蓝山正在第7次派件",
"p_desc": "2017-05-17 18:01:38",
"p_is_current": "0"
}
]
}
}
}
]
}
}
用户点击查看更多后,若为block类型则发送的workflow类型消息体格式:
{
"templateId": "bubble_node_list",
"target": "1A1630EDEEB6C255-17c082362a34a2b8",
"params": "_preRequestId=d9322b0c-03fe-4469-9482-e5f3063afdf1&_sessionId=6681684506&_preNodeId=1A1630EDEEB6C255-aa1ef9707ee38676&_token=c5df9226f6a0371d70f3986caf65e474&_flowId=1A1630EDEEB6C255-8B261AFF7FF91CD5&nodeId=1A1630EDEEB6C255-f518e7de44485d1f"
}
返回参数说明
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
sessionId | 是 | long | 当前机器人会话id |
userId | 是 | long | 当前访客在七鱼系统里的userId |
robotId | 是 | long | 当前机器人会话所在的机器人id |
answerList | 是 | List<Object> | 回复的消息列表 |
answerList.get(0).msgId | 是 | string | 机器人回复消息id |
answerList.get(0).ansType | 是 | integer | 机器人回复类型,这个字段决定了回复内容ansContent数据格式,枚举值:1-精准回复 2-推荐回复 4-未知回复 7-流程节点回复 10-触发转人工 |
answerList.get(0).ansContent | 是 | object | 机器人回复内容,需按回复类型ansType解析 |
answerList.get(0).msgEvaluation | 否 | object | 消息评价相关信息 |
answerList.get(0).msgEvaluation.evaluation | 是 | integer | 是否显示评价 0-不显示评价 1-显示评价 |
answerList.get(0).msgEvaluation.evaluationReason | 否 | integer | 是否可填写评价原因,0-不填写 1-可填写 |
answerList.get(0).msgEvaluation.evaluationGuide | 否 | string | 消息评价引导语 |
ansContent格式说明:ansType=1
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
answer | 是 | CommonMsg | 回复内容,这里的消息类型支持:text/richtext/workflow,字段格式详细介绍见通用数据结构说明 |
connectQuestions | 否 | List<SimpleQuestion> | 当前回复 关联的问题列表,字段格式详细介绍见通用数据结构SimpleQuestion说明 |
ansContent格式说明:ansType=2
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
recommandGuide | 是 | string | 相似问题引导文案 |
recommandQuestions | 是 | List<SimpleQuestion> | 当前推荐的问题列表,字段格式详细介绍见通用数据结构SimpleQuestion说明 |
ansContent格式说明:ansType=4
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
silence | 是 | integer | 未知问题回复/情绪安抚语类型,0-按answer回复,1-静默处理不回复 |
answer | 否 | CommonMsg | 回复内容,这里的消息类型支持:text/richtext,字段格式详细介绍见通用数据结构说明 |
ansContent格式说明:ansType=10
转人工事件,此时 ansContent 即为CommonMsg格式,消息类型为event_trans,字段格式详细介绍见通用数据结构说明;
ansContent格式说明:ansType=7
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
templateId | 是 | string | 一触即达样式模版id,模版id决定了templateData的数据格式,枚举值:static_union图文按钮样式、reply_asked反问样式、radio_button对话样式、drawer_list抽屉列表样式、bubble_list气泡列表样式、horizontal_sliding_list横滑列表样式 |
templateData | 是 | object | 一触即达样式模版内容,需按templateId区分解析 |
templateData格式说明:templateId=static_union
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
unions | 是 | List<Object> | 图文按钮混合数据列表 |
unions数据项object格式说明:
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
type | 是 | string | 当前数据类型,枚举值:richText-富文本消息,link-可点击消息 |
detail | 是 | object | 数据内容,需按type类型区分解析 |
detail数据object格式说明:type=richText
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
label | 是 | string | 富文本消息内容 |
detail数据object格式说明:type=link
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
style | 是 | string | 展示样式,button-按钮样式 |
label | 是 | string | 用于展示的文案内容 |
params | 是 | string | 节点参数,用于点击后回传使用 |
type | 是 | string | 当前点击后行为类型,枚举值:url-点击跳转外部链接,block-点击跳转到下一个一触即达节点 |
target | 是 | string | type=url时,该值为外部链接地址;type=block时,该值为下一个一触即达节点id |
templateData格式说明:templateId=reply_asked
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
label | 是 | string | 反问的引导文案 |
list | 是 | List<Object> | 反问的可选择问题列表 |
list数据object格式说明:
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
id | 是 | long | 问题id |
params | 是 | string | 节点参数,用于点击后回传使用 |
type | 是 | int | 问题类型 |
knowledge | 是 | string | 问题内容 |
templateData格式说明:templateId=radio_button
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
button_type | 是 | string | 对话节点可选项类型,radio-单选 |
label | 是 | string | 对话节点引导文案 |
list | 是 | List<Object> | 对话节点可选项列表 |
list数据object格式说明:
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
style | 是 | string | 选项样式,button-按钮样式 |
label | 是 | string | 选项文案 |
type | 是 | string | 选项类型,radio-单选 |
templateData格式说明:templateId=drawer_list
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
tab_id | 是 | int | 当前所在tab |
empty_list_hint | 是 | string | 无数据时的文案 |
label | 是 | string | 引导文案 |
title | 是 | string | 标题 |
tabList | 是 | List<Object> | tab数据列表 |
tabList数据object结构说明:
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
tab_id | 是 | string | 子tabid |
tab_name | 是 | string | 子tab名字 |
action | 是 | object | 子tab翻页加载参数 |
list | 是 | List<Object> | 子tab数据项列表 |
action数据object格式说明:
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
label | 是 | string | 加载下一页的引导文案 |
type | 是 | string | 节点类型,block-内部节点 url-跳外部链接 |
params | 是 | string | 节点参数,用于点击后回传使用 |
target | 是 | string | type=block时为节点id,用于点击后回传使用;type=url时为点击跳转地址 |
list数据object格式说明:
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
p_attr_1 | 否 | string | 卡片属性1 |
p_attr_2 | 否 | string | 卡片属性2 |
p_attr_3 | 否 | string | 卡片属性3 |
p_img | 否 | string | 图片 |
p_title | 否 | string | 标题 |
p_sub_title | 否 | string | 子标题 |
p_item_type | 否 | string | 自定义类型,0-详情 1-分组 |
type | 是 | string | 点击类型,block-节点跳转 url-链接跳转 display-只展示 |
params | 是 | string | 节点参数,用于点击后回传使用 |
target | 是 | string | 节点id,用于点击后回传使用 |
templateData格式说明:templateId=bubble_list
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
empty_list_hint | 是 | string | 无数据时的文案 |
label | 是 | string | 引导文案 |
title | 是 | string | 标题 |
action | 是 | object | tab翻页加载参数 |
list | 是 | List<Object> | tab数据列表 |
action数据格式 和 list数据格式,同上templateId=drawer_list时的action和list结构
templateData格式说明:templateId=horizontal_sliding_list
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
empty_list_hint | 是 | string | 无数据时的文案 |
label | 是 | string | 引导文案 |
action | 是 | object | tab翻页加载参数 |
list | 是 | List<Object> | tab数据列表 |
action数据格式 和 list数据格式,同上templateId=drawer_list时的action和list结构
templateData格式说明:templateId=bubble_node_list
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
empty_list_hint | 是 | string | 无数据时的文案 |
label | 是 | string | 引导文案 |
title | 否 | object | banner信息 |
action | 否 | object | 翻页加载参数 |
list | 是 | List<Object> | 数据项列表 |
title数据object格式说明:
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
label | 是 | string | banner文案 |
list数据object格式说明:
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
p_title | 否 | string | 标题 |
p_desc | 否 | string | 描述 |
p_is_current | 是 | string | 是否停留在当前节点:1-是 0-否 |
action数据格式,同上templateId=drawer_list时的action结构
# 机器人回复消息评价
简要描述:
- 访客对机器人消息的评价。机器人回复访客后,根据回复数据里的消息评价信息,接入方可实现消息评价功能。通过此接口将评价信息传递到七鱼机器人平台,用于生成知识纬度的评价统计报表,便于接入方实现机器人数据分析。同时,可基于消息差评转人工功能,实现访客差评时自动转接人工客服功能,提交访客咨询满意度。
- 消息评价的时间不做限制,可以在会话中评价,也可以在会话结束后评价,由接入方按需对接即可。
请求URL:
/openapi/robot/session/msgEvaluation
请求方式:
- POST
参数:
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
msgId | 是 | string | 被评价的机器人消息id,从机器人回复消息内容中取msgId |
evaluation | 是 | int | 机器人回复有用无用,2-有用 3-无用 |
evaluationContent | 否 | string | 机器人回复无用(evaluation=3)具体原因 |
返回示例
{
"code": 200,
"message": "哈哈",
"data": {
"sessionId": 62927,
"userId": 43412123,
"robotId": 34351,
"transEvent": {
"msgType": "event_trans",
"msgBody": {
"closeReason": 31,
"transGuide": "转人工引导语"
}
}
}
}
返回参数说明
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
sessionId | 是 | long | 当前机器人会话id |
userId | 是 | long | 当前访客在七鱼系统里的userId |
robotId | 是 | long | 当前机器人会话所在的机器人id |
transEvent | 否 | CommonMsg | 消息评价是否触发转人工事件,为空表示未触发,非空则消息类型为:event_trans,字段格式详细介绍见通用数据结构说明 |
# 机器人会话满意度评价
简要描述:
- 访客评价当前机器人整体服务。接入方实现此接口,将访客对机器人整体服务的反馈信息传递到七鱼机器人平台,用于生成会话纬度的满意度统计报表,便于接入方实现机器人数据分析。
- 接入方需根据评价设置接口中返回的list数组显示满意度评价项,name 为评价项名称,value 为对应评价值,访客选择某评价项时,将对应 value 值作为下面接口参数 evaluation 的参数值。
- 会话评价的时间不做限制,可以在会话中评价,也可以在会话结束后评价,由接入方按需对接即可。
请求URL:
/openapi/robot/session/evaluation
请求方式:
- POST
参数:
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
sessionId | 是 | long | 被评价的机器人会话id,从会话/消息相关接口返回数据中取sessionId |
evaluation | 是 | int | 机器人会话满意度得分分值,按五级满意度模式区分分值,可取值:1-非常不满意 25-不满意 50-一般 75-满意 100-非常满意 |
evaluationResolved | 否,默认0 | integer | 机器人会话是否已解决访客问题,0-未选择,1-已解决 2-未解决 |
remarks | 否 | string | 机器人会话评价备注信息 |
tagList | 否 | List<string> | 机器人会话评价时,访客选择的标签 |
返回示例
{
"code": 200,
"message": "哈哈",
"data": {
"sessionId": 62927,
"userId": 43412123,
"robotId": 34351,
"evaluationThanks": {
"msgType": "richText",
"msgBody": {
"content": "<p>会话评价感谢文案</p>"
}
}
}
返回参数说明
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
sessionId | 是 | long | 当前机器人会话id |
userId | 是 | long | 当前访客在七鱼系统里的userId |
robotId | 是 | long | 当前机器人会话所在的机器人id |
evaluationThanks | 否 | CommonMsg | 机器人会话评价感谢文案,这里的消息类型支持:text/richtext,字段格式详细介绍见通用数据结构说明 |
# 关闭机器人会话
简要描述:
- 主动关闭一个机器人会话。当访客主动离开或者主动接入到人工客服时,接入方可通过此接口,将访客关闭机器人会话原因传递到七鱼机器人平台,平台会按转人工具体类型生成相应的统计数据报表。
- 若未主动调用此接口,则七鱼系统会在访客未说话10分钟后自动关闭这一通机器人会话。
- 会话关闭后将会生成对应的 会话历史记录,会话纬度统计数据,消息纬度统计数据,知识纬度统计数据,转人工纬度统计数据等,接入方可在七鱼机器人平台查看相应数据,便于管理和分析数据。
请求URL:
/openapi/robot/session/close
请求方式:
- POST
参数:
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
uid | 是 | string | 访客在调用方系统里的标志,用于唯一确定用户身份 |
productId | 否 | string | 当前咨询应用唯一标识,可以是 Android 应用的包名,iOS 应用的 bundleid,微信公众号appid等。调用方系统如果有多个应用需要接入七鱼时,对不同应用需保证该字段值的唯一性 |
closeReason | 是 | integer | 关闭机器人会话原因,1-访客离开 30-访客主动转人工 |
返回示例
{
"code": 200,
"message": "哈哈",
"data": {
"sessionId": 62927,
"userId": 43412123,
"robotId": 34351
}
返回参数说明
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
userId | 是 | long | 当前访客在七鱼系统里的userId |
sessionId | 否 | long | 当前机器人会话id |
robotId | 否 | long | 当前机器人会话所在的机器人id |
# 文件上传
简要描述:
- 语音文件上传接口。调用方可通过此接口上传语音文件,获取生成的语音文件地址,并通过发送msgType = audio 类型的语音消息到七鱼机器人平台,实现机器人短语音回复功能。
- 上传文件时,同样需要计算checksum,此时checksum的md5为文件内容md5的小写。文件大小限制 5M。
请求URL:
/openapi/robot/session/uploadFile
请求方式:
- POST,Content-Type: multipart/form-data
返回示例
{
"code": 200,
"message": "哈哈",
"data": {
"url": "http://ysf.nosdn.qiyukf.com/xxxxxxx"
}
返回参数说明
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
url | 是 | string | 文件下载地址 |
# 机器人辅助人工客服
简要描述:
- 机器人辅助人工客服接口。调用方可基于此接口,在人工会话过程中,实现机器人辅助客服回答功能,提高客服应答效率。
- 该接口仅基于当前输入消息做语义理解,返回最佳的FAQ回复,不包含上下文纬度语义理解,不生成历史记录。
请求URL:
/openapi/robot/session/assist
请求方式:
- POST
参数:
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
robotId | 否 | long | 机器人id,未指定时取默认机器人 |
content | 是 | string | 访客当前文本消息内容 |
uid | 否 | string | 访客在调用方系统里的标志,用于唯一确定用户身份 |
fromType | 否 | string | 当前访客咨询来源渠道 |
productId | 否 | string | 当前咨询应用标识,可以是 Android 应用的包名,iOS 应用的 bundleid,微信公众号appid等 |
fromPage | 否 | string | 当前访客咨询来源页面 |
返回示例
{
"code": 200,
"message": "哈哈",
"data": {
"assistType": 1,
"assistContent": [
{
"question": {
"question": "辅助问题1",
"type": 1
},
"answer": {
"msgType": "richText",
"msgBody": {
"content": "<p>这是一个富文本答案</p>"
}
}
}
]
}
}
返回参数说明
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
assistType | 是 | integer | 机器人辅助回复类型,枚举值:1-精准回复 2-推荐回复 4-未匹配 |
assistContent | 否 | List | 辅助回复答案,assistType=1时有且仅有1个问答对,assistType=2时有1-3个问答对 |
assistContent[0].question | 是 | SimpleQuestion | 机器人匹配到的FAQ问题 |
assistContent[0].answer | 是 | CommonMsg | 机器人匹配到的FAQ问题的答案,这里的消息类型支持:text/richtext,字段格式详细介绍见通用数据结构说明 |
# 获取机器人切换配置
简要描述:
- 通过接口指定机器人id,获取管理端机器人转接中配置的切换信息,禁用状态的机器人不再返回。若固定入口开关处于关闭状态,将返回空值。
请求URL:
/openapi/robot/transfer/config
请求方式:
- POST
频率限制:
- 1次/秒
参数:
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
robotId | 是 | long | 机器人id |
返回示例
{
"code": 200,
"message": "哈哈",
"data": {
"entranceTips": "切换业务",
"entranceGuide": "请选择要咨询的业务",
"transferList": [
{
"robotId": 10000,
"robotName": "小七",
"realName": "小七",
"biz_name":"手机业务",//对外展示业务名称
"group_id":131323, //转人工分流组
"portraitUrl": "https://ysf.qiyukf.net/operation/49f100747e5fd65876961f9225516ebb"
}
]
}
}
返回data参数说明
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
entranceTips | 是 | string | 切换机器人引导短语 |
entranceGuide | 是 | string | 切换机器人引导语 |
transferList[0].robotId | 是 | long | 机器人id |
transferList[0].robotName | 是 | string | 机器人对外名称 |
transferList[0].realName | 是 | string | 机器人对内名称 |
transferList[0].portraitUrl | 是 | string | 机器人头像 |
transferList[0].bizName | 是 | string | 对外展示业务名称 |
transferList[0].groupid | 是 | long | 转人工分流组id |
# 微信公众号切换机器人
简要描述:
- 针对微信公众号切换机器人场景,企业可以通过自定义H5页面,访客在H5页面选择机器人后发送请求到企业服务器,由企业后端通过调用此接口实现机器人切换
请求URL:
/openapi/robot/session/transfer
请求方式:
- POST
频率限制:
- 1次/秒
参数:
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
robotId | 是 | long | 目标机器人id |
appId | 是 | string | 微信公众号appid |
fromAccount | 是 | string | 访客标识 |
groupId | 是 | long | 转人工分流组id,默认0不指定转人工分流组 |
返回示例
{
"code": 200,
"message": "哈哈",
"data": true
}
}
返回data参数说明
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
data | 是 | boolean | true-切换成功,false-切换失败 |
# 企业微信切换机器人
简要描述:
- 针对企业微信切换机器人场景,企业可以通过自定义H5页面,访客在H5页面选择机器人后发送请求到企业服务器,由企业后端通过调用此接口实现机器人切换
请求URL:
/openapi/robot/session/wxWork/transfer
请求方式:
- POST
频率限制:
- 1次/秒
参数:
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
robotId | 是 | long | 目标机器人id |
wxWorkCorpId | 是 | string | 企业微信的企业ID,在企业微信后台企业信息中查看 |
wxWorkAgentId | 是 | string | 企业我先应用agentId |
fromAccount | 是 | string | 访客访客企业微信账号 |
groupId | 是 | long | 转人工分流组id,默认0不指定转人工分流组 |
返回示例
{
"code": 200,
"message": "哈哈",
"data": true
}
}
返回data参数说明
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
data | 是 | boolean | true-切换成功,false-切换失败 |