服务端 API

发送单条消息

使用 发送单条消息 从业务服务端调用 OpenIM 消息 REST 接口，由 APP 管理员模拟指定用户或系统账号向单聊或群聊写入一条消息。这个接口适合系统消息、后台运营消息、客服代发，以及历史消息迁移导入。

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

HTTP 请求

POST {API_ADDRESS}/msg/send_msg

请求示例

curl --request POST "${API_ADDRESS}/msg/send_msg" \
  --header "Content-Type: application/json; charset=utf-8" \
  --header "operationID: ${OPERATION_ID}" \
  --header "token: ${ADMIN_TOKEN}" \
  --data-raw '{
  "sendID": "openIMAdmin",
  "recvID": "user_001",
  "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 服务端，不能下发到客户端或写入前端代码。普通用户聊天消息优先由客户端 SDK 按登录用户身份发送。

参数

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

请求头

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

请求体

{
  "sendID": "openIMAdmin",
  "recvID": "user_001",
  "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": ""
}

参数名	是否必填	类型	说明
recvID	条件	string	单聊接收者用户 ID；`sessionType=1` 时必填。
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": {
    "serverMsgID": "server_msg_001",
    "clientMsgID": "client_msg_001",
    "sendTime": 1719800000000,
    "modify": null
  }
}

响应参数

参数名	类型	说明
errCode	int	业务错误码，0 表示成功。
errMsg	string	错误简要信息，成功时通常为空。
errDlt	string	错误详细信息，成功时通常为空。
data	object	接口返回数据。
data.serverMsgID	string	服务端消息 ID。
data.clientMsgID	string	客户端消息 ID。
data.sendTime	int	消息发送时间，Unix 毫秒时间戳。
data.modify	object	回调或服务端逻辑修改后的消息数据，可能为空。

目标会话

根据发送目标选择会话字段：

场景	sessionType	必填目标
单聊	`1`	`recvID`
群聊	`3`	`groupID`

单聊消息会写入发送者和接收者对应的单聊会话。群聊消息会写入目标群组会话，并按照群成员关系投递。

导入历史消息

迁移历史消息时，可以使用本接口按原发送者写入消息，并通过 sendTime 保留原始发送时间。建议按会话维度从旧到新顺序导入，并在业务侧记录旧消息 ID 与 OpenIM serverMsgID、clientMsgID 的映射，便于重试和排查。

错误

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

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

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

权限和限制

写入消息、更新会话，并按消息选项触发在线推送、离线推送和多端同步。
必须使用 APP 管理员 Token 调用。
content、contentType、sessionType 和发送目标必填。
content 结构必须与 contentType 匹配。
普通用户实时聊天消息优先通过客户端 SDK 发送；本接口更适合服务端管理和导入场景。