本文主要介绍如何快速接入自定义机器人，帮助您在 IM 应用中实现多样化的 AI 服务，在一对一（P2P）和群组（高级群，Team）场景中进行即时通讯。

网易云信的即时通讯自定义机器人服务，仅面向已成功接入的用户提供。对于尚未接入过的用户，推荐您尝试 AI 数字人 功能。

技术原理

接入自定义机器人后，IM 应用中的工作流程如下（以单聊为例）：

主要流程如下：

1. 用户发送消息给机器人（提前定义好机器人的用户账号 accid）。
2. 网易云信 IM 服务器检测到发送对象为机器人后，发送给网易云信机器人服务器。
3. 网易云信机器人服务器调用自定义机器人服务的相关接口。
4. 自定义机器人服务响应，返回回复内容。
5. 网易云信机器人服务器调用网易云信的发送消息接口将回复内容发送到网易云信 IM 服务器。
6. 网易云信 IM 服务器将机器人的回复消息返回给用户。

当您开通第三方回调和安全通服务时，您发送的消息以及机器人回复的消息都会经过安全审核，相关内容请参考 安全通。

前提条件

已在 网易云信控制台 创建应用并 注册网易云信 IM 账号，获取网易云信 IM 账号和 Token。

实现流程

1. 接收方调用 addMessageListener 方法注册消息监听器，监听消息接收回调事件 onReceiveMessages。

2. 发送方 调用 createTextMessage 方法，构建一条文本消息。然后调用 sendMessage 方法向机器人发送文本消息。

   向机器人发送消息时，需要在消息体（V2NIMMessage）中通过 robotConfig 配置机器人信息，字段类型为 V2NIMMessageRobotConfig。

   V2NIMMessageRobotConfig 说明：

   如果您的应用平台为 Android，则需要调用对应的成员函数获取对应参数。

   名称	类型	是否必填	默认值	说明
   accountId	String	是	-	机器人账号，必须与在 网易云信控制台 配置的机器人 account 一致。 该字段仅对群组消息有效。
   topic	String	是	-	机器人消息话题
   function	String	否	-	机器人具体功能
   customContent	String	否	-	机器人自定义内容

   目前机器人消息功能支持多种消息类型，包括文本消息、图片消息、语音消息、视频消息、文件消息、地理位置消息、提示消息、通知消息以及自定义消息。具体实现流程请参考 消息收发。

3. 接收方 通过 onReceiveMessages 回调收到文本消息。

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 值计算示例：

  JavaString requestBody = "{}";
  String MD5 = CheckSumBuilder.getMD5(requestBody); //参考 接口概述 -> API checksum 校验 部分
  

• CheckSum 值计算示例：

  JavaString 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

示例：

JSON{
  "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 格式，示例：

JSON{
  "code":200,
  "data":{
        "type":0,
        "body":"xxx",
        "antispam":false
     }
}

data 中为第三方机器人返回的消息体详情，具体参数说明请参考以下表格：

• 消息体中并不是每个字段都一定会返回，注意对各字段的判空处理。
• 第三方机器人返回的参数字段（响应参数）与网易云信 IM 服务端 API 发送消息）接口的请求参数一致。

单击查看具体参数说明。

​ ​ ​

参数	类型	说明
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"} 字段说明： 1. type: 1：文本，2：图片，3：视频 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 如需设置为好友关系才能发送消息，需先在 [网易云信控制台](https://app.yunxin.163.com/global/home) 完成配置。
subType	Integer	自定义消息子类型，大于 0
msgSenderNoSense	Integer	发送方是否无感知。0-有感知，1-无感知。默认 0，若无感知，则消息发送者无该消息的多端、漫游、历史记录等可设置是否在历史记录查询结果中包含无感知消息，具体参考 分页查询历史消息。
msgReceiverNoSense	Integer	接受方是否无感知。0-有感知，1-无感知。默认 0，若无感知，则消息接收者者无该消息的多端、漫游、历史记录等可设置是否在历史记录查询结果中包含无感知消息，具体参考 分页查询历史消息。
env	String	当前消息需要抄送到的环境的名称，对应您在 [网易云信控制台](https://app.yunxin.163.com/global/home) 中配置的自定义抄送的环境名称，最大 32 个字符