文档中心

这套协议是客户端和ABC Robot云端的通信协议，客户端借助此协议，实现端云交互，完成请求发送和返回值处理。我们将端云交互抽象成事件、指令和端状态的形式，客户端的请求由事件和端状态组合而成，云端处理客户端传输的事件和端状态，将处理结果以指令集的形式下发给机器人，客户端执行收到的指令集，完成交互逻辑。

ClientContext（端状态）

ClientContext（端状态）反映的是客户端发起请求时的状态，客户端把端状态告知云端，云端可以根据设备端当前状态做出不同的逻辑决策，从而下发不同的指令集。例如，当前设备端正在语音播报，客户端收音并发起请求时将语音播报状态带上，这样云端就可以智能选择是否要求客户端打断当前语音播报。

示例

{ "clientContextV2":{ "TTS_PLAYING": "true", "APP_VERSION": "2", "WAKEUP_TYPE": 

"easyTalk|wakeupWord|touchBody|touchScreen", "MANUAL_REPLY": "true|false", "DIRECTION_INVALID": 

"0", "NAV_RUNNING":"true|false", "GUIDE_RUNNING":"true|false", "CHAT_IN_GUIDING":"true|false",

 "KNOW_ME_RUNNING":"true|false", }, "event": { ... } }

参数说明

Event（事件）

我们把客户端和云端交互的请求数据组装成Event（事件）发给云端，常见的事件例如：人脸识别事件等。

TextInput事件

TextInput事件是以文本的方式请求ABC Robot对话接口，这个过程不包含ASR。

示例

{ "header": { "namespace": "baidu.abcrobot.event.text_input", "name":

 "TextInput" }, "payload": { "query": "今天天气怎么样" } }

payload参数说明

FaceRecognition事件

人脸识别事件，整个人脸识别请求由两部分组成：人脸识别事件和人脸图片。

{ "header": { "namespace": "baidu.abcrobot.event.face_recognition", "name": "FaceRecognition" }, 

"payload": { "group":"face group id" } }

二进制图片附件

--this-is-a-boundary
Content-Disposition: form-data; name="image"; filename="image"
Content-Type: application/octet-stream
{{binary image attachment}}
--this-is-a-boundary

FaceComparison事件

人脸1:1比对事件，整个人脸1:1比对请求由两部分组成：人脸1:1比对事件和两张人脸图片。

{ "header": { "namespace": "baidu.abcrobot.event.face_recognition", "name": "FaceComparison" },

 "payload": { "imageTypes":[ 1, 2 ] } }

payload参数说明

imageTypes参数说明

二进制图片附件

--this-is-a-boundary
Content-Disposition: form-data; name="image"; filename="image"
Content-Type: application/octet-stream
{{binary image 1 attachment}}
--this-is-a-boundary

--this-is-a-boundary
Content-Disposition: form-data; name="image"; filename="image"
Content-Type: application/octet-stream
{{binary image 2 attachment}}
--this-is-a-boundary

FaceImageInput事件

人脸图片上传事件，人脸图片上传请求由两部分组成：人脸图片上传事件和人脸图片。

{ "header": { "namespace": "baidu.abcrobot.event.image_input", "name": "FaceImageInput" }, "payload": {} }

二进制图片附件

--this-is-a-boundary
Content-Disposition: form-data; name="image"; filename="image"
Content-Type: application/octet-stream
{{binary image attachment}}
--this-is-a-boundary

RobotConfig事件

客户端拉取配置事件，云端收到这个事件后，会将云端配置下发给客户端。

{ "header": { "namespace": "baidu.abcrobot.event.system", "name": "RobotConfig" }, "payload": {} }

Directive（指令）

云端把下发给客户端的操作封装成指令的格式，客户端收到指令后，依据指令的namespace、name和payload做出相应的响应。比如，Text指令，客户端收到这个指令后显示指令里的文本内容。

header参数说明

常规指令

Speak指令

语音播报指令，客户端将指令的文本内容转换成语音并播报。

{ "header": { "namespace": "baidu.abcrobot.directive.voice_output", "name": "Speak",

 "interactionId": "", "messageId": "" }, "payload": { "content": "今天晴，天气不错！" } }

payload参数说明

Text指令

文本显示指令，一般用于显示语音播报对应的文本，长文本的显示请使用卡片显示中的TextCard指令。

{ "header": { "namespace": "baidu.abcrobot.directive.text_output", "name": "Text", "interactionId":

 "", "messageId": "" }, "payload": { "content": "为您找到长城的介绍" } }

payload参数说明

Hints指令

提示信息指令，用于引导用户进行下一轮交互。如用户问“天气怎么样”，云端在返回天气答案的同时，会下发Hints指令，如“明天呢”、“天津呢”，引导用户进行多轮对话。

{ "header": { "namespace": "baidu.abcrobot.directive.hint", "name": "Hints", 

"interactionId": "", "messageId": "" }, "payload": { "hints": [ "我要办理值机" ] } }

payload参数说明

Text指令和Hints指令排版示例如下，其中“为您找到长城的介绍”为Text指令，“我要办理值机”为Hints指令。

卡片显示

下面介绍的指令都是涉及客户端卡片显示的，客户端收到这些指令后，根据不同的类型展示不同的卡片。卡片显示指令统一使用RenderCard指令header，通过不同的payload来区分不同的卡片。

{ "header": { "namespace": "baidu.abcrobot.directive.screen", "name": "RenderCard",

 "interactionId": "", "messageId": "" }, "payload": { {{不同的payload}} } }

TextCard类型卡片

文本卡片。参考排版方式：标题、内容上下排列，左对齐。

{ "type": "TextCard", "title": "长城", "content": "${{长城|link0}}(The Great Wall)，

又称万里长城...", "url": "https://baike.baidu.com/item/%E9%95%BF%E5%9F%8E/14251", "links": 

{ "link0": { "type": "renderHtml", "url": "http://robot.baidu.com/" } } }

payload参数说明

ImageCard类型卡片

图片卡片，包含图片和对应的文本信息。参考排版方式：图片在左侧，标题、内容上下排列，三者左对齐。

{ "type": "ImageCard", "title": "长城", "image": "https://timgsa.baidu.com/timg?

20100603_96286_1.jpg", "content": "Great Wall）又称${{万里长城|link0}}，是中国古代的军事防御工程，

是...", "url": "https://baike.baidu.com/item/长城/14251", "links": { "link0": { "type": 

"renderHtml", "url": "http://robot.baidu.com/" } } }

payload参数说明

ListCard类型卡片

列表卡片格式一，参考排版方式：列表包行多项，上下依次排列。每一项的排列方式和ImageCard的相同。

{ "type":"ListCard", "links":{ "link0":{ "speak":"播报话术", "type":"sendTextEvent",

 "query":"防御工程" }, "link1":{ "speak":"播报话术", "type":"sendTextEvent", "query":"防御工程" } 

} "title": "", "list":[ { "title": "柳宗元", "content":"${{防御工程|link0}}", "image": 

"https://ss2.baidu.com/6ONYsjip0QIZ8tyhnq/it/u=2541339440,4048181160&fm=58", "url": "" }, 

{ "title": "曾巩", "content":"${{防御工程|link1}}", "image": "https://ss2.baidu.com/6ONYsj

ip0QIZ8tyhnq/it/u=2541339440,4048181160&fm=58", "url": "" }, ... ] }

列表卡片格式二，参考排版方式：卡片主标题和列表项上下依次排列，左对齐。

{ "type":"ListCard", "links":{ "link0":{ "speak":"播报话术", "type":"sendTextEvent",

 "query":"里程查询" }, "link1":{ "speak":"播报话术", "type":"sendTextEvent", "query":"里程补登" }, 

"link1":{ "speak":"播报话术", "type":"sendTextEvent", "query":"里程兑换" } } "title":

 "请选择您所需要办理的业务类型", "list":[ { "content":"${{1.里程查询|link0}}", }, 

{ "content":"${{2.里程补登|link1}}", }, { "content":"${{3.里程兑换|link2}}", } ] }

payload参数说明

列表项

SimpleImageListCard类型卡片

简单图片列表卡片，为多个图片的集合，在仅展示图片的场景下，建议用此卡片。参考排版方式：这种类型只包含图片列表，图片排列依据屏幕宽度换行排列。

{ "type": "SimpleImageListCard", "list": [ { "image": "image_src", "url": "http://robot.baidu.com/" },

 { "image": "image_src", "url": "http://robot.baidu.com/" } ] }

payload参数说明

列表项

InputCard类型卡片

输入卡片，参考排版格式：标题、内容、输入说明列表项上下依次排列，左对齐。

{ "type": "InputCard", "content" : "请您输入需查询的完整的城市对信息，例如广州飞北京', 

"inputList" : [ "出发城市：", "到达城市：" ] "queryFormat": "${{input0}}飞${{input1}}" }

payload参数说明

HintsCard类型卡片

信息提示卡片，list中为提示内容列表信息。

{ "type": "HintsCard", "content" : "小度能带你到这些地方', "list": [ { "content": "带我去第七展厅" },

 { "content": "带我去7号楼" }, { "content": "带我去卫生间" },

 { "content": "带我去电梯口" }, { "content": "带我去净化器" } ] }

payload参数说明

复合类型卡片

复合类型卡片支持更复杂的卡片点击、卡片间跳转等操作，目前我们为用户航班信息查询场景，提供里程查询、消费查询等卡片间的跳转。如果开发者有接入需求，请提交工单联系我们。

links字段说明

文本点击操作，文本整段或部分显示可点击。自定义协议：${{长城|link0}}，link0为links json里的key。

音量控制

AdjustVolume指令

调节音量指令，客户端根据指令内的字段调节本地系统音量。

{ "header": { "namespace": "baidu.abcrobot.directive.speaker_controller", "name": "AdjustVolume", 

"interactionId": "", "messageId": "" }, "payload": { "volume_control": "down", "volume_value": "5.0" } }

payload参数说明

SetMute指令

静音指令，客户端根据指令设置打开或取消静音。

{ "header": { "namespace": "baidu.abcrobot.directive.speaker_controller", "name": "SetMute",

 "interactionId": "", "messageId": "" }, "payload": { "switch":"on" } }

payload参数说明

运动控制

下面介绍的都是涉及客户端运动控制的指令，客户端收到这些指令后，可以控制客户端做出相应的动作。

Walk指令

行走指令，控制设备行走一段距离。

{ "header": { "namespace": "baidu.abcrobot.directive.action", "name": "Walk", 

"interactionId": "", "messageId": "" }, "payload": { "direction": "forward", "distance": "5.0", "distance_unit": "米" } }

payload参数说明

Turn指令

转动指令，控制设备转动一定角度。

{ "header": { "namespace": "baidu.abcrobot.directive.action", "name": "Turn", 

"interactionId": "", "messageId": "" }, "payload": { "direction": "forward", "angle": "90.0", "angle_unit": "度" } }

payload参数说明

RaiseHands指令

抬手指令，设备可以抬起手臂。

{ "header": { "namespace": "baidu.abcrobot.directive.action", "name": "RaiseHands", 

"interactionId": "", "messageId": "" }, "payload": { "hands": "hand" } }

payload参数说明

ShakeHands指令

握手指令，设备可以做出握手动作。例如当用户说“握个手”时，云端会下发该指令。

{ "header": { "namespace": "baidu.abcrobot.directive.action", "name": "ShakeHands", 

"interactionId": "", "messageId": "" }, "payload": {} }

Hug指令

拥抱指令，设备可以做出拥抱动作。

{ "header": { "namespace": "baidu.abcrobot.directive.action", "name": "Hug" }, "payload": {} }

TwistHead指令

摇头指令，设备可以做出摇头动作。

{ "header": { "namespace": "baidu.abcrobot.directive.action", "name": "TwistHead" }, "payload": {} }

TurnHeadLeft指令

向左看指令，客户端可以做出向左看动作。

{ "header": { "namespace": "baidu.abcrobot.directive.action", "name": "TurnHeadLeft", 

"interactionId": "", "messageId": "" }, "payload": {} }

TurnHeadRight指令

向右看指令，客户端可以做出向右看动作。

{ "header": { "namespace": "baidu.abcrobot.directive.action", "name": "TurnHeadRight",

 "interactionId": "", "messageId": "" }, "payload": {} }

Stop指令

停止运动指令，设备收到该指令后停止当前动作。

{ "header": { "namespace": "baidu.abcrobot.directive.action", "name": "Stop" }, "payload": {} }

Wave指令

打招呼指令。

{ "header": { "namespace": "baidu.abcrobot.directive.action", "name": "Wave", "interactionId":

 "", "messageId": "" }, "payload": {} }

DoAnAction指令

动一下指令。

{ "header": { "namespace": "baidu.abcrobot.directive.action", "name": "DoAnAction",

 "interactionId": "", "messageId": "" }, "payload": {} }

Charge指令

充电指令，控制设备开始充电或停止充电。例如，当用户说“回去充电”时，可控制机器人进行自主充电。

{ "header": { "namespace": "baidu.abcrobot.directive.action", "name": "Charge",

 "interactionId": "", "messageId": "" }, "payload": { "switch": "on" } }

payload参数说明

巡航指令

巡航指令，控制设备开始巡航或停止巡航。例如，当用户说“开始巡航”时，可控制机器人按编排的路线进行巡航。

{ "header": { "namespace": "baidu.abcrobot.directive.action", "name": "Cruise", "interactionId":

 "", "messageId": "" }, "payload": { "switch": "on" } }

payload参数说明

导航指令

当用户说“带我去XXX”时，可控制机器人导航至XXX地点。

{ "header": { "namespace": "baidu.airport.directive.navigation", "name": "Navigate",

 "interactionId": "", "messageId": "" }, "payload": { "target": "卫生间" } }

payload参数说明

导览指令

开始导览指令

当用户说“开始导览”时，可控制机器人按编排的路线进行导览讲解。

{ "header": { "namespace": "baidu.standard.directive.guide", "name": "StartGuideFlow", 

"interactionId": "", "messageId": "" }, "payload": { "routeName":"导览路线1", "chatInGuiding" : true } }

payload参数说明

结束导览指令

当用户说“结束导览”时，可控制机器人结束导览讲解。

{ "header": { "namespace": "baidu.standard.directive.guide", "name": "EndGuideFlow", 

"interactionId": "", "messageId": "" }, "payload": { } }

继续导览指令

当机器人在导览过程中被打断后处于暂停导览状态的情况下，用户说“继续导览”时，可控制机器人继续暂停前的导览讲解。

{ "header": { "namespace": "baidu.standard.directive.guide", "name": "ProceedCurrentStep",

 "interactionId": "", "messageId": "" }, "payload": { } }

下一个导览点

当机器人在某一个导览点进行讲解时，可以通过“下一个讲解点”话术，控制机器人结束当前点的讲解，直接到下一个导览点进行讲解。

{ "header": { "namespace": "baidu.standard.directive.guide", "name": "ProceedNextStep", 

"interactionId": "", "messageId": "" }, "payload": { } }

人脸指令

FaceRecognitionResult指令

人脸识别结果指令，云端下发人脸识别结果给客户端。

{ "header": { "namespace": "baidu.abcrobot.directive.face_recognition", "name": 

"FaceRecognitionResult", "interactionId": "", "messageId": "" }, "payload": { "name": 

"name", "sex": "MALE", "age": 30，, "uid": "N1088", "faceliveness": true, "type": "VIP" } }

payload参数说明

FaceComparisonResult指令

人脸比对结果指令，云端下发人脸比对结果给客户端。

{ "header": { "namespace": "baidu.abcrobot.directive.face_recognition", "name": "FaceComparisonResult",

 "interactionId": "", "messageId": "" }, "payload": { "score": 89.9 } }

payload参数说明

GetFaceImage指令

上传人脸图片指令，客户端收到这个指令后，上传人脸图片到云端，与FaceImageInput事件配合使用。

{ "header": { "namespace": "baidu.abcrobot.directive.image_input", "name": "GetFaceImage", 

"interactionId": "", "messageId": "" }, "payload": {} }

系统指令

SyncRobotConfig指令

云端配置下发指令，由RobotConfig事件触发。

{ "header": { "namespace": "baidu.abcrobot.directive.system", "name": "SyncRobotConfig", 

"interactionId": "", "messageId": "" }, "payload": { "welcomeSpeeches": [ "您好,很高兴为您服务",

 "${name}您好,很高兴为您服务" ], "faceWakeUpType": 1, "sensitiveWords":[ "abc", "edf" ] } }

payload参数说明

InquireEnergy指令

电量查询指令，客户端收到这个指令后，显示客户端电量。

{ "header": { "namespace": "baidu.abcrobot.directive.instruction", "name": "InquireEnergy", 

"interactionId": "", "messageId": "" }, "payload": {} }

ShowFeatures指令

功能页展示指令，客户端收到这个指令后，展示功能介绍页。

{ "header": { "namespace": "baidu.abcrobot.directive.instruction", "name": "ShowFeatures",

 "interactionId": "", "messageId": "" }, "payload": {} }

媒体资源控制指令

媒体播放指令

用于播放媒体资源，如唱一首没有共产党就没有新中国。

{ "header": { "namespace": "baidu.abcrobot.directive.media_control", "name": "PlayMedia",

 "interactionId": "", "messageId": "" }, "payload": { "name":"没有共产党就没有新中国", "type":"SING_SONG" } }

payload参数说明

媒体播放控制指令

用于媒体播放控制，如暂停，继续，下一个，换一个等

{ "header": { "namespace": "baidu.abcrobot.directive.media_control", "name": "PlayControl", 

"interactionId": "", "messageId": "" }, "payload": { "action":"play_next" } }

payload参数说明

页面切换控制指令

用于页面切换控制，比如返回主页，返回上一页，下一页等

{ "header": { "namespace": "baidu.abcrobot.directive.media_control", "name": "PageControl", 

"interactionId": "", "messageId": "" }, "payload": { "pageName":"MAIN_PAGE" } }

payload参数说明

按索引选择指令

用于在媒体列表中，按索引选择要操作的媒体项。如第一个/页，倒数第一个/页等，

{ "header": { "namespace": "baidu.abcrobot.directive.media_control", "name": "SelectByIndex", 

"interactionId": "", "messageId": "" }, "payload": { "order": "POS", "index": 1, "unit": "page" } }

payload参数说明

其它指令

NLUResult指令

语义理解结果指令，开发者使用自定义技能时，可以在技能回复中配置成直接获取NLU结果，并通过这个指令下发。

{ "header": { "namespace": "baidu.abcrobot.directive.nlu", "name": "NLUResult", 

"interactionId": "", "messageId": "" }, "payload": { "skill": { "name": "CUSTOMER" },

 "intent": { "name": "RECHARGE" }, "slots": [ { "name": "cellphone", "originalWord": 

"13810102020", "normalizedWord": "13810102020" } ] } }

payload参数说明

CustomData指令

自定义参数下发指令，通常为控制台配置的KV集合，例如问答库中的自定义参数。

{ "header": { "namespace": "baidu.abcrobot.directive.custom", "name": "CustomData",

 "interactionId": "", "messageId": "" }, "payload": { "data": { "key": "value", ... } } }

payload参数说明

技能分发描述指令

用于表明用户问题命中技能和答案来源技能。

{ "header": { "namespace": "baidu.abcrobot.directive.skill_dispatch", "name":

 "SkillInfo", "interactionId": "", "messageId": "" }, "payload": { "type": "Navigation", } }

payload参数说明

End指令

再见指令，客户端收到这个指令后，客户端重置和云端交互的session。

{ "header": { "namespace": "baidu.abcrobot.directive.session", "name": "End",

 "interactionId": "", "messageId": "" }, "payload": {} }

Error指令

错误指令，客户端请求云端返回此指令，表示请求失败，客户端根据相应的错误码做错误处理。

{ "header": { "namespace": "baidu.abcrobot.directive.error", "name": "Error",

 "interactionId": "", "messageId": "" }, "payload": { "code": 50300, "message": "……" } }

payload参数说明

错误码