智能回复机器人API使用说明

最后更新于 2024/04/03

前置条件：魔音提供appKey、appSecret，以便获取相应权限

接口一：获取机器人token

请求URL

https://hapi.moyincloud.com/robot/open/token/get

请求方式

POST

参数

Json方式

参数名	必选	类型	说明
appKey	是	string	客户专有key，由魔音分配
appSecret	是	string	客户专有Secret，由魔音分配
robotName	是	string	机器人标识
ts	是	string	时间戳，精确到毫秒，如1684846661967
sign	是	string	签名，md5(appKey+robotName+ts) ,32位小写

举例：

{
    "robotName":"yy",
    "appKey":"XXX",
    "appSecret":"XXX",
    "ts":"1684846661967",
    "sign":"aebfe221223ed06ea7ad298fc7e8b81a"
}

1
2
3
4
5
6
7

JSON

返回示例

{
    "code": 0,
    "data": {
        "expireTime": "2023-05-23 22:57:59",
        "robotId": "1000043",
        "robotName": "xxx",
        "token": "d5df79e4cf604d04bf73a97d813b39bd"
    },
    "desc": "成功",
    "reqId": "725cae0f-3ed2-4ba0-a9ce-9ca83a0f81e4"
}

1
2
3
4
5
6
7
8
9
10
11

JSON

返回参数说明

参数名	类型	说明
code	int	0表示获取成功
expireTime	Date字符串	token过期时间，一般自生成起2小时
token	String	token值

注意

token建议在本地缓存（可以根据expireTime设置缓存时间，预留一些提前量），提升效率

接口二：机器人回复-流式

请求URL

https://hapi.moyincloud.com/robot/open/chat/stream

请求方式

POST

参数

Json方式

参数名	必选	类型	说明
chatId	是	String	会话ID，使用32位随机数
robotName	是	String	机器人标识
question	是	String	用户提问内容
token	是	String	该机器人对应的token
ts	是	String	时间戳，精确到毫秒，如1684846661967
sign	是	String	签名，md5(robotName+chatId+URLEncode(question)+ts) ,32位小写
outerParam	否	String	自定义参数，JSON，该值会在接口返回时带上
visitorId	否	string	聊天用户的id，非必填
accountId	否	string	聊天用户所在组织的id，非必填
isDisplayRecommend	否	Integer	是否在回复中推荐相关内容，1表示推荐，0表示无，默认1

传参举例：

{
    "robotName":"yy",
    "chatId":"99d642572d4e59a6c653791f66ef0b85",
    "question":"hello",
    "ts":"1684846992569",
    "sign":"4041faa1bc519e77f0413f6da0df9308",
    "token":"9f4f28ddaaa64042a05d4d4566630fbff4f13175ccf047a1b2188cf6349dff18"
    "outerParam":{"userId":"100066"}
}

1
2
3
4
5
6
7
8
9

JSON

返回值示例

id:1689160389865
data:{"content":"","role":"assistant"}

id:1689160394213
data:{"content":"您好","role":"assistant"}

id:1689160394219
data:{"content":"，请","role":"assistant"}

id:1689160394222
data:{"content":"问有","role":"assistant"}

id:1689160394225
data:{"content":"什么","role":"assistant"}

id:1689160394229
data:{"content":"可以","role":"assistant"}

id:1689160394232
data:{"content":"帮您","role":"assistant"}

id:1689160394236
data:{"content":"？","role":"assistant"}

id:1689160394239
event:systemInfo
data:{"content":"","extCode":"","extInfo":null,"isTransferToHuman":0,"outerParam":{"vId":20019280},"recordId":"1679086490430345216","role":"system"}

id:1689160394269
data:[DONE]

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

Plaintext

返回参数说明

该接口是SSE流式输出，每次输出的内容结构主要有以下几种

机器人回复的普通消息
id:1689160394239
data:{"content":"XXX","role":"assistant"}

或者：系统消息（该类型的消息特点是有event属性，event=systemInfo）
id:1689160394289
event:systemInfo
data:{"content":"","role":"system","recordId":1677950676953186306,"outerParam":{"userId":"1000"},"extCode":"1004","extInfo":{"recommendIdList":[1762819222246920193,1761778983155929089]}}

或者：当前请求返回的消息结束标识
id:1689160396631
data:[DONE]

1
2
3
4
5
6
7
8
9
10
11
12

Plaintext

消息各字段的含义如下

{ "content":"", --该字段表示机器人返回的信息，该字段可能为空（例如用于维持连接的心跳消息，以及systemInfo类型的消息）
"role":"system", --该字段表示消息角色，assistant为机器人，system为系统 "recordId":"1677950676953186306", --该字段为该消息记录ID，用于点赞、踩、评价等后续操作 "isTransferToHuman":0, --该字段为1表示当前消息用户意图是转人工，0或空为非转人工 "outerParam":{ -- 该部分是原样返回用户调用接口时传的outerParam参数，没有传参时为空
}, "extCode":"1004", --该字段表示扩展信息类型，和extInfo配合使用，不同的extCode对应不同的extInfo结构，无此信息时为null，1004表示推荐问题列表
"extInfo":{ -- 扩展信息，用于机器人向调用者发送约定内容，无此信息时为空 }

注：content和role是必含字段，其余字段可能无，role为system的消息不需要展示给用户

消息体字段说明

参数名	类型	说明
id	String	消息序列id
event	String	消息类型，普通消息无该字段如果含有event字段，需要根据其类型做相应的处理，例如系统消息event=systemInfo
data	String	消息值，JSON格式，例如{"content":"xxx","role":"assistant"}，其中content为机器人回复内容详细信息参见上文中的《消息各字段的含义》部分

sse 可以参考 https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#event_stream_format

机器人聊天内容的约定项

1、机器人返回结果需要前端兼容 HTML 和 markdown 两种格式

HTML常见标签：如p、a、br、img、video、div、td、tr、table 等
markdown常见标签：如链接、图片、标题等

2、关于推荐问题的约定

机器人在回答客户问题时，会推荐相关的问题，例如：

您好，关于录入固定资产，我可以为您解答关于固定资产信息录入、固定资产卡片管理、固定资产原始卡片录入等方面的问题。例如：
<a href="#message">如何录入固定资产信息？</a>
<a href="#message">固定资产卡片的管理方法有哪些？</a>
<a href="#message">如何进行固定资产原始卡片的录入操作？</a>
请问您具体想咨询哪方面的问题呢？

1
2
3
4
5

JSON

接口返回的内容中，推荐问题有固定格式（a链接语法）：<a href="#message">如何录入固定资产信息？</a>

推荐的处理方式是：

显示为可点击的链接
用户点击该链接，直接使用用户身份发送该链接对应的文本问题（即例子中的：如何录入固定资产信息？）

未能解决您的问题？请联系

在线客服

本篇目录

接口一：获取机器人token

请求URL

请求方式

参数

返回示例

返回参数说明

注意

接口二：机器人回复-流式

请求URL

请求方式

参数

返回值示例

返回参数说明

消息各字段的含义如下

机器人聊天内容的约定项

1、机器人返回结果需要前端兼容 HTML 和 markdown 两种格式

2、关于推荐问题的约定

接口一：获取机器人token

请求URL

请求方式

参数

返回示例

返回参数说明

注意

接口二：机器人回复-流式

请求URL

请求方式

参数

返回值示例

返回参数说明

消息各字段的含义如下

机器人聊天内容的约定项

1、机器人返回结果需要前端兼容 HTML 和 markdown 两种格式

2、关于推荐问题的约定

魔音智能

产品

关于

联系我们