本文主要介绍如何在控制台开通并配置第三方机器人。

配置好第三方机器人后，可在单聊或群聊中与机器人进行互动。

前提条件

已注册计划接入的第三方机器人服务的相应账号，获取 API 密钥。

实现流程

1. 在控制台首页应用管理中选择应用，然后单击 IM 即时通讯 专业版下的功能配置按钮进入功能配置页。

   

2. 顶部选择账号管理页签，单击机器人右侧的子功能配置。

   

3. 单击添加机器人按钮，进入机器人具体配置页。

   • 填写机器人信息

     

     字段	必填	说明
     机器人accid	是	输入机器人对应的 IM 账号（accid） 可以是已注册的云信 IM 账号，也可以是未注册过的用户自定义的账号（云信后台会自行注册对应的 IM 账号）
     机器人名称	否	输入机器人名称
     头像	否	上传机器人头像，支持 jpg/png/jpeg 格式，单个文件大小限制 5MB 以内
     机器人能力	是	选择机器人的能力，默认为“微软openAI ChatGPT”，也可以选择自定义的机器人能力

   • 配置机器人能力

     微软openAI ChatGPT

     若选择 “微软openAI ChatGPT” 机器人能力，则需要配置对应的 Azure OpenAI，具体请参考微软官网文档。

     

     自定义的机器人

     若选择 “自定义” 机器人能力，则需要配置对应的 Webhook 地址。自定义机器人 Webhook 的请求和响应格式需要满足具体的接口规范，否则云信服务器将不会处理相关请求。

     

   • 配置消息逻辑

     

     字段	必填	说明
     消息回溯条数	是	发给 ChatGPT 需要往前回溯的消息条数限制
     消息回溯时间	是	发给 ChatGPT 需要往前回溯消息的时间限制
     回复消息是否直接下放	是	直接下发的消息不会回调至业务服务器，也不会通过云信自带审核服务，默认为是

4. 配置完后，单击保存，即机器人创建完成，可以与机器人开始对话。

   可以配置多个机器人，且 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	是	用户发送给机器人的消息
fromAccount	String	是	发送者账户，accid
to	String	是	单聊场景下传入对应接收消息的机器人账号（accid）；群聊场景下传入所在的群组 ID（teamid）
robotAccid	String	是	机器人账号，accid
robotFunction	String	是	机器人function
robotTopic	String	否	机器人消息的话题
robotCustomContent	String	否	机器人自定义内容
msgType	String	是	消息类型，TEXT：文本消息；PICTURE：图片消息；AUDIO：语音消息；VIDEO：视频消息；LOCATION：地理位置；NOTIFICATION：通知；FILE：文件消息；TIPS：提示类型消息；CUSTOM：自定义消息
body	String	否	消息内容，部分消息类型不需要传入该参数，但需传入 attach，示例以及具体说明请参见：消息格式示例
attach	String	否	消息附件，部分消息类型不需要传入该参数，但需传入 body，示例以及具体说明请参见：消息格式示例
ext	String	否	消息扩展字段
msgTimestamp	Long	否	消息发送时间戳
msgidClient	String	否	客户端生成的消息 ID
msgidServer	Long	否	服务端生成的消息 ID
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	0：文本消息 1：图片消息 2：语音消息 3：视频消息 4：地理位置消息 6：文件消息 10：提示消息 100：自定义消息对于未开通安全通（即易盾反垃圾）功能的应用，自定义消息不会过内容审核。
body	String	消息内容，最大长度 5000 字符，JSON 格式，具体请参见：消息格式示例消息格式示例
msgDesc	String	消息描述文本，对文本消息和提示消息以外的消息类型有效，最大长度 500 字符。该描述信息可用于云端历史消息关键词检索
antispam	Boolean	已开通安全通的前提下，是否对自定义消息的指定内容（antispamCustom）进行审核，默认 false 该参数只对自定义消息（消息类型为：100 ）生效。
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} 字段说明： roam: 该消息是否需要漫游，默认 true（需要已为应用开通漫游消息功能） history: 该消息是否存云端历史，默认 true sendersync: 该消息是否需要发送方多端同步，默认 true push: 该消息是否需要 APNs 推送或 Android 系统通知栏推送，默认 true route: 该消息是否需要抄送至指定的应用服务器；默认 true (需要已为应用开通消息抄送功能); badge: 该消息是否需要计入到未读计数中，默认 true; needPushNick: 推送文案是否需要带上昵称，不设置该参数时默认 true persistent: 是否需要存离线消息，不设置该参数时默认 true。离线消息指不在线时其他人发来的消息。如果存离线，在用户下次登录时，IM 服务端会自动将离线期间暂存的离线消息自动下发到客户端SDK。单聊场景下发最近 30 天内的最新的 5000 条离线消息，且每个会话最多 100 条最新的离线消息；群聊场景下发最近 30 天内的离线消息，且每个群聊会话最多下发 100 条最新的离线消息。 sessionUpdate: 是否将本消息更新到服务端会话列表中本会话的最后一条消息（lastmsg），默认 true
pushcontent	String	推送文案，最长 500 字符。option 选项中允许推送（push=true）后才能配置推送文案。pushcontent 如果不填，则使用默认文案。推送文案的显示规则如下： pushcontent不为空且needPushNick=true，最终推送文案为：推送者昵称+pushcontent pushcontent不为空且needPushNick=false，最终推送文案为：pushcontent pushcontent为空且needPushNick=true ，最终推送文案为：推送者昵称+默认文案 pushcontent为空且needPushNick=false，最终推送文案为：默认文案 其中，根据消息类型，默认文案分为以下几种： 文本消息默认文案：发来了一条消息 地理位置默认文案：发来了一个地理位置 语音消息默认文案：发来了一段语音 视频消息默认文案：发来了一段视频 文件消息默认文案：发来了一个文件 图片消息默认文案：发来了一张图片 语音聊天邀请消息默认文案：发来了语音聊天邀请 视频聊天邀请消息默认文案：发来了视频聊天邀请
payload	String	推送对应的 payload，必须是 JSON 格式，不能超过 2048 字符。更多说明请参见 推送 payload 配置
ext	String	开发者扩展字段，必须是 JSON 格式，长度限制1024字符
forcepushall	Boolean	发送群消息时，强推（@操作）列表是否为群里除发送者外的所有有效成员，默认为 false
forcepushlist	String	发送群消息时的强推（@操作）用户列表，格式为JSONArray，如["accid1","accid2"]。若 forcepushall 为 true，则 forcepushlist 为除发送者外的所有有效群成员最多可强推 100 个用户，如果超过将报错（状态码：811）。
forcepushcontent	String	发送群消息时，针对强推列表forcepushlist中的用户，强制推送的内容，最大 500 字符
useYidun	Integer	单条消息（包括自定义消息）是否使用安全通（即易盾反垃圾），只能传 0，传其他值相当于不传 0：（在已开通安全通的情况下）不使用安全通 若不填此字段，即在默认情况下，若应用开通了易盾反垃圾功能，则使用易盾反垃圾来进行垃圾消息的判断
bid	String	安全通业务 ID，可以指定当前消息过安全通某个检测配置，若不填则使用原来的检测配置
yidunAntiCheating	String	透传给易盾的反作弊检测参数，格式为 JSON，长度限制 1024 字符（具体请参见易盾的反垃圾防刷版专属字段） 反作弊相关的email、phone、token、extension，抄送到yidunAntiCheating。其他用户增值信息，抄送到 yidunAntiSpamExt。 yidunAntiSpamExt 传入的值默认覆盖 extension。
yidunAntiSpamExt	String	透传给易盾的反垃圾含圈组版的检测参数，格式为 JSON，长度限制 1024 字符（具体请参见易盾的反垃圾含圈组版用户可扩展字段）反作弊相关的email、phone、token、extension，抄送到 yidunAntiCheating。其他用户增值信息，抄送到 yidunAntiSpamExt。
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 个字符