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

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"
}

注意:

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

返回值:

字段 含义
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": "2018-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 扣费失败(可以联系商务同事)