本文介绍如何使用服务端 API 批量发送单聊消息。

功能描述

批量给多个用户发送单聊消息。

API 使用限制

• 最多可批量给 500 个用户账号发送单聊消息。如果批量提供的帐号中有未注册的帐号，会提示并返回给用户。
  
• 单个应用最高调用频率 120 次/分。如超限，将报错（状态码：416），并且应用将被屏蔽 1 分钟，之后才可再次调用。
  

URL

httpPOST https://api.netease.im/nimserver/msg/sendBatchMsg.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

请求参数

• POST 请求中 Headers 的设置请参见API调用方式。

• POST 请求中 Body 的设置如下：

​

参数	类型	必填	说明
fromAccid	String	是	发送者的网易云信 IM 账号（accid），最大 32 字符， 必须保证一个APP内唯一
toAccids	String	是	消息接收者的网易云信 IM 账号（accid）列表，示例：["accid1","accid2","accid3"]（JSONArray对应的 accid，如果解析出错，会报 414 错误），限 500 人如果将入参 returnMsgid 设为 true，即需要返回消息 ID，那么 toAccids 中最多传入 100 个账号。
type	int	是	0 表示文本消息, 1 表示图片消息， 2 表示语音消息， 3 表示视频消息， 4 表示地理位置消息， 6 表示文件消息， 10 表示提示消息， 100 表示自定义消息
body	String	是	消息内容，最大长度 5000 字符，JSON 格式，具体请参见：消息格式示例
msgDesc	String	否	消息描述文本，只对文本消息和提示消息以外的消息类型有效，最大长度 500 字符。该描述信息可用于云端历史消息关键词检索
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 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 字符
useYidun	int	否	单条消息（包括自定义消息）是否使用安全通（即易盾反垃圾），只能传 0，传其他值相当于不传 0：（在已开通安全通的情况下）不使用安全通 若不填此字段，即在默认情况下，若应用开通了易盾反垃圾功能，则使用易盾反垃圾来进行垃圾消息的判断
bid	String	否	安全通业务 ID，可以指定当前消息过安全通某个检测配置，若不填则使用原来的检测配置
yidunAntiCheating	String	否	透传给易盾的反作弊检测参数，格式为 JSON，长度限制 1024 字符（具体请参见易盾的反垃圾防刷版专属字段）反作弊相关的email、phone、token、extension，抄送到 yidunAntiCheating。其他用户增值信息，抄送到 yidunAntiSpamExt
yidunAntiSpamExt	String	否	透传给易盾的反垃圾含圈组版的检测参数，格式为 JSON，长度限制 1024 字符。（具体请参见易盾的反垃圾含圈组版用户可扩展字段）。反作弊相关的email、phone、token、extension，抄送到 yidunAntiCheating。其他用户增值信息，抄送到 yidunAntiSpamExt
returnMsgid	Boolean	否	是否需要返回消息ID false：不返回消息ID（默认值） true：返回消息ID如果选择 true，即需要返回消息 ID，那么 toAccids 中最多传入 100 个账号。
env	String	否	当前消息需要抄送到的环境的名称，对应您在云信控制台中配置的自定义抄送的环境名称（如下图），最大 32 个字符
msgSenderNoSense	int	否	发送方是否无感知。如果 toAccids 中包含发送方，则无感知失效。 0：有感知（默认），1：无感知。若无感知，则消息发送者无该消息的多端、漫游、历史记录等 可设置是否在历史记录查询结果中包含无感知消息，具体参见单聊云端历史消息查询和群聊云端历史消息查询。

返回参数

参数	类型	说明
unregister	JSONArray	toAccids 列表中存在的未注册用户，示例：["123123","111422"]
timetag	Long	消息发送的时间戳
msgids	String	发送给每个 accid 的消息 ID 列表，示例：{"12345":1200510468189,"55213":3141251231231}，该示例中"12345"和"55213"表示 accid，1200510468189 和 3141251231231 表示消息 ID

示例

cURL请求示例

curlcurl -X POST -H "AppKey: go9dnk49**0803mgq3" -H "Nonce: 4tggge**t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'fromAccid=zhangsan&toAccids=["aaa","bbb"]&type=0&body={"msg":"hello"}' 'https://api.netease.im/nimserver/msg/sendBatchMsg.action'

请求成功返回示例

json"Content-Type": "application/json; charset=utf-8"
{
    "code":200
    "unregister":["123123","111422"]  // toAccids列表中存在的未注册用户
    "timetag":123124124124   // 消息发送的时间戳
    "msgids":{      // 发送给每个accid的消息id列表
        "12345":1200510468189,  // 发送给用户12345的消息，消息id为1200510468189
        "55213":3141251231231  // 发送给用户55213的消息，消息id为3141251231231
     }
}

请求失败返回示例

"Content-Type": "application/json; charset=utf-8"
{
    "code":414
    "desc":"too many members."  // toAccids中的用户数过多
}

"Content-Type": "application/json; charset=utf-8"
{
    "code":423
    "desc":"account 'mute'."  // 发送方账号被禁言
}

状态码

该接口在 HTTPS Body 中返回请求的状态码，以下仅列出与接口业务相关的状态码。完整状态码请参见状态码。

状态码	说明	处理建议
200	请求成功	-
414	参数错误	根据提示信息，检查传入参数的格式和限制条件
403	导致请求失败的原因可能为： 权限校验失败 应用没有发送普通消息的权限	-
422	发送方账号被禁用	检查账号是否可用
423	发送方账号被禁言	检查发送方发消息的权限
500	服务出错	-