一、产品介绍

基于websocket协议的API请求DUI全链路产品，获得对话交互结果

1.1 适用场景

1）轻量级嵌入式设备，基于协议开发

2）采用云对云的方式，使用DUI全链路产品，基于协议开发

3）其他特殊场景，需要基于协议开发

4）支持语音、文本、意图三种输入

1.2 使用限制

需要先前往控制台创建全链路产品，并且将产品成功发布，才能正常使用基于websocket协议的API。

二、接入说明

2.1 接入前的准备

1）登录DUI控制台

2）创建全链路产品

3）进行产品配置

4）添加技能

5）进行产品技能测试

6）配置授权

7）发布产品

2.2 建立websocket连接

本API正式环境的地址是wss://dds.dui.ai/dds/v2/[分支号]，其中[分支号]是DUI控制台分支管理页面的内容。如下图所示： 在产品详情页的发布管理页面，选择分支管理，获取分支号。

2.2.1 连接上需要携带的公共参数

参数名	含义	是否必须	取值示例
serviceType	表示使用何种协议	是	websocket
productId	产品标识	是	278578090
productVersion	指定使用的产品版本	否	1

 

连接上需要携带的参数，包含了授权参数，授权有两种场景，一种是设备对接云，一种是云对云。具体参数信息如下：

2.2.2 设备对接云端API的授权参数

参数名	含义	是否必须	取值示例
deviceName	设备激活时获取到的device profile中deviceName字段	是	0ddddeeeeeeeeeeee88888888260c8ab
nonce	随机字符串, 32字符以内	是	bf7c8674
sig	签名，对query parameter中的参数按照预先约定的顺序排序 (devicename + nonce + productId + timestamp)，然后基于 deviceSecret对参数做签 名:hmacsha1(deviceSecretSecret, devicename + nonce + productId + timestamp)	是	0ddddddddd94dd87788888888260c8ab
timestamp	unix时间戳（毫秒）	是	1546059559999

 

特别说明：获取DeviceName，需要走设备激活流程，请求设备激活接口，接口详情如下：

 

设备激活接口简介

设备使用前必须的鉴授权环节，设备通过此接口，与DUI产品绑定并获得鉴权秘钥（device profile），后续基于鉴权秘钥与云端进行语音对话请求。设备方需要妥善保管鉴权秘钥，如丢失可调用此接口进行重新获取，重新获取的秘钥与原来的秘钥不相同，且原秘钥会失效。

 

接口请求地址

https://auth.dui.ai/auth/device/register

 

接口请求类型

POST

 

接口请求参数

Headers

参数名	参数值	是否必须
Content-Type	application/json	是

 

Query

参数名	是否必须	示例	备注
productKey	是	0d397453dd94dd87788888888260c8cb	来自dui控制台，产品授权管理页面
format	是	plain	传入plain即可
productId	是	100000001	产品id，来自dui控制台，产品授权管理页面
timestamp	是	1546059559999	unix时间戳（毫秒）
nonce	是	bf7c8674	随机字符串，32字符以内
sig	是	0ddddddddd94dd87788888888260c8ab	签名，对query parameter中的参数按照预先约定的顺序排序 (productKey + format+ nonce + product id + timestamp)，然后基于product secret对参数做签名：hmacsha1(productSecret，productKey + format+ nonce + product id + timestamp) ，本文末尾有签名示例代码。

 

Request Body

request body中通过json格式上报设备信息，上报到思必驰的设备信息有三个作用：
1）确认设备的唯一性（针对各种设备的必填字段）
2）方便后续针对不同类型的设备进行优化（针对各种设备的选填字段）
3）查询统计分析，方便客户按照不同维度统计自己设备的激活情况

Android

名称	类型	是否必须	字段说明	示例
platform	string	是	平台类型，android设备填android即可	android
deviceId	string	是	设备ID	5235894f-3028-33f4-a948-c86549cc4808
packageName	string	是	包名	com.aispeech.dui.demo
applicationLabel	string	否	应用名称	DUI Demo
applicationVersion	string	否	版本	0.1.0-20171031163815
buildVariant	string	是	构建类型: debug 或 release	release
buildSdkInt	string	否	framework level	19
displayMatrix	string	是	屏幕分辨率	720*1280
buildModel	string	是	型号	Coolpad 8675
buildManufacture	string	是	制造商	XiaoMi
buildDevice	string	是	设备名称	8675
imei	string	否	IMEI号	356704081123748
mac	string	否	MAC地址	44:45:53:54:00:00
androidId	string	否	Android ID	9774d56d682e549c

 

iOS

名称	类型	是否必须	字段说明	备注
platform	string	是	平台类型，ios设备填ios即可	ios
deviceId	string	是	设备ID	0060D69C-AB7A-44E9-8754-7A12EC2AEDAD
packageName	string	是	包名	com.aispeech.dui.demo
applicationLabel	string	否	应用名称	DUI Demo
applicationVersion	string	否	版本	0.1.0-20171031163815
buildSdkInt	string	否	framework level	level 19
displayMatrix	string	否	屏幕分辨率	750x1334
buildModel	string	是	型号	iPhone 6
buildManufacture	string	是	制造商	Apple
buildDevice	string	是	设备名称	iPhone

 

嵌入式

名称	类型	是否必须	字段说明	备注
platform	string	是	平台类型，嵌入式设备填嵌入式操作系统或芯片型号即可	linux
deviceName	string	是	设备名称，要求是接入方所有设备中唯一的一个字段，比如mac地址、uid号等	0060D69C-AB7A-44E9-8754-7A12EC2AEDAD
instructionSet	string	否	指令集	armv6
chipModel	string	否	芯片型号	RK3308

 

正确返回示例

{
    "deviceInfo": {
        ......
    },
    "deviceName": "0000-0001",
    "deviceSecret": "1518b5f911864150a092ba6952be534d",
    "productId": "666666"
}

 

错误返回示例

{
    "errId": 401,
    "error": "signature mismatch."
}

 

通用http status解释

• 200 ok
• 400 请求错误
• 401 因为权限问题激活失败
• 500 内部系统错误

 

特别说明

嵌入式设备的请求body里，deivceName字段，需要有唯一性保证，否则如不同设备使用相同的deviceName，第二个激活的设备会使第一个激活设备的设备秘钥失效，可能会对用户体验造成不确定的影响。

 

附录 签名代码示例

JAVA

String content = productKey + format + nonce + productId + timestamp;
String signature = SecureUtil.hmacSha1(productSecret).digestHex(content);

2.2.3 云端对接云端的授权参数

参数名	含义	是否必须	取值示例
apikey	DUI控制台生成的绑定过ip的访问标识	是	0ddddeeeeeeeeeeee88888888260c8ab

2.2.4 全双工通信的参数

参数名	含义	是否必须	取值示例
communicationType	通信交互类型。 目前只有全双工需要此参数，取值只能为 fullDuplex。 如果采用半双工，则不要带上此参数。	否	fullDuplex

注意: 上述参数用于判别客户端想采用半双工还是全双工的通信交互方式。

1. 如果客户端采用半双工，则不要带上该参数。

2. 如果客户端采用全双工，则需要带上该参数，且取值必须为 fullDuplex。

2.2.5 一条完整的云端对接云端的连接示例

wss://dds.dui.ai/dds/v2/test?serviceType=websocket&productId=278578090&apikey=0ddddeeeeeeeeeeee88888888260c8ab

注意：以上productId和apikey需要更换为开发者自己创建的产品ID和apikey，否则请求不通过。

2.2.6 在以下情况下建立连接会失败

1）产品没有发布

2）产品分支号没有对应已经发布过的产品版本

3）授权参数不正确，服务端鉴权不通过

2.2.7 正确建立websocket连接的报文

2.3 发送语音请求

websocket连接建立成功之后，调用端首先向服务端发送一个opcode为text的报文；这个报文的payload是一个json字符串。

2.3.1 语音请求text参数

参数名	含义	是否必须	取值示例
topic	用于区分语音请求，文本请求	是	recorder.stream.start
recordId	uuid，标识一次请求，32字符	否	DUIddeeeeeeeeeeee88888888260c8ab
sessionId	uuid，服务端通过相同的sessionId关联多轮请求的上下文； 首轮对话请求不需要携带； 非首轮对话请求取值是上一轮服务端返回结果中的sessionId	否	DUIddeeeeeeeeeeee88888888260c8ab
audio.audioType	音频类型，推荐使用压缩过的音频格式，以节省带宽，推荐ogg，不支持ogg vorbis，只支持ogg speex	是	ogg, wav,mp3,flv,amr,opus
audio.sampleRate	音频数据采样率，推荐使用16000; （ogg支持8000、16000；wav支持8000、16000；mp3支持16000、22050、44100；amr支持8000）	是	16000
audio.channel	声道	是	1
audio.sampleBytes	音频数据每采样点大小	是	2
wakeupWord	触发当次请求的唤醒词，用于oneshot使用场景	否	你好小驰
asrParams.enableVAD	是否使用云端vad	否	true,false
asrParams.realBack	是否使用实时识别结果	否	true,false
asrParams.enablePunctuation	识别结果是否开启标点符号	否	true,false
asrParams.enableTone	是否使用拼音带声调	否	true,false
asrParams.enableConfidence	识别结果是否返回置信度	否	true,false
asrParams.enableNumberConvert	识别结果中文数字转成阿拉伯数字	否	true,false
asrParams.phraseHints	使用热词识别（pattern要在第二路，或者第三路lm中存在）	否	[{"type": "vocab", "name": "行政区", "data":["黄浦区"]}]
asrParams.enableEmotion	开启情感识别，返回性别、年龄、情绪	否	true,false
asrParams.enableAudioDetection	是否开启云端音频检测，如果未检测到有效音频，则会终止后续对话流程	否	true,false
asrParams.res	切换识别生效的语言模型	否	aienglish（此处填写三路模型对应的识别引擎）
asrParams.vadPauseTime	支持调用端指定vad在结束语音时采用的静音时长，取值范围是200~2000，单位是ms，默认500ms	否	1000
asrParams.enableCloudVAD	是否开启云端vad检测，开启云端会返回asr.vad.start的topic表示vad start	否	true,false
asrParams.enableProcessedWavTime	是否开启返回ProcessedWavTime字段	否	true,false
context.skill.task	在非首轮中可能用到，用于指定调用端使用了上一轮nbest结果中的哪一个task	否	查天气
aiType	指定云端服务的类型，asr表示识别结果，不设置该字段表示对话结果	否	asr
asrPlus.enableAsrPlus	是否开启声纹	否	true,false
asrPlus.users	注册的声纹用户列表，开启声纹后此字段必须填	否	["user1", "user2"]
asrPlus.organization	注册的声纹厂商、机构、组织，开启声纹后此字段必须填	否	"AISPEECH"

2.3.2 语音请求binary数据

调用端发送完opcode为text的报文之后，接着发送语音数据，opcode为binary，payload是语音数据；

语音数据建议分帧发送，每帧包含的语音时长是100毫秒；

语音数据发送完毕之后，再发送一个opcode为binary，payload是空，表示语音数据发送完毕。

2.4 发送文本请求

2.4.1 文本请求参数

参数名	含义	是否必须	取值示例
topic	用于区分语音请求，文本请求	是	nlu.input.text
recordId	uuid，标识一次请求，32字符	否	DUIddeeeeeeeeeeee88888888260c8ab
sessionId	uuid，服务端通过相同的sessionId关联多轮请求的上下文； 首轮对话请求不需要携带； 非首轮对话请求取值是上一轮服务端返回结果中的sessionId	否	DUIddeeeeeeeeeeee88888888260c8ab
refText	请求的文本	是	苏州的天气
aiType	指定云端服务的类型，asr表示识别结果，不设置该字段表示对话结果	否	asr

2.5 发送触发意图请求

2.5.1 触发意图请求参数

参数名	含义	是否必须	取值示例
topic	用于区分语音请求，文本请求，指定意图请求	是	dm.input.intent
recordId	uuid，标识一次请求，32字符	否	DUIddeeeeeeeeeeee88888888260c8ab
sessionId	uuid，服务端通过相同的sessionId关联多轮请求的上下文； 首轮对话请求不需要携带； 非首轮对话请求取值是上一轮服务端返回结果中的sessionId	否	DUIddeeeeeeeeeeee88888888260c8ab
intent	意图名称	是	查天气
task	任务名称	是	查天气
skillId	技能id，和skill两个字段中必须有一个	否	0000000000000000
skill	技能名称，和skillId两个字段中必须有一个	否	查天气
slots	语义槽名称，语义槽取值集合	否	{"城市":"苏州"}

2.6 上传自定义配置

自定义配置配合技能开发进行生效，具体请参照 配置对话回复 中的 资源查询结果引用——$参数名称$。

2.6.1 上传技能级配置

上传的数据仅在指定的技能中使用，如用户微信是否在登录状态。

 

参数名	含义	是否必须	取值示例
topic	string类型，表示技能级配置topic	是	skill.settings
recordId	string类型，uuid，标识一次请求，32字符	否	DUIddeeeeeeeeeeee88888888260c8ab
skillId	string类型，技能ID标识	是	0000000000000000
option	string类型，执行选项，设置、删除或查询	否	set(默认）/ delete / get
settings	json数组类型，每个元素标识一组设置的k-v列表	是	[{"key":"key1","value":"value1"}]
settings[0].key	string类型，自定义key名称	是	city
settings[0].value	string类型，自定义key对应的取值，当option是delete和get时不需要	否	苏州

 

2.6.2 上传系统级配置

上传的数据是公用的，有多个技能会关心并使用此类配置。如设备所在位置信息。

 

参数名	含义	是否必须	取值示例
topic	string类型，表示系统级设置topic	是	system.settings
recordId	string类型，uuid，标识一次请求，32字符	否	DUIddeeeeeeeeeeee88888888260c8ab
option	string类型，执行选项，设置、删除或查询	否	set(默认）/ delete / get
settings	json数组类型，每个元素标识一组设置的k-v列表	是	[{"key":"key1","value":"value1"}]
settings[0].key	string类型，自定义key名称	是	city
settings[0].value	string类型或者json，自定义key对应的取值，当option是delete和get时不需要	否	苏州

 

2.6.3 上传配置的响应

参数名	含义	取值示例
recordId	string类型，uuid, 标识一次请求	DUIddeeeeeeeeee88888888260c8ab
settings[0].key	option是get时返回，string类型，查询自定义的key名称	city
settings[0].value	option是get时返回， string类型，查到的value，如果没查到则是一个null	苏州
error.errId	错误码，出错时返回	1
error.errMsg	错误信息，出错时返回	params error

 

2.7 回复的对话结果（包括触发意图回复结果）

当请求的text报文没有aiType字段时，回复的是对话结果。

2.7.1 对话结果参数

参数名	含义	取值示例
dm.intentName	意图名称	查天气
dm.input	识别结果或者客户端发送的文本
dm.intentId	意图id	0000000000000000
dm.runSequence	本地执行command和播报nlg的先后顺序	nlgFirst
dm.widget	显示控件
dm.widget.widgetName	控件名称，冗余为了兼容老字段	card
dm.widget.subTitle	副标题	好听的歌
dm.widget.name	控件名称	card
dm.widget.extra	用于透传webapi返回字段
dm.widget.title	主标题	忘情水
dm.widget.buttons[].name	按钮显示提示	播放
dm.widget.duiWidget	控件类型，冗余为了兼容老字段	media
dm.widget.type	控件类型	media
dm.widget.count	列表控件内容数	1
dm.widget.content	列表控件内容
dm.widget.currentPage	列表控件当前页	2
dm.widget.totalPages	列表总共页数	5
dm.widget.itemsPerPage	每页显示数	5
dm.widget.match	内容是否匹配	1
dm.nlg	系统生成的对话回复	今天的天气是晴
dm.task	任务名称	查天气
dm.shouldEndSession	表示对话是否结束	true,false
skillId	技能id	0000000000000000
speakUrl	语音播报nlg的链接	https://dds.dui.ai/xxx
error.errId	错误id	010400
error.errMsg	错误信息	It's time to do qa.
recordId	uuid，标识一次请求，32字符	DUIddeeeeeeeeeeee88888888260c8ab
sessionId	uuid，服务端通过相同的sessionId关联多轮请求的上下文； 首轮对话请求不需要携带； 非首轮对话请求取值是上一轮服务端返回结果中的sessionId	DUIddeeeeeeeeeeee88888888260c8ab
contextId	向前兼容（sessionId替代了）待废弃

2.8 回复的识别结果

当请求的text报文有aiType字段，并且aiType字段为asr时，回复的是识别结果。

2.8.1识别结果参数

三、示例代码

3.1多轮对话交互python示例代码

查看示例代码

3.2多轮对话交互java示例代码

查看示例代码