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

功能描述

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

API 使用限制

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

URL

httpPOST https://api.yunxinapi.com/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 账号，最大 32 字符。必须保证一个 APP 内唯一。
toAccids	String	是	消息接收者的 IM 账号列表，示例：["accid1","accid2","accid3"]（JSONArray 对应的 accid，如果解析出错，会报 414 错误），限 500 人。如果将入参 returnMsgid 设为 true，即需要返回消息 ID，那么 toAccids 中最多传入 100 个账号。
type	int	是	消息类型。0 表示文本消息；1 表示图片消息；2 表示语音消息；3 表示视频消息；4 表示地理位置消息；6 表示文件消息；10 表示提示消息；100 表示自定义消息。
body	String	是	消息内容，JSON 格式，具体请参见：消息格式示例。 该字段长度上限以使用的 IM 套餐为准；IM 旗舰版及以上套餐才支持配置字段上限。
msgDesc	String	否	消息描述文本，只对文本消息和提示消息以外的消息类型有效，最大长度 500 字符。该描述信息可用于云端历史消息关键词检索。
option	String	否	发消息时特殊指定的行为选项，JSON 格式，可用于指定消息的漫游，存云端历史，发送方多端同步，推送，消息抄送等特殊行为。 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 格式，该字段长度上限以使用的 IM 套餐为准；IM 旗舰版及以上套餐才支持配置字段上限。
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	String	否	toAccids 列表中存在的未注册用户，格式为 JSONArray，示例：["123123","111422"]。
timetag	Long	是	消息发送的时间戳。
msgids	String	否	发送给每个 accid 的消息 ID 列表。只有将入参 returnMsgid 设为 true（需要返回消息 ID）时，才会返回 msgids。 示例：{"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.yunxinapi.com/nimserver/msg/sendBatchMsg.action'

请求成功返回示例

json"Content-Type": "application/json; charset=utf-8"
{
    "code":200
    "unregister":["123123","111422"]  // toAccids 列表中存在的未注册用户
    "timetag":123124124124   // 消息发送的时间戳
    "msgids":{      // 发送给每个 accid 的消息 id 列表,只有将入参 returnMsgid 设为 true 才会返回
        "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	服务出错	-