齐悟接口文档规范（v0.21）

接入方-齐悟接口对接文档规范说明

updated @ 2020.06.17

一、接入方语音网关请求齐悟对话接口协议

| 功能描述 | 接入方语音网关提交用户说的话进行语义解析 |
| - | - |
| 接口地址 | /api/chat |
| 调用方式 | POST |
| Body类型 | application/json |

1. 对话接口请求参数

对话接口请求 HEADER

| Header | Type | Value |
| - | - | - |
| Qiwu-MSG-Push | String (URI) | 齐悟网关推送下单或其他逻辑等待话术提交到的地址（见第三部分） |

对话接口请求 BODY

| Key | Type | Value | 必须 |
| - | - | - | - |
| appkey | String | 业务appkey | 是 |
| timestamp | Integer | 请求发送时的 unix 时间戳 | 是 |
| uid | String | 用于区分用户的用户唯一标识符，会传递给后台 | 是 |
| verify | String | 验证串，规则为 MD5(appsecret+uid+timestamp) | 是 |
| msg | String | 用户发送的消息 | 是 |
| geo[lng] | Float | 当前用户 GPS 经度信息 | 否 |
| geo[lat] | Float | 当前用户 GPS 纬度信息 | 否 |
| nickname | String | 用户昵称 | 否 |
| new_session | Boolean | 需清除本句消息之前所有对话记忆和对话状态时，传true | 否 |
| extra_order_info | JSONObject | 下单请求时，用户在接入方前端选择的下单参数 | 否 |

2. 对话接口请求示例

header

Authorization: Bearer XXXXXX
NLU-Callback: https://www.baidu.com

body

{
   "appkey":"pateo-train-test",
   "timestamp":1569402111,
   "uid":"123456789",
   "verify":"xxxxxx",
   "msg":"买张明天从深圳去北京的火车票",
   "geo[lng]":"113.959105",
   "geo[lat]":"22.543558",
   "nickname":"",
   "new_session":true,
   "extra_info": {
      // 外卖语音验证码
      "verify_code": "1234",
      // 机票，火车票联系人等信息（需要等齐悟接入方前后端一起确定）
   }
}

3. 对话接口响应参数

| Key | Type | Value | 必须 |
| - | - | - | - |
| retcode | Integer | 接口调用返回值（0代表成功，其他为失败） | 是 |
| ask | String | 用户问句 | 是 |
| msg | String | 给用户返回的话术 | 是 |
| data | JSON | 给前端返回的结构化数据，无数据时为 {} | 是 |
| data_key | String (UUID) | 结构化数据的 ID，可无视 | 否 |
| service | String (Enum) | 当前场景类型 | 否 |

data 中的必返字段说明

| Key | Type | Value | 说明 |
| - | - | - | - |
| task_finished | Boolean | true/false | 任务是否完成 |
| confidence | Float | 0-1 | 本次语句的置信度 |

当不在技能多轮，且NLU无法识别，将返回msg=好的，且confidence=0

当在某个技能的多轮里，NLU无法识别，直接返回msg=*还在帮您*（必须带这四个字），且confidence=0.5。

data.search_result_type 字段说明

类型为 String(Integer)，指代 data 中返回值的结构类型

| Value | 说明 |
| - | - |
| >0 | 正常返回，详情参见各个技能返回值说明文档 |
| 1 至 9 | 机票，酒店，火车等列表，详情参见各个技能返回值说明文档 |
| 10 至 10000 | 预留字段，由 NLU 接入方后端自行与前端约定并管理 |
| 10000 至 210000 | 其他齐悟自有业务技能返回值，详情参见各个技能返回值说明文档 |
| -1 | 纯语音返回，常见于追问缺失信息或结束对话 |
| -2 | 云端接口返回 Token 为空或失效，需要登陆 |
| -3 | 云端接口返回其他错误 |
| -4 | NLU 技能请求接入方回调接口超时 |
| -5 | NLU 技能请求接入方回调接口失败（retcode非0，500等） |

retcode 字段说明

当出现客户端请求错误，或者服务端错误时，retcode不为零

请求中错误

| retcode | 说明 |
| - | - |
| 1000 | 请求不合法或缺少必要的参数 |
| 1001 | 请求的 GPS 格式不合法 |
| 1002 | 请求体不是合法的 JSON 格式 |
| 1003 | 请求中 UID 为空 |
| 1004 | 请求中 UID 太长或包含非法字符（小于80，且只能包含 a-zA-Z0-9-_.@#） |
| 2000 | 请求 VERIFY 校验失败 |
| 2001 | 请求的聊天记录 UID 与原 UID 不一致（已废弃） |
| 3000 | 请求的业务非法或未上线 |

服务错误或系统崩溃

| retcode | 说明 |
| - | - |
| -1 | 服务端出现未知错误 |
| -2 | 会话初始化超时。可能由于服务繁忙或集群服务能力到达上限 |
| -3 | 单轮对话超时。可能由于集群服务能力到达上限或 CP 接口未及时响应 |
| -4 | 上一轮交互仍在处理中。由于齐悟语义多轮对单个用户仅支持回答后再处理下一句提问。可能由于同一用户说话太频繁，等待处理的问句队列太长导致 |
| -5 | 并发数超出集群处理能力太多。 |

4. 对话接口响应示例

{
   "retcode":0,
   "ask":"买张明天从深圳去北京的火车票",
   "msg":"为您推荐G201次列车",
   "data":{
      "search_result_type": "TRAIN_LIST_RESULT",
      "name":"xxx停车场",
      "lng":123.456,
      "lat":23.5678,
      "voice_words": "为您推荐高二零一次列车",
      "task_finished":false,
      "confidence":0.9
   },
   "data_key":"b1c00b1c-802a-4e4c-a6cf-7cb3515c2577",
   "service":"TRAIN"
}

<div style="page-break-after: always;"></div>

二、齐悟网关异步推送等待话术到接入方网关接口协议（可选）

| 功能描述 | 齐悟网关推送下单或其他逻辑的等待话术给接入方网关 |
| - | - |
| 接口地址 | 从二、1. 请求HEADER 中 MSG-Push 字段获取的地址 |
| 调用方式 | POST |
| Body类型 | application/json |

1. 消息推送接口请求参数

| Key | Type | Value | 必须 |
| - | - | - | - |
| retcode | Integer | 同上文响应部分 | 是 |
| uid | String | 同上文请求部分，对应问句的用户 uid | 是 |
| verify | String | 同上文请求部分，对应问句的 verify | 是 |
| ask | String | 同上文请求部分，对应用户问句问话内容 | 是 |
| msg | String | 同上文响应部分 | 是 |
| data | JSON | 同上文响应部分 | 是 |
| data_key | String (UUID) | 同上文响应部分 | 否 |
| service | String (Enum) | 同上文响应部分 | 否 |

安全性方面建议

建议回调接收端对推送消息的 verify 进行有效性检查，方便关联回复与问句，并防止第三方攻击。

2. 消息推送接口请求示例

{
   "retcode":0,
   "uid":"123456789",
   "verify":"xxxxxx",
   "ask":"买张明天从深圳去北京的火车票",
   "msg":"为您推荐G201次列车",
   "data":{
      "search_result_type": "TRAIN_LIST_RESULT",
      ......
   },
   "data_key":"b1c00b1c-802a-4e4c-a6cf-7cb3515c2577",
   "service":"TRAIN"
}

3. 消息推送接口响应参数

| Key | Type | Value | 必须 |
| - | - | - | - |
| retcode | Integer | 接口调用返回值（0代表成功，其他为失败） | 是 |
| msg | String | 接口调用提示信息（成功时为success） | 是 |
| timestamp | Integer | 接收到请求时的linux时间戳（System.currentTimeMillis()） | 是 |

4. 消息推送接口响应示例

{
   "retcode": 0,
   "msg":"success",
   "timestamp":1569402111
}

<div style="page-break-after: always;"></div>

三、接入方语音网关对齐悟数据透传接口协议（可选）

| 功能描述 | 接入方语音网关提交前端UI发生的数据变更或数据同步 |
| - | - |
| 接口地址 | /api/data/ |
| 调用方式 | POST |
| Body类型 | application/json |

1. 数据透传接口请求参数

数据透传接口请求 BODY

| Key | Type | Value | 必须 |
| - | - | - | - |
| appkey | String | 业务appkey | 是 |
| timestamp | Integer | 请求发送时的 unix 时间戳 | 是 |
| uid | String | 用于区分用户的用户唯一标识符，会传递给后台 | 是 |
| verify | String | 验证串，规则为 MD5(appsecret+uid+timestamp) | 是 |
| extra_order_info | JSONObject | 透传的数据 | 是 |

extra_order_info 中必须包含的字段

| Key | Type | Value |
| - | - | - |
| skillName | String (Enum) | 业务技能名称 |
| scene | String (Enum) | 当前业务场景 |
| data | JSONObject | 具体数据 |

2. 数据透传接口请求示例

header

Authorization: Bearer XXXXXX

body

{
   "appkey":"xiaowu-train-test",
   "timestamp":1569402111,
   "uid":"123456789",
   "verify":"xxxxxx",
   "extra_order_info": {
      "skillName": "TAKEAWAY",
      "scene": "CHOOSE_COURSE",
      "data": {
         "hello": "world"
      }
   }
}

3. 数据透传接口响应参数

| Key | Type | Value | 必须 |
| - | - | - | - |
| retcode | Integer | 接口调用返回值（0代表成功，其他为失败） | 是 |
| msg | String | 接口调用提示信息（成功时为success） | 是 |
| data | JSONObject | 给前端返回的结构化数据，无数据时为 {} | 是 |
| data_key | String (UUID) | 结构化数据的 ID，可无视 | 否 |
| service | String (Enum) | 当前场景类型 | 否 |

4. 数据透传接口响应示例

成功时：

{
   "retcode":0,
   "msg": "success",
   "data":{
      "search_result_type": "TRAIN_LIST_RESULT",
      "a": "b" // 详细数据结构参见各个业务的返回值说明文档
   },
   "data_key":"b1c00b1c-802a-4e4c-a6cf-7cb3515c2577",
   "service":"TRAIN"
}

失败时：

{
   "retcode":500,
   "msg": "失败原因",
   "data": {}, 
   // 依照和网关的约定，流程外异常时 data 返回空 Object
   // 流程内错误会有独立的search_result_type，参见各个业务的返回值说明文档
   "data_key":"",
   "service":"TRAIN"
}

5. 数据透传接口-外卖菜品选择 extra_order_info 请求示例

{
    "skillName": "TAKEAWAY",
    "scene": "CHOOSE_COURSE",
    "data": {
        "courses": [
            {
                "skuId": "2179542419",
                "quantity": 10,
                "selectedAttrIds": ["1833375638", "1833375644"]
            }
        ]
    }
}

6. 数据透传接口-美食请求门店基本信息人数，房型 extra_order_info 请求示例

{
    "skillName":"FOOD",
    "scene":"FOOD_BASIC_INFO",
    "data":{
        "sid":"......"
    }
}
Last modification：March 15, 2023
© Reprint prohibited
如果觉得我的文章对你有用，请随意赞赏