发送系统通知给一批用户
接口说明
发送系统通知给一批用户；落库、离线补发、多端同步，客户端展示为“系统通知”会话。
| 项目 | 值 |
|---|---|
| 操作 ID | message.system.publish |
| 起始版本 | 1.0.0 |
| 幂等 | 否 |
| 回调事件 | message.routed |
| 所属模块 | 消息 |
请求头
| 名称 | 必填 | 说明 | 示例 |
|---|---|---|---|
App-Key | 是 | 应用 AppKey | demo |
Nonce | 是 | 随机串，8-64 字符，5 分钟内不可重复 | 9f2a7c1b |
Timestamp | 是 | epoch 毫秒，允许 ±300000ms | 1750000000000 |
Signature | 是 | hex(sha1(AppSecret + Nonce + Timestamp)) 小写 | 372e885320aabd997aafc5491f9d90fdca94432e |
X-Request-Id | 否 | 可选请求头；缺省或超过 128 字符时由服务端生成，响应原值回声 | req_7f3a9c |
请求体参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
toUserIds | string[] | 是 | 1-1000 个用户 |
content | Content | 是 | type=system，systemType=system_notification|broadcast 等 |
clientMsgId | string | 否 | — |
返回结果
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
code | int | 是 | 0 表示成功；非 0 为错误码，见错误码表 |
msg | string | 否 | 错误信息；成功响应通常不返回 |
data | SystemPublishResult | 是 | 业务数据；成功时返回，结构见下方字段表 |
requestId | string | 是 | 服务端生成的请求 ID，便于排查；与请求头 X-Request-Id 对应 |
data 字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
data.message | Message | 否 | — |
data.deliveredUsers | uint32 | 否 | — |
必填列取自 IDL 的 field.required；未标注的字段按非必填展示。
请求示例
APP_KEY="demo"
APP_SECRET="YOUR_APP_SECRET"
BASE_URL="https://im.example.com"
NONCE="$(openssl rand -hex 16)"
TIMESTAMP="$(date +%s%3N)"
SIGNATURE="$(printf '%s' "$APP_SECRET$NONCE$TIMESTAMP" | openssl sha1 | awk '{print $2}')"
curl -sS -X POST "$BASE_URL/im/v2/message/system/publish" \
-H "Content-Type: application/json" \
-H "App-Key: $APP_KEY" \
-H "Nonce: $NONCE" \
-H "Timestamp: $TIMESTAMP" \
-H "Signature: $SIGNATURE" \
-d '{"toUserIds":["user2"],"content":{"type":"text","text":"你好，IM PaaS"},"clientMsgId":"client_9f2a7c"}'import { createHash, randomBytes } from 'node:crypto';
const APP_KEY = 'demo';
const APP_SECRET = 'YOUR_APP_SECRET';
const BASE_URL = 'https://im.example.com';
const PATH = '/im/v2/message/system/publish';
const nonce = randomBytes(16).toString('hex');
const timestamp = String(Date.now());
const signature = createHash('sha1')
.update(APP_SECRET + nonce + timestamp)
.digest('hex');
const res = await fetch(BASE_URL + PATH, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'App-Key': APP_KEY,
Nonce: nonce,
Timestamp: timestamp,
Signature: signature,
},
body: JSON.stringify({"toUserIds":["user2"],"content":{"type":"text","text":"你好，IM PaaS"},"clientMsgId":"client_9f2a7c"}),
});
const result = await res.json();
if (result.code !== 0) throw new Error(result.code + ': ' + result.msg);
console.log(result.data);返回示例
JSON
{
"code": 0,
"data": {
"message": {
"messageId": "msg_10001",
"clientMsgId": "client_9f2a7c",
"conversationType": 1,
"targetId": "user2",
"channelId": "channel1",
"senderId": "user1",
"seq": 1024,
"timestamp": 1750000000000,
"content": {
"type": "text",
"text": "你好，IM PaaS"
},
"direction": 1
},
"deliveredUsers": 0
},
"requestId": "req_7f3a9c"
}错误码
| 错误码 | 名称 | HTTP 状态 | 说明 | 可重试 | 起始版本 |
|---|---|---|---|---|---|
1001 | INVALID_PARAMETER | 400 | 参数错误 | 否 | 1.0.0 |
1004 | USER_NOT_FOUND | 404 | 用户不存在 | 否 | 1.0.0 |
1007 | MESSAGE_TOO_LARGE | 400 | 消息体过大（上限 5KB） | 否 | 1.0.0 |
1008 | RATE_LIMITED | 429 | 发送过于频繁 | 是 | 1.0.0 |
1021 | SERVICE_NOT_ACTIVATED | 403 | 服务未开通 | 否 | 1.0.0 |