服务端
API 参考
圈组

批量发送单聊消息

更新时间: 2024/05/23 10:25:39

本文介绍如何使用服务端 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 个账号。
typeint 0 表示文本消息,
1 表示图片消息,
2 表示语音消息,
3 表示视频消息,
4 表示地理位置消息,
6 表示文件消息,
10 表示提示消息,
100 表示自定义消息
bodyString消息内容,最大长度 5000 字符,JSON 格式,具体请参见:消息格式示例
msgDescString消息描述文本,只对文本消息和提示消息以外的消息类型有效,最大长度 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 个字符

自定义抄送环境.png

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 服务出错 -
此文档是否对你有帮助?
有帮助
去反馈
  • 功能描述
  • API 使用限制
  • URL
  • 请求参数
  • 返回参数
  • 示例
  • cURL请求示例
  • 请求成功返回示例
  • 请求失败返回示例
  • 状态码