服务端 API

批量发送消息

使用 批量发送消息 从业务服务端调用 OpenIM 消息 REST 接口，由 APP 管理员向多个用户发送同一条消息，或向全量用户下发低频系统通知。

请先在接入准备中配置 API 地址和 Token；接口参数通过请求头和 JSON 请求体传递。

HTTP 请求

POST {API_ADDRESS}/msg/batch_send_msg

请求示例

curl --request POST "${API_ADDRESS}/msg/batch_send_msg" \
  --header "Content-Type: application/json; charset=utf-8" \
  --header "operationID: ${OPERATION_ID}" \
  --header "token: ${ADMIN_TOKEN}" \
  --data-raw '{
  "sendID": "openIMAdmin",
  "recvIDs": [
    "user_001",
    "user_002"
  ],
  "isSendAll": false,
  "groupID": "",
  "senderNickname": "系统通知",
  "senderFaceURL": "https://example.com/system.png",
  "senderPlatformID": 10,
  "content": {
    "content": "hello"
  },
  "contentType": 101,
  "sessionType": 1,
  "isOnlineOnly": false,
  "notOfflinePush": false,
  "sendTime": 1719800000000,
  "offlinePushInfo": {
    "title": "OpenIM 消息",
    "desc": "你收到一条新消息",
    "ex": "",
    "iOSPushSound": "default",
    "iOSBadgeCount": true,
    "signalInfo": ""
  },
  "ex": ""
}'

安全提示：管理员 Token 只能保存在业务服务端或 OpenIM Chat 服务端，不能下发到客户端或写入前端代码。批量发送会放大发送、推送和会话更新压力，建议在业务侧做频率控制。

参数

此接口通过请求头传入链路追踪信息和鉴权凭证，通过 JSON 请求体传递业务参数。

请求头

Header	是否必填	类型	说明
operationID	是	string	每次请求的唯一链路追踪 ID，建议由后端生成并写入日志。
token	是	string	APP 管理员 Token 或具备该用户访问权限的用户 Token；仅保存在可信后端服务中。
Content-Type: application/json	是	string	请求体为 JSON 时必须设置。

请求体

{
  "sendID": "openIMAdmin",
  "recvIDs": [
    "user_001",
    "user_002"
  ],
  "isSendAll": false,
  "groupID": "",
  "senderNickname": "系统通知",
  "senderFaceURL": "https://example.com/system.png",
  "senderPlatformID": 10,
  "content": {
    "content": "hello"
  },
  "contentType": 101,
  "sessionType": 1,
  "isOnlineOnly": false,
  "notOfflinePush": false,
  "sendTime": 1719800000000,
  "offlinePushInfo": {
    "title": "OpenIM 消息",
    "desc": "你收到一条新消息",
    "ex": "",
    "iOSPushSound": "default",
    "iOSBadgeCount": true,
    "signalInfo": ""
  },
  "ex": ""
}

参数名	是否必填	类型	说明
recvIDs	条件	array	`isSendAll=false` 时的接收用户 ID 列表。
isSendAll	否	boolean	是否发送给全部用户；为 true 时服务端分页读取全量用户 ID。
sendID	是	string	发送者用户 ID，可为系统通知号或普通用户 ID。
groupID	条件	string	群聊目标群 ID；`sessionType=3` 时必填。
senderNickname	否	string	发送者昵称。
senderFaceURL	否	string	发送者头像 URL。
senderPlatformID	否	int	发送者终端平台 ID；管理端模拟发送通常传 10。
content	是	object	消息内容对象，结构由 `contentType` 决定。见消息内容类型。
content.content	条件	string	文本消息内容；`contentType=101` 时使用。
contentType	是	int	消息内容类型，参见消息内容类型。
sessionType	是	int	会话类型，参见会话模块的 `ConversationType`。
isOnlineOnly	否	boolean	是否只在线投递；为 true 时关闭历史、持久化、发送方同步和会话更新。
notOfflinePush	否	boolean	是否不触发离线推送；为 true 时关闭离线推送。
sendTime	否	int	消息发送时间，Unix 毫秒时间戳；导入历史消息时可指定。
offlinePushInfo	否	object	离线推送信息；`notOfflinePush=false` 时生效，字段见下方。
offlinePushInfo.title	否	string	离线推送标题。
offlinePushInfo.desc	否	string	离线推送描述。
offlinePushInfo.ex	否	string	离线推送扩展字段。
offlinePushInfo.iOSPushSound	否	string	iOS 推送声音。
offlinePushInfo.iOSBadgeCount	否	boolean	iOS 推送是否计入桌面角标。
offlinePushInfo.signalInfo	否	string	信令推送扩展信息。
ex	否	string	消息扩展字段。

响应

请求被 OpenIM 正常处理时通常返回 200 OK。业务是否成功以响应体中的 errCode 为准；errCode === 0 表示成功，非 0 表示业务错误。

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "results": [
      {
        "serverMsgID": "server_msg_001",
        "clientMsgID": "client_msg_001",
        "sendTime": 1719800000000,
        "recvID": "user_001"
      }
    ],
    "failedUserIDs": [
      "user_002"
    ]
  }
}

响应参数

参数名	类型	说明
errCode	int	业务错误码，0 表示成功。
errMsg	string	错误简要信息，成功时通常为空。
errDlt	string	错误详细信息，成功时通常为空。
data	object	接口返回数据。
data.results	array	发送成功的结果列表。
data.results[].serverMsgID	string	服务端消息 ID。
data.results[].clientMsgID	string	客户端消息 ID。
data.results[].sendTime	int	发送时间，Unix 毫秒时间戳。
data.results[].recvID	string	本次发送的接收用户 ID。
data.failedUserIDs	array	发送失败的用户 ID 列表。

发送范围

场景	参数
指定用户	`isSendAll=false`，并传入 `recvIDs`。
全量用户	`isSendAll=true`，服务端分页读取用户并发送。

全量发送适合低频系统通知，不适合高频营销触达。调用方应在业务侧做审批、限流和失败重试策略。

错误

如果请求失败，OpenIM 返回错误对象。更多错误码说明见错误码。

{
  "errCode": 1004,
  "errMsg": "RecordNotFoundError",
  "errDlt": ": [1004]RecordNotFoundError"
}

错误场景	可能原因	处理方式
鉴权失败	`token` 缺失、过期，或调用账号没有该接口权限。	重新获取有效 Token，并在可信后端调用接口。
链路追踪困难	`operationID` 缺失或在大量请求中重复使用。	为每次请求生成独立 `operationID`，并在服务端日志中保留。
参数校验失败	请求体字段类型、必填字段或消息内容结构不符合接口要求。	对照请求体参数表和限制说明检查字段。

权限和限制

向多个用户写入消息，并按消息选项触发推送和会话更新。
必须使用 APP 管理员 Token 调用。
content、contentType 和 sessionType 必填。
isSendAll=true 会遍历全量用户，调用前应评估推送和写入压力。
content 结构必须与 contentType 匹配。

HTTP 请求

请求示例

参数

请求头

请求体

响应

响应参数

发送范围

错误

权限和限制

相关页面