开通和配置第三方机器人
更新时间: 2024/07/29 17:31:56
本文主要介绍如何在控制台开通并配置第三方机器人。
配置好第三方机器人后,可在单聊或群聊中与机器人进行互动。
前提条件
已注册计划接入的第三方机器人服务的相应账号,获取 API 密钥。
实现流程
-
在控制台首页应用管理中选择应用,然后单击 IM 即时通讯下的功能配置按钮进入功能配置页。
-
顶部选择账号管理页签,单击机器人右侧的子功能配置。
-
单击添加机器人按钮,进入机器人具体配置页。
-
填写机器人信息
字段 必填 说明 机器人accid 是 输入机器人对应的 IM 账号(accid)
可以是已注册的云信 IM 账号,也可以是未注册过的用户自定义的账号(云信后台会自行注册对应的 IM 账号)机器人名称 否 输入机器人名称 头像 否 上传机器人头像,支持 jpg/png/jpeg 格式,单个文件大小限制 5MB 以内 机器人能力 是 选择机器人的能力,默认为“微软openAI ChatGPT”,也可以选择自定义的机器人能力 -
配置机器人能力
-
配置消息逻辑
字段 必填 说明 消息回溯条数 是 发给 ChatGPT 需要往前回溯的消息条数限制 消息回溯时间 是 发给 ChatGPT 需要往前回溯消息的时间限制 回复消息是否直接下放 是 直接下发的消息不会回调至业务服务器,也不会通过云信自带审核服务,默认为是
-
-
配置完后,单击保存,即机器人创建完成,可以与机器人开始对话。
可以配置多个机器人,且 webhook 地址可以相同。
自定义机器人 Webhook 接口规范
自定义机器人 Webhook 的请求和响应格式需要满足具体的规范要求,否则云信服务器将不会处理相关请求。
请求格式
请求头说明
您需在请求头中传入如下参数:
Header 参数 | 类型 | 说明 |
---|---|---|
AppKey |
String | 您的应用的 App Key,具体获取方式请参见获取 App Key |
CurTime |
Long | 当前 UTC 时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到现在的毫秒数(Long) |
MD5 |
String | 根据请求中的 request body 计算出来的 MD5 值 |
CheckSum |
String | 校验值 |
Content-Type |
String | 请求消息体类型,一般为:application/json |
-
MD5值计算示例:
java
String requestBody = "{}"; String MD5 = CheckSumBuilder.getMD5(requestBody); //参考 接口概述 -> API checksum校验 部分
-
CheckSum值计算示例:
java
String AppSecret = "90ud57s6****"; String MD5 = "9894907e4ad9de467809127750******"; String CurTime = "1440570500855"; ////当前UTC时间戳,从1970年1月1日0点0 分0 秒开始到现在的毫秒数(String) String CheckSum = CheckSumBuilder.getCheckSum(AppSecret, MD5, CurTime); //参考 接口概述 -> API checksum校验 部分
请求的 HTTP Body 说明
Body 为消息体,统一为 JSON 格式。
具体字段信息如下:
参数名称 | 类型 | 必须 | 说明 |
---|---|---|---|
+ msg | JSON | 是 | 用户发送给机器人的消息 |
lastMsgs | JSONArray | 否 | 需要回溯的消息,每个JSON 为一条回溯的 msg |
示例:
java{
"msg": {
"fromAccount": "xx",
"to": "acc2",
"robotAccid": "acc2",
"robotFunction": "acc2",
"robotTopic": "aaa",
"robotCustomContent": "xx",
"msgType": "TEXT",
"body": "XX",
"attach": "xx",
"ext": "xx",
"msgTimestamp": 123,
"msgidClient": "xxx",
"msgidServer": 222
},
"lastMsgs": [
{},
{}
]
}
响应格式
响应的 Content-Type Header 需要设置为 application/json; charset=utf-8
。
响应消息体为 JSON 格式,示例:
java{
"code":200,
"data":{
"type":0,
"body":"xxx",
"antispam":false
}
}
data 中为第三方机器人返回的消息体详情,具体参数说明请参考以下表格:
- 消息体中并不是每个字段都一定会返回,注意对各字段的判空处理。
- 第三方机器人返回的参数字段(响应参数)与云信 IM 发送消息接口(/msg/sendMsg.action)接口的请求参数一致。
单击查看具体参数说明
参数 | 类型 | 说明 |
---|---|---|
type | Integer |
|
body | String | 消息内容,最大长度 5000 字符,JSON 格式,具体请参见:消息格式示例消息格式示例 |
msgDesc | String | 消息描述文本,对文本消息和提示消息以外的消息类型有效,最大长度 500 字符。该描述信息可用于云端历史消息关键词检索 |
antispam | Boolean |
已开通安全通的前提下,是否对自定义消息的指定内容(antispamCustom)进行审核,默认 false |
antispamCustom | String |
在 antispam 参数为 true 时生效 自定义的反垃圾检测内容, JSON 格式,长度限制同 body 字段,不能超过 5000 字符,要求 antispamCustom 格式如下: {"type":1,"data":"custom content"} 字段说明: type: 1:文本,2:图片 data: 文本内容或图片地址 |
option | String |
发消息时特殊指定的行为选项,JSON 格式,可用于指定消息的漫游、存云端历史、发送方多端同步、推送、消息抄送等特殊行为。option 中字段不填时表示默认值
,option 示例: {"push":false,"roam":true,"history":false,"sendersync":true,"route":false,"badge":false,"needPushNick":true} 字段说明:
|
pushcontent | String |
推送文案,最长 500 字符。option 选项中允许推送(push=true)后才能配置推送文案。pushcontent 如果不填,则使用默认文案。推送文案的显示规则如下:
|
payload | String | 推送对应的 payload,必须是 JSON 格式,不能超过 2048 字符。更多说明请参见 推送 payload 配置 |
ext | String | 开发者扩展字段,必须是 JSON 格式,长度限制1024字符 |
forcepushall | Boolean | 发送群消息时,强推(@操作)列表是否为群里除发送者外的所有有效成员,默认为 false |
forcepushlist | String |
发送群消息时的强推(@操作)用户列表,格式为JSONArray,如["accid1","accid2"]。若 forcepushall 为 true,则 forcepushlist 为除发送者外的所有有效群成员 |
forcepushcontent | String | 发送群消息时,针对强推列表forcepushlist中的用户,强制推送的内容,最大 500 字符 |
useYidun | Integer |
单条消息(包括自定义消息)是否使用安全通(即易盾反垃圾),只能传 0,传其他值相当于不传 0:(在已开通安全通的情况下)不使用安全通 若不填此字段,即在默认情况下,若应用开通了易盾反垃圾功能,则使用易盾反垃圾来进行垃圾消息的判断 |
bid | String | 安全通业务 ID,可以指定当前消息过安全通某个检测配置,若不填则使用原来的检测配置 |
yidunAntiCheating | String |
透传给易盾的反作弊检测参数,格式为 JSON,长度限制 1024 字符(具体请参见易盾的反垃圾防刷版专属字段) |
yidunAntiSpamExt | String |
透传给易盾的反垃圾含圈组版的检测参数,格式为 JSON,长度限制 1024 字符(具体请参见易盾的反垃圾含圈组版用户可扩展字段) |
markRead | Integer | 群消息是否需要已读业务(仅对群消息有效),0:不需要,1:需要 |
async | Boolean | 是否异步,默认 false |
checkFriend | Boolean |
是否为好友关系才能发送消息,默认为 false |
subType | Integer | 自定义消息子类型,大于0 |
msgSenderNoSense | Integer |
发送方是否无感知。0-有感知,1-无感知。默认 0,若无感知,则消息发送者无该消息的多端、漫游、历史记录等 |
msgReceiverNoSense | Integer |
接受方是否无感知。0-有感知,1-无感知。默认 0,若无感知,则消息接收者者无该消息的多端、漫游、历史记录等 |
env | String | 当前消息需要抄送到的环境的名称,对应您在云信控制台中配置的自定义抄送的环境名称,最大 32 个字符 |
此文档是否对你有帮助?