1、V3.0 SDK 响应数据对象结构
2、返回结果 json 样例

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

V3.0 SDK 是目前平台提供的最新版 SDK。V3.0 版本 SDK 不仅包括了 V1.0 版本的全部内容，还额外新增了 confirmParaInfo 和 gwCommands 等字段。这些字段的具体功能请详见下文。

V3.0 版本 SDK 的maven坐标如下：

<dependency>
    <groupId>com.alibaba.da.coin</groupId>
    <artifactId>semantic-execute-meta</artifactId>
    <version>1.1.18-REALEASE</version>
</dependency>

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

返回结果对象：

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

returnValue 字段内容：

字段名	type	描述	是否必要
reply	String	回复给用户的 TTS 文本信息	否
resultType	String	回复时的状态标识，这里不再通过resultType的取值决定是否开麦	是
askedInfos	List	resultType: ASK_INF状态下需要携带追问的参数信息，包括参数名称和意图id。可同时携带多个参数。	否
properties	Map	生成回复语句时携带的额外信息	否
actions	List	播控类信息，支持播放音频素材和 TTS 文本	否
gwCommands	List	最新版响应协议定义的 command结构	否
confirmParaInfo	ConfirmParaInfo	resultType: CONFIRM状态下可以携带的匹配用户肯定和否定回答的参数名称。	否
executeCode	String	“SUCCESS“代表执行成功； “PARAMS_ERROR“代表接收到的请求参数出错； “EXECUTE_ERROR“代表自身代码有异常； “REPLY_ERROR“代表回复结果生成出错	是

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

RESULT：用于正常结束交互对话，音箱播放完回复文案后会闭麦。但此时依旧属于此技能的多轮对话中，用户唤醒天猫精灵后仍可以只使用语料进入意图。若用户使用了其它技能或 5 分钟内没有再次交互，就会退出此技能的多轮对话状态，需要使用调用词才能再次进入此技能。
ASK_INF：用于追问用户参数信息或引导用户继续对话，期望用户回答本意图或下的参数取值或者本意图或其它意图中的语料，音箱询问后会自动开麦。期望用户回答的参数需要在 askedInfos 字段中指定。
CONFIRM：用于向用户确认信息，并期待用户做出肯定或否定回答，音箱询问后会自动开麦。一般用于重要参数的再次确定。若用户做了肯定或否定回答，则请求数据中会携 confirmStatus: CONFIRMED/DENIED 字段。可以通过 confirmParaInfo 字段指定用户表达需要匹配的参数。如果响应数据没有携带 confirmParaInfo数据，或两个参数都没有匹配到，则依靠平台来判断用户肯定或否定的想法。若平台没有判断出用户的想法，则可能会跳出技能。

AskedInfoMsg字段内容：

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

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

Action 字段内容：

根据音频素材id播放音频素材 | 字段名 | type | 描述 | 是否必要 | | —- | —- | —- | —- | | name | String | Action名称，该名字必须设置为：
“audioPlayGenieSource“ | 是 | | properties | Map | Action中的携带信息的集合，必要的key: “audioGenieId“，value为该技能下音频素材库内的音频ID | 是 |

播放 TTS 文本内容 | 字段名 | type | 描述 | 是否必要 | | —- | —- | —- | —- | | name | String | Action名称，该名字必须设置为”playTts“ | 是 | | properties | Map | key：”content“，value为需要播报的内容；
key: “format“，value: “text“；
key: “showText“，value为设备对话流展示文字，一般与”content”一致即可 | 是 |

confirmParaInfo 字段内容：

字段名	type	描述	是否必要
confirmParameterName	String	用户表达匹配到此参数，表示确定意思	是
denyParameterName	String	用户表达匹配到此参数，表示否定意思	是

gwCommands 字段是 V3.0 SDK 中一个特殊的字段，在响应数据中携带了gwCommands 后，原 reply、actions 字段会被忽略。

自定义技能中使用 TPL 模板，需要在响应数据中 gwCommands 字段里携带页面展示需要的数据。GwCommand 字段内容：

字段名	type	描述	是否必要
commandDomain	String	指令命名空间	是
commandName	String	指令名称	是
payload	Map	指令数据	是

2、返回结果 json 样例

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

2.1 正常结束对话

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

{
    "returnCode": "0",
    "returnErrorSolution": "",
    "returnMessage": "",
    "returnValue": {
        "reply": "上海今天天气多云，温度15到20度，东南风3级",
        "resultType": "RESULT",
        "executeCode": "SUCCESS",
        "msgInfo": ""
    }
}

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

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

{
    "returnCode": "0",
    "returnErrorSolution": "",
    "returnMessage": "",
    "returnValue": {
        "reply": "欢迎使用天气小助手，您可以对我说:杭州今天天气 或 杭州今天空气质量。",
        "resultType": "ASK_INF",
        "actions": [],
        "properties": {},
        "executeCode": "SUCCESS",
        "msgInfo": ""
    }
}

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

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

{
    "returnCode": "0",
    "returnErrorSolution": "",
    "returnMessage": "",
    "returnValue": {
        "reply": "请问您要查询哪个城市的天气？",
        "resultType": "ASK_INF",
        "askedInfos": [
            {
                "parameterName": "city",
                "intentId": "34567"
            }
        ],
        "executeCode": "SUCCESS",
        "msgInfo": ""
    }
}

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

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

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

{
    "returnCode": "0",
    "returnErrorSolution": "",
    "returnMessage": "",
    "returnValue": {
        "reply": "请问确定是要查询杭州的天气吗？",
        "resultType": "CONFIRM",
        "actions": [],
        "properties": {},
          "confirmParaInfo": {
                "confirmParameterName": "yes",
              "denyParameterName": "no"
        },
        "executeCode": "SUCCESS",
        "msgInfo": ""
    }
}

当用户的回复匹配到 yes 参数时，请求数据中会携带 confirmStatus: CONFIRMED，当用户的回复匹配到 NO 参数时，请求数据中会携带 confirmStatus: DENIED。如果两个参数都没有匹配到，则依靠平台判断用户的想法，如果判断不出用户想法，则可能会跳出技能。

{
    "sessionId": "b112a091-1523-4d2d-8059-e09461dafd73", 
    "utterance": "是的",
    "requestData": {
        "userOpenId": "XXXXXXXX==", 
        "deviceOpenId": "YYYYYYYYY==", 
        "city": "上海" 
    }, 
    "botId": 10, 
    "domainId": 12345, 
    "skillId": 23456, 
    "skillName": "天气小助手", 
    "intentId": 34567, 
    "intentName": "weather", 
    "slotEntities": [
        {
            "intentParameterId": 45678, 
            "intentParameterName": "yes", 
            "originalValue": "是的", 
            "standardValue": "是的", 
            "liveTime": 0, 
            "createTimeStamp": 1564110905331, 
            "slotName": "yes:yes",
            "slotValue": "是的"
        },    
      {
            "intentParameterId": 45678, 
            "intentParameterName": "city", 
            "originalValue": "杭州", 
            "standardValue": "杭州", 
            "liveTime": 1, 
            "createTimeStamp": 1564110905331, 
            "slotName": "city:city",
            "slotValue": "杭州"
        },
        {
            "intentParameterId": 56789, 
            "intentParameterName": "time", 
            "originalValue": "今天", 
            "standardValue": "今天", 
            "liveTime": 1, 
            "createTimeStamp": 1564110905331, 
            "slotName": "time:sys.time", 
            "slotValue": "今天"
        }
        ], 
    "requestId": "20190726111511958-508551760", 
    "device": { },
      "confirmStatus": "CONFIRMED",
    "skillSession": {
        "skillSessionId":"8d7501fe-a80a-46cf-a43f-ff8743a7ec66",
        "newSession":false
    }
}

2.5 使用 gwCommands 数据时

2.5.1 回复 TTS 文本

在使用了最新版网关 gwCommands 数据后，原 reply 字段会被忽略，需要使用 speak 的指令回复 TTS 文本数据。此 command 指令数据格式如下：

{
    "returnCode": "0",
    "returnErrorSolution": "",
    "returnMessage": "",
    "returnValue": {
        "resultType": "RESULT",
        "executeCode": "SUCCESS",
        "msgInfo": "",
        "gwCommands": [
            {
                "commandDomain": "AliGenie.Speaker",
                "commandName": "Speak",
                "payload": {
                      "type": "text",             //默认 text
                    "text": "这是语音播放的TTS需要用到的Command",
                      "expectSpeech": true,       //是否开麦,默认 false
                      "needLight": true,          //开麦时是否需要灯光提示用户
                      "needVoice": true,          //开麦时是否需要声音提示用户
                      "wakeupType": "continuity"  // 如果需要开麦，这里需要设置为 continuity
                }
            }
        ]
    }
}

2.5.2 回复 TPL 模板数据

响应数据中可以通过 gwCommands 字段携带 TPL 模板的屏显数据。根据使用的模板不同，屏显数据的数据格式也有所不同。下面示例是精选模板中 “图文模板2” 模板所要求的数据格式：

{
    "returnCode": "0",
    "returnErrorSolution": "",
    "returnMessage": "",
    "returnValue": {
        "resultType": "RESULT",
        "executeCode": "SUCCESS",
        "msgInfo": "",
        "gwCommands": [
            {
                "commandDomain": "AliGenie.Speaker",
                "commandName": "Speak",
                "payload": {
                      "type": "text",
                    "text": "这是语音播放的TTS需要用到的Command",
                      "expectSpeech": true,
                      "needLight": true,
                      "needVoice": true,
                      "wakeupType": "continuity"
                }
            },{
                  "commandDomain": "AliGenie.Screen",
                "commandName": "Render",
                "payload":{
                            "pageType":"TPL.RenderTemplate",
                            "data": { 
                                  "template": "Genie_ImageText1",  // 模板的唯一标识
                                  "pageTitle": "图文模板2",   // 真机渲染时显示在顶部导航栏的标题
                                  "dataSource": {  // 渲染模板所需的数据，即 data.json 中定义的字段
                                        "title": "图文类模板",
                                        "detail": "目前提供了 3 个简单图文类模板，分别为左图右文、右图左文、突出重点这3种布局模式",
                                          "imageUrl": "https://img.alicdn.com/tfs/TB1FHUFLqL7gK0jSZFBXXXZZpXa-720-405.jpg"
                                                }
                            }
                }
            }
        ]
    }
}

智能应用开放平台

响应数据 - V3.0 SDK