注意,本接口的使用需要进行接口鉴权

Xbot机器人接口对接

机器人接口简介: 首先使用初始化接口创建会话,代表与机器人的一次会话,之后使用sid去调用机器人问答接口。问答接口会将问题解析为关键字去匹配机器人问答库,然后将匹配到的答案返回。

1.机器人初始化接口

  • HTTP请求方式:POST

  • 请求地址:{HOST}/dingzhi/xbot/initSession/{ACCOUNTID}?sig={sig}

  • 请求时请将{HOST}换成对接数据查询中获取到的请求域名,{ACCOUNTID}替换为账户编号,{SIG}是根据鉴权规则生成的,请看鉴权文档,查看具体的生成规则

  • 鉴权文档:接口鉴权

  • 请求示例:

https://apis.7moor.com/dingzhi/xbot/initSession/N00000000556
?sig=41276A8E7767352A0FE7456D20F03D3
  • 请求体:
{
  "botid": "d4302e91dc944ab1ac0b9dce58f5929b",
  "sid": "4734c140a8af49d0bcb606fc125c202b",
  "distribute_channel": "pc",
  "user_ip": "124.206.192.2",
  "system_args": {
        "system_userID":"213143",       //访客id
        "system_Ip":"124.206.192.2",    //ip
        "system_nickName":"马云",       //访客名称
        "system_platform":"web",        //来源
        "system_accessName":"北京测试", //接入渠道
        "vip":"true"                    //一问多答的字段值
   }
}

注意:

botid xbot机器人的唯一id,后台查看
sid 会话id,格式为:数字、字母、下划线、横线组合而成,长度为15-40个字符。
distribute_channel 会话来源,pc,wap为网站,sdk为移动app ,weixin为公众号,wxmini为小程序,weibo为微博
user_ip 访客ip
system_args 访客这边调用机器人接口传给机器人的参数

返回值:

字段 含义
avatar 头像
nickname 机器人昵称
description 机器人的相关描述
enable_common 常见问题推荐开关:0关闭,1开启,默认为0
common_language 常见问题推荐引导语
common_questions 常见问题推荐,存标准问题
enable_emoji 表情回复开关:0关闭,1开启,默认1
satisfied_switch 满意度评价开关:0关闭,1开启,默认1
enable_is_useful 知识点有用无用评价开关
wrong_text 非文本问题回复
association_input_switch 联想输入开关:0关闭,1开启,默认1
  • 初始化成功返回示例:
{
  "avatar": "1",
  "nickname": "昵称",
  "description": "对机器人的相关描述",
  "enable_common": 1,
  "common_language": "常见问题推荐引导语",
  "common_questions": [
    '今天天气如何',
    '今天天气如何啊'
  ],
  "enable_emoji": 1,
  "satisfied_switch": 1,
  "enable_is_useful": 1,
  "wrong_text": "暂时只支持文字的回复哦~",
  "association_input_switch": 1
}

2.机器人问答接口

  • HTTP请求方式:POST

  • 请求地址:{HOST}/dingzhi/xbot/query/{ACCOUNTID}?sig={sig}

  • 请求时请将{HOST}换成对接数据查询中获取到的请求域名,{ACCOUNTID}替换为账户编号,{SIG}是根据鉴权规则生成的,请看鉴权文档,查看具体的生成规则

  • 鉴权文档:接口鉴权

  • 请求示例:

http://apis.7moor.com/dingzhi/xbot/query/N00000000556
?sig=41276A8E7767352A0FE7456D20F03D3
  • 请求体:
{
  "sid": "4734c140a8af49d0bcb606fc125c202b",
  "msg": "有多少人?"
}

返回值:

字段 含义
sid 每个会话的唯一标识
botid 机器人id
msg 提示给用户的信息
turn_human 触发转人工时,值为ture
bot2human_reason 触发转人工时出现,3无答案,4负面情绪,5重复提问(同close _session接口)(1.8版本新增)
q_list nlp匹配到的除置信度最高的 问题(std_question)之外的所 有问题(含相似问)
q_list_std 只匹配标准问题,用于“我猜你想问:”的推荐问题

log:

channel 0为API,1为web
user_region 用户省份
user_type 0为访客,1为xbot,2为座席
msg_type 0为文本,1为其他
msg_time 消息时间
confidence 机器人回答置信度
ori_question 用户原始问句
std_question 标准问题
source 消息来源
distribute_channel_label 用户自定义渠道标签
sentiment 用户问句情绪

  • 返回示例:
{
  "sid": "1234",
  "botid": "test-botid",
  "msg": "您好,很高兴为您服务,请问有什么可以帮助您",
  "turn_human": true,
  "bot2human_reason": 3,
  "q_list": [
    "xxxxx",
    "xxxxx",
    "xxxxx"
  ],
   "q_list_std": [
    "xxxxx",
    "xxxxx",
    "xxxxx"
  ],
  "log": {
    "channel": 1,
    "user_region": "河北省",
    "user_type": 1,
    "msg_type": 0,
    "msg_time": "2020-06-08 17:03:30",
    "confidence": 0.8,
    "ori_question": "xxxx",
    "std_question": "xxxx",
    "source": 1,
    "distribute_channel_label": "weixin",
    "sentiment": "neutral"
  }
}

3.会话关闭或者转人工

注意:初始化后,一定要记得会话关闭。

  • HTTP请求方式:POST

  • 请求地址:{HOST}/dingzhi/xbot/closeSession/{ACCOUNTID}?sig={SIG}

  • 请求时请将{HOST}换成对接数据查询中获取到的请求域名,{ACCOUNTID}替换为账户编号,{SIG}是根据鉴权规则生成的,请看鉴权文档,查看具体的生成规则

  • 鉴权文档:接口鉴权

  • 请求示例:
http://apis.7moor.com/dingzhi/xbot/closeSession/N00000000556
?sig=41276A8E7767352A0FE7456D20F03D3
  • 请求体:
{
  "sid": "4734c140a8af49d0bcb606fc125c202b",
  "reason": 2,
  "satisfaction": 3,
  "bot2human_reason": 1
}

请求值:

字段 含义
sid 会话唯一标识的id
reason 关闭原因:1是会话结束关闭;2是会话已转人工
satisfaction 会话满意度:不传代表未评价,1是满意,3是不满意
bot2human_reason 转人工原因:1是点击转人工;2是关键词转人工;3是无答案;4是负面情绪;5是重复提问,注意reason为2时该值必填
  • 返回示例:
{
    "success": true,
    "message": "200 ok!"
}

返回错误码:

error_code 描述 备注
1001 Missing argument {arg_name} 缺少必要请求参数
1002 bot {botid} not exist 机器人不存在
1003 bot{botid}has expired 机器人已过期
1004 invalid sid sid不合法
1005 msg can not be empty 消息为空
1006 session {sid} not exists or have been closed 会话不存在或者已经关闭
1007 invalid distribute_channel 接入渠道不合法
1008 invalid user_ip user_ip不合法
1009 invalid close reason 会话关闭原因不合法
1010 invalid bot2human_reason 转人工原因不合法
1011 invalid satisfaction 满意度不合法
10001 unopened robot package or debt 欠费或计费异常(可以联系商务同事)
10002 failure in charging and deducting fees 扣费失败(可以联系商务同事)

4.知识库接口

4.1 新增知识库分类

  • HTTP请求方式:POST

  • 请求地址:{host}/knowledge/knowledgeService/knowledgeBaseCreate/{account}?sig={SIG}

  • 请求时请将{HOST}换成对接数据查询中获取到的请求域名,{ACCOUNTID}替换为账户编号,{SIG}是根据鉴权规则生成的,请看鉴权文档,查看具体的生成规则

  • 鉴权文档:接口鉴权

  • 请求体:
{
    "bot_id":"c367d6d20a994ee6a0de1bc76b4e9278",
    "type_list": [
        {
            "type_name": "weqweq",
            "parent_id": "9600203aceff464eb2464d2b8f8dd5cc",
            "pre_id": "1"
        },
        {
            "type_name": "vefwfwefw",
            "parent_id": "9600203aceff464eb2464d2b8f8dd5cc",
            "pre_id": "1"
        }
    ]
}

请求值:

参数 类型 是否必填 说明
bot_id String 机器人编号
type_list object 数据数组,单次限制20条
parent_id String 父级分类id
pre_id String 同级别队列前一位Id,代表分类的排列顺序
type_name String 分类名称,不能重复,否则会返回空
  • 返回值示例:
{
    "code": 200,
    "data": [{
        "create_datetime": "2020-08-12T10:26:47",
        "enable": 1,
        "id": "d9f1985d9ca3431194c9ee43c7283e48",
        "parent_id": "92f36eae2ec442df944e713e8108e526",
        "pre_id": 23,
        "type_name": "test-3-25"
    }, {
        "create_datetime": "2020-08-12T10:26:47",
        "enable": 1,
        "id": "9d89306b666147c39194caef41c5e907",
        "parent_id": "92f36eae2ec442df944e713e8108e526",
        "pre_id": 27,
        "type_name": "test-3-27"
    }],
    "mssage": "success"
}

4.2 查询知识库分类

  • HTTP请求方式:POST

  • 请求地址:{host}/knowledge/knowledgeService/knowledgeBaseQuery/{account}?sig={SIG}

  • 请求时请将{HOST}换成对接数据查询中获取到的请求域名,{ACCOUNTID}替换为账户编号,{SIG}是根据鉴权规则生成的,请看鉴权文档,查看具体的生成规则

  • 鉴权文档:接口鉴权

  • 请求体:
{
    "bot_id": "b43e98c375394a94ab6fef4e08822b39",
    "page_num": 1,
    "page_size": 20
}

请求值:

参数 类型 是否必填 说明
bot_id String 机器人编号
type_id String 分类名称,当有id时返回对应id对应当分类信息
type_name String 分类名,模糊搜索,返回分类当信息
page_num int 页码,默认为1
page_size int 页面大小,默认为10,上限50
  • 返回值示例:
{
    "code": 200,
    "data": {
        "list": [{
            "create_datetime": "2020-08-11T10:27:23",
            "enable": 1,
            "id": "11aea82091ff422a94a9309d890ad850",
            "parent_id": "92f36eae2ec442df944e713e8108e526",
            "pre_id": 1,
            "type_name": "test-3"
        }],
        "total": 1
    },
    "mssage": "success"
}

4.3 修改知识库分类

  • HTTP请求方式:POST

  • 请求地址:{host}/knowledge/knowledgeService/knowledgeBaseUpdate/{account}?sig={SIG}

  • 请求时请将{HOST}换成对接数据查询中获取到的请求域名,{ACCOUNTID}替换为账户编号,{SIG}是根据鉴权规则生成的,请看鉴权文档,查看具体的生成规则

  • 鉴权文档:接口鉴权

  • 请求体:
{
    "bot_id": "c367d6d20a994ee6a0de1bc76b4e9278",
    "type_list": [{
        "type_id": "a89b923549f84b7d9e39c611d1e18e59",
        "type_name": "我要修改它"
    }, {
        "type_id": "c6b26a4fc48d44c2b8f7bc810083c153",
        "parent_id": "9600203aceff464eb2464d2b8f8dd5cc",
        "pre_id": 1,
        "type_name": "我要修改它2"
    }]
}

请求值:

参数 类型 是否必填 说明
bot_id String 机器人编号
type_list object 数据数组,单次限制20条
parent_id String 父级分类id
pre_id String 同级别队列前一位Id,默认为0
type_name String 分类名称
type_id String 分类id
  • 返回值示例:
{
    "code": 200,
    "message": "success"
}

4.4 删除指定知识库分类

  • HTTP请求方式:POST

  • 请求地址:{host}/knowledge/knowledgeService/knowledgeBaseDelete/{account}?sig={SIG}

  • 请求时请将{HOST}换成对接数据查询中获取到的请求域名,{ACCOUNTID}替换为账户编号,{SIG}是根据鉴权规则生成的,请看鉴权文档,查看具体的生成规则

  • 鉴权文档:接口鉴权

  • 请求体:
{
    "bot_id": "c367d6d20a994ee6a0de1bc76b4e9278",
    "type_id": "a89b923549f84b7d9e39c611d1e18e59"
}

请求值:

参数 类型 是否必填 说明
bot_id String 机器人编号
type_id String 分类id,多条用英文逗号分割,20上限,会删除子分类
  • 返回值示例:
{"code":200,"message":"success"}

4.5 新增知识点

  • HTTP请求方式:POST

  • 请求地址:{host}/knowledge/knowledgeService/knowledgeCreate/{account}?sig={SIG}

  • 请求时请将{HOST}换成对接数据查询中获取到的请求域名,{ACCOUNTID}替换为账户编号,{SIG}是根据鉴权规则生成的,请看鉴权文档,查看具体的生成规则

  • 鉴权文档:接口鉴权

  • 请求体:
{
    "bot_id": "c367d6d20a994ee6a0de1bc76b4e9278",
    "list": [{
        "type_id": "c6b26a4fc48d44c2b8f7bc810083c153",
        "knowledge": [{
                "question": "我是谁",
                "answer": "皮卡丘",
                "status": 1
            },
            {
                "question": "今年几岁",
                "answer": "111",
                "status": 1
            }
        ]
    }, {
        "type_id": "9600203aceff464eb2464d2b8f8dd5cc",
        "knowledge": [{
            "question": "你好",
            "answer": "I'm fine.Thanks",
            "status": 1
        }]
    }]
}

请求值:

参数 类型 是否必填 说明
bot_id String 机器人编号
list object 数据数组,单次限制500条
knowledge object 知识点内容列表
type_id String 分类id
question String 问题
answer String 答案
status int 开启状态:默认为1;0:下架1:上架
  • 返回值示例:
{
    "code": 200,
    "data": [{
        "answer": "皮卡丘",
        "id": "e120f42aca244e639fc4f650cba0b125",
        "question": "我是谁",
        "status": 1,
        "type_id": "c6b26a4fc48d44c2b8f7bc810083c153",
        "update_datetime": "2020-08-12T11:02:33"
    }, {
        "answer": "111",
        "id": "78bba8b42881433c887c60fdd9dade47",
        "question": "今年几岁",
        "status": 1,
        "type_id": "c6b26a4fc48d44c2b8f7bc810083c153",
        "update_datetime": "2020-08-12T11:02:33"
    }, {
        "answer": "I'm fine.Thanks",
        "id": "2d7feb35bf6f4963a2290ac65e34b078",
        "question": "你好",
        "status": 1,
        "type_id": "9600203aceff464eb2464d2b8f8dd5cc",
        "update_datetime": "2020-08-12T11:02:33"
    }],
    "message": "success"
}

4.6 查询知识点

  • HTTP请求方式:POST

  • 请求地址:{host}/knowledge/knowledgeService/knowledgeQuery/{account}?sig={SIG}

  • 请求时请将{HOST}换成对接数据查询中获取到的请求域名,{ACCOUNTID}替换为账户编号,{SIG}是根据鉴权规则生成的,请看鉴权文档,查看具体的生成规则

  • 鉴权文档:接口鉴权

  • 请求体:
{   
"bot_id":"c367d6d20a994ee6a0de1bc76b4e9278"
}

请求值:

参数 类型 是否必填 说明
bot_id String 机器人编号
knowledge_id String 知识点id,用英文逗号拼接
type_id String 分类id,用英文逗号拼接,不传查询所有分类的知识点
question String 问题,模糊搜索,返回知识点的信息
answer String 答案,模糊搜索,返回知识点的信息
page_num int 页码,不传默认为1
page_size int 页面大小,不传默认为10
  • 返回值示例:
{
    "code": 200,
    "data": {
        "list": [{
            "answer": "answer",
            "id": "381fbcfe6bbd49e5917bafb24af7125c",
            "question": "question",
            "status": 1,
            "type_id": "8bcf83aa3d58495d9473769763a946f0",
            "update_datetime": "2020-08-12T10:44:46"
        }],
        "total": 119
    },
    "message": "success"
}

4.7 修改知识点

  • HTTP请求方式:POST

  • 请求地址:{host}/knowledge/knowledgeService/knowledgeUpdate/{account}?sig={SIG}

  • 请求时请将{HOST}换成对接数据查询中获取到的请求域名,{ACCOUNTID}替换为账户编号,{SIG}是根据鉴权规则生成的,请看鉴权文档,查看具体的生成规则

  • 鉴权文档:接口鉴权

  • 请求体:
{
    "bot_id": "c367d6d20a994ee6a0de1bc76b4e9278",
    "list": [{
        "id": "77f9a65a9e1f4219bf2ffbff2bc2df46",
        "answer": "可达鸭"
    }, {
        "id": "201ecb067dce445c9cabfe42294d1e51",
        "question": "没有远方没有诗"
    }]

}

请求值:

参数 类型 是否必填 说明
bot_id String 机器人编号
list object 数据数组
id String 知识点id
question String 问题
answer String 答案
status int 开启状态:0:下架1:上架
  • 返回值示例:
{
    "code": 200,
    "message": "success"
}

4.8 删除指定知识点

  • HTTP请求方式:POST

  • 请求地址:{host}/knowledge/knowledgeService/knowledgeDelete/{account}?sig={SIG}

  • 请求时请将{HOST}换成对接数据查询中获取到的请求域名,{ACCOUNTID}替换为账户编号,{SIG}是根据鉴权规则生成的,请看鉴权文档,查看具体的生成规则

  • 鉴权文档:接口鉴权

  • 请求体:
{   
    "bot_id":"c367d6d20a994ee6a0de1bc76b4e9278",
    "knowledge_id":"201ecb067dce445c9cabfe42294d1e51"
}

请求值:

参数 类型 是否必填 说明
bot_id String 机器人编号
knowledge_id String 知识点id,多条用英文逗号分割,上限50
  • 返回值示例:
{
    "code": 200,
    "message": "success"
}

4.9 知识点点踩/点赞

  • HTTP请求方式:POST

  • 请求地址:{host}/dingzhi/xbot/logChatUseless/{account}?sig={SIG}

  • 请求时请将{HOST}换成对接数据查询中获取到的请求域名,{ACCOUNTID}替换为账户编号,{SIG}是根据鉴权规则生成的,请看鉴权文档,查看具体的生成规则

  • 鉴权文档:接口鉴权

  • 请求体:
{
    "bot_id": "8c811fc1bb074b828d2390cfd63f6d91",
    "session_id": "ca1d54f0-f28a-11ea-ad3f-5d27f5cf473a",
    "distribute_channel": "pc",
    "ori_question": "xxxx",
    "question": "xxxxx",
    "answer": "xxxxxx",
    "confidence": 0.8,
    "is_useful": false
}

请求值:

参数 类型 是否必填 说明
bot_id String 机器人编号
session_id String 会话编号
distribute_channel String pc或wap:网站sdk: 移动appseixin:微信公众号wxmini:微信小程序weibo:微博wxwork:企业微信call或other: 其他test: xbot后台测试窗口,不参与数据统计
question String 问题
answer String 答案
confidence float 0~100%,机器人回答置信度
is_useful boolean 点赞/点踩: true/false
ori_question boolean 原始问题
  • 返回值示例:
{
    "answer": "xxxxxx",
    "is_useful ": false,
    "ori_question": "xxxx"
}

5.机器人一问多答对接

  • 说明: 知识点一问多答。同一个问题,一问多答功能可根据访客标签信息进行不同答案 的回复。(不支持公众号、小程序和微博)

  • 场景举例:

    访客(会员身份):现在有什么活动吗?

    Bot:您可以参加以下会员活动......

    访客(非会员身份):现在有什么活动吗?

    Bot:对不起,您还不是会员,无法参加我们的活动哦......

  • 配置流程: 1、对接云客服系统时:在扩展信息字段(也是自定义信息)增加用户标签变量跟 xbot 关联起来,客服系统对接扩展信息,是json的key-value 形式。所以 key-value 分别对应 xbot 的标签和值。具体对接方面不清楚可以联系对接群 里 的技术。

  • 代码格式:

customField: { //扩展字段,json 对象,对象中的 key-value 都自定义 "user_labels":{ //xbot 一问多答标签传参 "city":"beijing" //city 为标签名,beijing 为值 } }
  • js 代码方式对接:

  • h5 代码方式对接:

  • 安卓sdk 代码方式对接:

  • iossdk 代码方式对接:

2、xbot 机器人里面设置标签与客服系统用户相关联,具体位置:机器人人设置- 高级设置-应用标签设置,给用户标签变量设置对应的别名以及标签值信息,如 vip 的标签值为 true、false,分别表示是、否。

3.知识库列表-知识点编辑,设置默认答案和答案

  • 默认答案:机器人未识别到对应的用户标签信息时进行回复的答案
  • 答案 1:可设置对应标签信息的答案,如会员标签为“是”的访客可回复答案 1,其他 情况 则回复默认答案。

一问多答案测试效果如下:

1、访客会员身份(vip)为是(true)时:

2、其他情况或者访客会员身份(vip)为是(false)时: