响应数据是指 Webhook 服务接收到请求数据，并经过技能逻辑处理后，返回给平台的数据。平台会根据接收到的响应数据将文字合成语音播放或播放音频素材。

目前平台提供的 SDK 已经升级到 V3.0 版本，虽然依旧支持 V1.0 SDK 的使用，但推荐使用 V3.0 版本。

1、V1.0 SDK 响应数据对象结构

返回结果对象：

字段名 type 描述 是否必要
returnCode String “0”默认表示成功，其他不成功的字段自己可以确定 是
returnErrorSolution String 出错时解决办法的描述信息 否
returnMessage String 返回执行成功的描述信息 否
returnValue Object 意图理解后的执行结果 是

returnValue 字段内容：

字段名 type 描述 是否必要
reply String 回复给用户的 TTS 文本信息 是
resultType String 回复的状态标识，详细介绍见此表格下方 是
askedInfos List resultType: ASK_INF状态下需要携带追问的参数信息，包括参数名称和意图id，可同时携带多个参数。 否
properties Map 生成回复语句时携带的额外信息 否
actions List 播控类信息，支持播放音频素材和 TTS 文本 否
executeCode String “SUCCESS“代表执行成功；
“PARAMS_ERROR“代表收到的请求参数出错；
“EXECUTE_ERROR“代表自身代码有异常；
“REPLY_ERROR“代表回复结果生成出错。		 是

resultType 有三种枚举值：RESULT、ASK_INF 和 CONFIRM。

  1. RESULT：用于正常结束交互对话 ，音箱播放完回复文案后会闭麦。但此时依旧属于此技能的多轮对话中，用户唤醒天猫精灵后仍可以只使用语料进入意图。若用户使用了其它技能或 5 分钟内没有再次交互，就会退出此技能的多轮对话状态，需要使用调用词才能再次进入此技能。

  2. ASK_INF：用于追问用户参数信息或引导用户继续对话，期望用户回答本意图或下的参数取值或者本意图或其它意图中的语料，音箱询问后会自动开麦。期望用户回答的参数需要在 askedInfos 字段中指定。

  3. CONFIRM：用于向用户确认信息，并期待用户做出肯定或否定回答，音箱询问后会自动开麦。一般用于重要参数的再次确定。若用户做了肯定或否定回答，则这次交互的请求字段中会携 confirmStatus: CONFIRMED/DENIED。

AskedInfoMsg字段内容：

字段名 type 描述 是否必要
parameterName String 追问的参数名称。
此名称是在意图中定义的，不是实体标识		 是
intentId Long 参数所在的意图ID。
从请求参数中获得，请勿使用固定值		 是

PS:开发阶段的意图ID 和线上阶段的意图ID 不同。

Action 字段内容：

  1. 根据音频素材id播放音频素材 | 字段名 | type | 描述 | 是否必要 | | —- | —- | —- | —- | | name | String | Action名称，该名字必须设置为：
    “audioPlayGenieSource“ | 是 | | properties | Map | Action中的携带信息的集合，必要的key: “audioGenieId“，value为该技能下音频素材库内的音频ID | 是 |
  1. 播放 TTS 文本内容 | 字段名 | type | 描述 | 是否必要 | | —- | —- | —- | —- | | name | String | Action名称，该名字必须设置为”playTts“ | 是 | | properties | Map | key：”content“，value为需要播报的内容；
    key: “format“，value: “text“；
    key: “showText“，value为设备对话流展示文字，一般与”content”一致即可 | 是 |

2、返回结果json样例

技能请求响应协议都是基于JSON格式携带数据，响应头信息是content-type: text，会导致平台抛出JSON反序列化异常。

2.1 正常结束对话

返回用户访问意图想要的结果，返回后即结束对话。返回数据结构如下：

  1. {
  2.     "returnCode": "0",
  3.     "returnErrorSolution": "",
  4.     "returnMessage": "",
  5.     "returnValue": {
  6.         "reply": "上海今天天气多云，温度15到20度，东南风3级",
  7.         "resultType": "RESULT",
  8.         "executeCode": "SUCCESS",
  9.         "msgInfo": ""
  10.     }
  11. }

2.2 期望用户回答本意图或其他意图语料

开麦效果需要开发者勾选技能配置中”能力申请“->”授权配置“->”申请技能权限包“中的允许通过”Webhook触发音箱开麦行为“。

某些场景下希望天猫精灵播报完内容后开麦，用户的回答能够跳转到其它意图中。假如定义的默认意图只提供了引导功能，帮助用户如何使用此技能。那么默认意图的返回的数据是不需要对参数进行追问的。具体数据格式如下：

  1. {
  2.     "returnCode": "0",
  3.     "returnErrorSolution": "",
  4.     "returnMessage": "",
  5.     "returnValue": {
  6.         "reply": "欢迎使用天气小助手，您可以对我说:杭州今天天气 或 杭州今天空气质量。",
  7.         "resultType": "ASK_INF",
  8.         "actions": [],
  9.         "properties": {},
  10.         "executeCode": "SUCCESS",
  11.         "msgInfo": ""
  12.     }
  13. }

2.3 向用户追问当前意图的某个参数

当请求中缺少某个参数时，可以返回追问参数的响应。下次用户所说的话会优先进入本意图并解析其中这个参数的取值。返回数据结构如下：

  1. {
  2.     "returnCode": "0",
  3.     "returnErrorSolution": "",
  4.     "returnMessage": "",
  5.     "returnValue": {
  6.         "reply": "请问您要查询哪个城市的天气？",
  7.         "resultType": "ASK_INF",
  8.         "askedInfos": [
  9.             {
  10.                 "parameterName": "city",
  11.                 "intentId": "34567"
  12.             }
  13.         ],
  14.         "executeCode": "SUCCESS",
  15.         "msgInfo": ""
  16.     }
  17. }

PS: 可以同时追问多个参数。当同时追问多个参数时，这些参数的取值用户都可以回答，然后根据用户的回答识别参数。

2.4 重要参数向用户再次确认

某些场景下希望向用户再次确认重要参数是否正确，例如查询天气时城市信息的再次确认。具体数据格式如下：

  1. {
  2.     "returnCode": "0",
  3.     "returnErrorSolution": "",
  4.     "returnMessage": "",
  5.     "returnValue": {
  6.         "reply": "请问确定是要查询杭州的天气吗？",
  7.         "resultType": "CONFIRM",
  8.         "actions": [],
  9.         "properties": {},
  10.         "executeCode": "SUCCESS",
  11.         "msgInfo": ""
  12.     }
  13. }

用户做出确认回复时，请求数据中会有状态字段 confirmStatus: CONFIRMED。具体请求数据如下：

  1. {
  2.     "sessionId": "b112a091-1523-4d2d-8059-e09461dafd73", 
  3.     "utterance": "是的",   //确认回答：是的、好的、好、可以....;否认回答：不行、不、不是、不好....
  4.     "requestData": {
  5.         "userOpenId": "XXXXXXXX==", 
  6.         "deviceOpenId": "YYYYYYYYY==", 
  7.         "city": "上海" 
  8.     }, 
  9.     "botId": 10, 
  10.     "domainId": 12345, 
  11.     "skillId": 23456, 
  12.     "skillName": "天气小助手", 
  13.     "intentId": 34567, 
  14.     "intentName": "weather", 
  15.     "slotEntities": [
  16.             {
  17.             "intentParameterId": 45678, 
  18.             "intentParameterName": "city", 
  19.             "originalValue": "杭州", 
  20.             "standardValue": "杭州", 
  21.             "liveTime": 1, 
  22.             "createTimeStamp": 1564110905331, 
  23.             "slotName": "city:city",
  24.             "slotValue": "杭州"
  25.         },
  26.         {
  27.             "intentParameterId": 56789, 
  28.             "intentParameterName": "time", 
  29.             "originalValue": "今天", 
  30.             "standardValue": "今天", 
  31.             "liveTime": 1, 
  32.             "createTimeStamp": 1564110905331, 
  33.             "slotName": "time:sys.time", 
  34.             "slotValue": "今天"
  35.         }
  36.         ], 
  37.     "requestId": "20190726111511958-508551760", 
  38.     "device": { },
  39.       "confirmStatus": "CONFIRMED", //用户做确认回答时：CONFIRMED；用户做否认回答时：DENIED
  40.     "skillSession": {
  41.         "skillSessionId":"8d7501fe-a80a-46cf-a43f-ff8743a7ec66",
  42.         "newSession":false
  43.     }
  44. }