# API接入文档

# 接入准备

# 获取Accesskey

与我司商务合作后，我司会给客户appId和appSecret。请妥善保存appSecret

# 开发以及联调测试

客户通过appId和appSecret获取token，将token放入HTTP Header中可以请求对应的接口。

# API对接方式

# 公共请求头

字段 类型 是否必须 备注
token String Y 通过appId和appSecret获取token

# 公共返回参数

duix得到token和其他请求数据集合后，会先进行安全校验等验证，一系列验证通过后便会处理完成这次发送过来的数据请求，平台返回的参数格式如下：

字段 类型 是否必须 备注
code String Y 返回的状态码，为0表示成功
message String N 成功/错误的描述信息
data object N 返回的具体内容
success Boolean Y 是否成功

下文中如没有特殊说明，对返回值的解释都是指data内部的结构。

# 公共错误码

错误码 描述
0 正常
-1 系统异常
1005 token不能为空
1006 toke失效
1007 话术信息不存在
1009 用户可用次数不足
2002 会话信息不存在
40001 appid或者appscrect无效
40002 内部错误

# 构造签名获取token

对接duix-openapi-v2平台时，需在自己平台中集成生成token的代码,生成token的方法可参考以下代码：

  1. 引入依赖
<dependency>
    <groupId>com.auth0</groupId>
    <artifactId>java-jwt</artifactId>
    <version>3.8.3</version>
</dependency>
  1. Java 示例。
import com.auth0.jwt.JWT;
import com.auth0.jwt.algorithms.Algorithm;

import java.util.Calendar;
import java.util.Date;

/**
 * 创建签名
 *
 * @param appId  签发对象
 * @param secret 密钥
 * @param exp    到期时间：单位秒
 * @return
 */
public static String createSig(String appId,String secret,int exp){
        Calendar nowTime=Calendar.getInstance();
        nowTime.add(Calendar.SECOND,exp);
        Date expiresDate=nowTime.getTime();

        return JWT.create()
        //发行时间
        .withIssuedAt(new Date())
        //有效时间
        .withExpiresAt(expiresDate)
        //载荷
        .withClaim("appId",appId)
        //加密
        .sign(Algorithm.HMAC256(secret));
        }

# 校验签名

接口地址:

/duix-openapi-v2/sdk/checkSig

请求方式: GET

请求数据类型: application/json

响应数据类型: application/json

# 接口描述:

验证token有效性，并返回数字人实时交互ws连接地址

# 参数说明
参数名称 类型 传参方式 参数说明
sig String Query 与token相同
# 响应参数:
参数名称 类型 描述
appId String appId
wsService String 数字人实时交互ws地址

# 管理接口

管理类HTTP请求有一个共同的约定，需要在请求头中传token

# 获取APP实时并发数

# 接口地址:

/duix-openapi-v2/v1/getconcurrentNumber

# 请求方式: GET

接口描述:

查询某APP下并发数

# 参数说明
参数名称 类型 传参方式 参数说明
appId String Query 从平台创建的APPID

响应参数:

参数名称 类型
code String
data ConcurrentStatus
cropId String
totalConcurrentNumber integer(int32)
userConcurrentNumber integer(int32)
message String
success boolean

响应示例:

{
  "code": "",
  "data": {
    "cropId": "",
    "totalConcurrentNumber": 0,
    "userConcurrentNumber": 0
  },
  "message": "",
  "success": true
}

# 获取APP实时会话

# 接口地址:

/duix-openapi-v2/v1/getconcurrentList

# 请求方式: GET
# 接口描述:

查询某APP下的”通话中“的会话列表。

# 参数说明
参数名称 类型 传参方式 参数说明
appId String Query 从平台创建的APPID

# 关闭APP所有会话

# 接口地址:

/duix-openapi-v2/v1/distroyCallSessionsByAppId

# 请求方式: GET
# 接口描述：

关闭某APP下所有的会话

# 参数说明
参数名称 类型 传参方式 参数说明
appId String Query 从平台创建的APPID
# 响应示例:
{
  "code": "",
  "data": "",
  "message": "",
  "success": true
}

# 关闭指定会话

# 接口地址:

/duix-openapi-v2/v1/sessionStop

# 请求方式: GET
# 参数说明
参数名称 类型 传参方式 参数说明
uuid String Query start-complete事件返回的 sessionId 字段

# 第三方话术对接

# 其他会话集成: 其他会话平台可以通过以下的方式提供给数字人使用。DUIX平台可以通过你的数字人，使用POST方式请求一个你定义的远程URL，来获取问题的答案。
image.png
# 会话平台集成样例: 可以参考这个会话平台集成的例子。这个开源的应用实现了一个对话平台集成，该样例应用实现闲聊会话功能。
# 请求规范: DUIX平台将问题请求（客户想你的数字人提出的）按照以下格式，通过POST方式发送至你远程URL。
# 参数说明
Field Type Description Required
sid String 你的用户id，在创建用户时产生。可以在账号信息中查看。 Y
dh-code String 数字人编号，在每个数字人创建时产生，可以在数字人概览查看。 Y
dh-question String 你需要问数字的问题内容 Y
dh-conversation-id String 会话id，标识该会话的唯一标识 Y
dh-context String 关于该会话期间产生的上下文信息，该信息为已经字符串化的JSON格式数据。 N
# 请求示例:
{
  "sid": "100003",
  "dh-code": "187265485019156480",
  "dh-question": "who are you?",
  "dh-conversation-id": "0513e935-041f-48e0-9330-652ef4194511",
  "dh-context": "{}"
}

响应规范: 当你收到问题请求的时候，你需要按照下面的格式返回。

有效响应类型:

Code Status Response
200 OK 按照下面规范的返回体
400 Bad Request Request body/headers are invalid
401 Unauthorized 鉴权信息无效
403 Forbidden 鉴权失败
500 Server Error 服务异常

返回体规范:

Field Type Description Required
conversationId String 会话id，标识该会话的唯一标识，与请求参数体的dh-conversation-id一致。 Y
question String 用户所问的问题。 N
answer String 用户问数字人的问题的答案，这是一个字符串化的 JSON 对象。 Y
intent String 问题匹配到平台的意图 N
errorMsg String 异常或者对错误的描述 N
extra String 额外信息，JSON字符串 N

{
    "code": "200",
    "msg": "处理成功",
    "success": true,
    "data": {
		"conversationId": "0513e935-041f-48e0-9330-652ef4194511",
		"question": "who are you?",
		"answer": {
			"answer": "Welcome to UneeQ, how can I help?",
			"operations": {
				"tipPhrases": {
					"phrases": ["yes", "no"]
				},
				"canShowText": 1
			}
		},
		"intent": "introduce",
		"errorMsg": "",
		"extra": "{}"
	}
}

预期响应时间: 与数字人类的互动，由于他们的实时性，对延迟很敏感。因此，在处理来自DUIX平台的请求时，响应时间是需要考虑的一个重要因素。这些服务的响应时间需要95%以上在2000ms以内。如果响应时间超过20000ms，该请求将报出超时错误，但是数字人将继续响应。