版本历史

版本号	时间	修改
1.0	2019-03-11
1.1	2019-04-01	修改DialogStage的返回参数
1.2	2019-09-18	新增一些接口参数
1.3	2019-11-04	更新接口描述
1.4	2020-03-04	更新接口描述

概述
接入准备
2.1 BOTID 和 TOKEN
2.2 编码格式
机器人对话接口请求和响应
3.1 接口调用请求说明
    1. 请求方法
    2. 请求地址
    3. 请求示例
    4. 请求参数
3.2 接口响应说明
    1. 响应格式
    2. 响应示例
    3. 响应字段
    4. 使用说明

1. 概述

本文档描述如何通过API接口调用形式来使用RSVP对话平台提供的对话服务。

2. 接入准备

2.1 BOTID 和 TOKEN##

BOTID 是客服机器人在RSVP平台内的唯一应用编码（切勿泄露）
TOKEN是客服机器人访问凭证，请妥善保存

2.2 编码格式

URL 的编码格式使用 UTF-8，拼接 URL 时请 Encode。
返回的结果编码格式同样使用 UTF-8。

3. 机器人对话接口请求和响应

3.1 接口调用请求说明：

HTTP方法：

GET

请求地址：

http://[host]:[port]/[endpoint]/chat

请求示例:

https://api.rsvp.ai/sandbox/chat?botid=999001&token=rsvpai&uid=123459&q=你好

请求参数：

Key	Type	Note	Default
基础参数
uid	String	必填，定位当前用户的当前会话的标识符
q	String	必填，发送给机器人的问题，例如：“您好”
token	String	必填，访问凭证，一串字符串，暂时不设过期时间，所以请不要泄漏
lang	String	可选，机器人或技能语言，可选“cn”或 “en”（中文和英文）	cn
botid	String	可选，但和skillid必须至少存在一个，在平台创建的机器人发布后会生成botid
skillid	String	可选，但和botid必须至少存在一个，在平台创建的技能创建后会生成skillid
stage	String	必选，指定机器人的版本，即调试版(test)或线上版(release)。若为空，则默认为test	test
开发者参数
botAppid	String	可选。在意图对话场景中，原bot id所对应的意图对话专用ID
labels	String	可选，问答对类别标签，可以是多个，标签之间以英文逗号分隔，例如：“Logo, Setting”
filterSkillid	String	可选，用以在机器人回答中优先回答某个技能下的问题
filterIntentids	String	可选，用以在机器人或技能回答中优先回答某个意图下的问题。可以是多个，以英文逗号分隔
showPartial	String	可选，true/false，意图对话中指定是否返回实例结果	false
threshold	String	可选，范围[0, 1]的实数，用以调整意图对话答案相似度的阈值	0.8
minscore	String	可选，范围[0, 1]的实数，用以调整问答对答案相似度的阈值	0.8
fuzz	String	可选，true/false，意图对话中开关模糊匹配功能。若为false，只有两个句子完全一样时才会命中	true

3.2 接口响应说明

响应格式：

Content-Type: application/json;charset=utf-8

响应示例（问答对）:

{
  "params":{
     "skillId":"1003064",
     "tid":"981b05d6-d0d4-4ce4-a007-1fee5c573290"
  },
  "stage": [{
    "message": "新的回答"
    "props": {
      "faq_info": {
        "candidates": [{
          "score": 1,
          "gid": "144617",
          "groupBusinessId":"",
          "question": "新的问题",
          "answer": "新的回答",
          "skillname":"faq_business",
          "labels": ["1"]
        },
        {
          "score": 0.9668123,
          "gid": "144618",
          "question": "新问题",
          "answer": "不同回答",
          "skillname":"faq_business",
          "labels": ["2"]
        }],
        "skillname":"faq_business",
        "gid": "144617",
        "groupBusinessId":"",
        "labels": ["1"]
      }
    },
  }],
  "status": 0,
  "topic": "faq"
}

响应示例（意图对话）:

{
   "params":{
      "skillId":"1001815",
      "intentSlots":{
         "地点":[
            {
               "slotType":"system_地点",
               "value":[
                  [
                     "0",
                     "北京",
                     "北京",
                     "中国",
                     "亚洲"
                  ]
               ],
               "key":"北京"
            }
         ]
      },
      "intentName":"天气测试",
      "nluSkillId":"402881436cdddd17016cdde307b105a9",
      "intentCandidates":[
         {
            "sentence":"北京真好",
            "skillid":"402881436cdddd17016cdde307b105a9",
            "score":1.0,
            "skilllevel":"open_m",
            "originalSkillid":"1001815",
            "name":"天气测试",
            "intentid":"402881436cdddd17016cdde307da05af",
            "fulfillment":false,
            "done":true,
            "slotProperties":{
               "地点":[
                  {
                     "slotType":"system_地点",
                     "value":[
                        [
                           "0",
                           "北京",
                           "北京",
                           "中国",
                           "亚洲"
                        ]
                     ],
                     "key":"北京"
                  }
               ]
            }
         }
         {
             【其他回答】
         }
      ],
      "tid":"4f9a2671-2de8-469d-a12f-86509ab5f9f5"
   },
   "stage":[
      {
         "message":"北京真好"
      }
   ],
   "status":0,
   "topic":"nlu_skill"
}

响应字段：

Key	Type	Note
status	int	结果状态（0代表成功，-1代表失败）
topic	String	分类主题，领域信息
stage	JSONArray	回复列表，是 DialogStage数组

响应参数详细说明:

DialogStage对象的详细字段如下表

Name	Type	Note
message	String	回复的信息文本
url	String	播放的音频地址
image	String	显示的图片地址
props	Map	`[可选]` 当topic是faq时，从中获取key为“faq_info”的对象,详见下表FaqInfo
action	String	特殊动作指令（针对硬件机器人）

其中FaqInfo对象的详细字段如下表

Name	Type	Note
gid	String	问答组id
labels	String Array	问答组标签，是个字符串数组
skillname	String	技能名称
candidates	JSONArray	候选问答组列表，是Candidate数组

其中Candidate对象的详细字段如下表

Name	Type	Note
gid	String	问答组语料唯一标识
labels	String Array	问答组标签，是个字符串数组
skillname	String	技能名称
score	Double	问题相似度评分
question	String	问题
answer	String	问题

使用说明：

stage 至少有一个 DialogStage；
stage 里面的队列是有先后顺序的；
DialogStage 中message 和 url 字段，两者至少有一个；
若message 与url 同时出现，则只获取 url，message 内容无效；
非RSVP 硬件设备可忽略DialogStage中的action字段。