消息 API

消息模块覆盖单聊/群/聊天室/系统通知发送、撤回、历史与搜索、已读人数、投递轨迹、扩展 KV、消息修改、回应、模板消息、流式消息、广播与翻译。

模块概览​

项目值
接口数量30
幂等接口2
路径前缀/im/v2
请求方法POST（JSON 请求体）
鉴权方式App-Key / Nonce / Timestamp / Signature（见 鉴权与签名）
响应信封{ code, msg?, data?, requestId? }

接口列表​

接口方法路径说明幂等
以指定用户身份发送单聊消息POST/im/v2/message/private/publish以指定用户身份发送单聊消息；返回服务端消息（含 seq）。幂等键 clientMsgId。否
发送群/超级群消息POST/im/v2/message/group/publish发送群/超级群消息。否
发送聊天室消息POST/im/v2/message/chatroom/publish发送聊天室消息（仅广播在线成员，不落离线）。否
发送系统通知给一批用户POST/im/v2/message/system/publish发送系统通知给一批用户；落库、离线补发、多端同步，客户端展示为“系统通知”会话。否
撤回消息POST/im/v2/message/recall撤回消息（发送者或应用服务器；时限 recallWindowMs，超时 1022）。否
查询历史消息POST/im/v2/message/history/get查询历史消息（倒序分页，beforeSeq 向前翻页）。否
查询消息已读人数POST/im/v2/message/read/count查询消息已读人数。否
按用户搜索文本消息POST/im/v2/message/search按用户搜索文本消息。否
消息投递轨迹POST/im/v2/message/trace/get消息投递轨迹（存储/ACK/离线补偿/回调路由），控制台消息流转查询使用。否
设置消息扩展 KVPOST/im/v2/message/expansion/set设置消息扩展 KV（key/value，随消息存储；用于业务透传/标记/回应数据）。否
读取消息扩展 KVPOST/im/v2/message/expansion/get读取消息扩展 KV。否
删除消息扩展 KVPOST/im/v2/message/expansion/remove删除消息扩展 KV。否
服务端修改消息内容POST/im/v2/message/modify服务端修改消息内容（单聊/群/超级群统一；仅发送者或应用管理员可改）。修改后历史与拉取返回新内容。否
清除远端会话历史消息POST/im/v2/message/history/clean清除远端会话历史消息（beforeTimestamp 省略表示全部；仅应用管理员/会话参与者可调用）。否
添加消息回应POST/im/v2/message/reaction/add添加消息回应（reaction；同一用户同一表情幂等）。是
移除消息回应POST/im/v2/message/reaction/remove移除消息回应。否
查询消息回应汇总POST/im/v2/message/reaction/list查询消息回应汇总（按表情聚合 count/userIds）。否
查询某表情的回应用户列表POST/im/v2/message/reaction/users查询某表情的回应用户列表。否
批量查询多条消息的回应摘要POST/im/v2/message/reaction/batch批量查询多条消息的回应摘要（上限 50）。否
发送模板消息POST/im/v2/message/template/publish发送模板消息：templateId 指向内置模板，params 填充占位符后按普通消息下发（单聊/群/系统通知）。否
开始流式消息POST/im/v2/message/stream/start开始流式消息（大模型输出场景）：创建流并预分配 messageId，后续 append 追加增量。否
向流追加文本增量POST/im/v2/message/stream/append向流追加文本增量（幂等 seq 可选；重复 seq 覆盖）。否
结束流式消息POST/im/v2/message/stream/end结束流式消息：落库为普通消息并按会话下发（返回最终 Message）。否
获取流内容与状态POST/im/v2/message/stream/get获取流内容与状态（覆盖融云 /message/get_stream）。否
发送全量用户落地通知POST/im/v2/message/broadcast发送全量用户落地通知（写入系统会话并下发；支持指定用户子集）。否
撤回全量用户落地通知POST/im/v2/message/broadcast/recall撤回全量用户落地通知。否
发送在线用户广播POST/im/v2/message/online/broadcast发送在线用户广播（仅推给当前在线连接，不落离线历史）。否
文本翻译POST/im/v2/message/translate文本翻译（转发到应用配置的翻译服务；未配置返回 1021）。覆盖融云 /v3/translate。否
分页查询应用历史消息审计记录POST/im/v2/message/history分页查询应用历史消息审计记录（userId/conversationType/targetId/from/to 过滤；page 从 1 开始，size 上限 100）。审计视图由已持久化消息派生，聊天室等 ephemeral 消息不在范围内。否
按时间区间删除历史消息审计记录POST/im/v2/message/history/delete按时间区间删除历史消息审计记录（from/to 至少传一个，epoch 毫秒闭区间；只记录审计删除区间，不清理在线会话消息存储；重叠区间合并）。是

相关回调事件​

接口约定​

  • 完整请求地址 = 部署域名 + /im/v2 + 接口路径；所有接口使用 POST。
  • 请求头必须携带 App-Key / Nonce / Timestamp / Signature；签名规则见鉴权与签名。
  • 响应统一为 { code, msg?, data?, requestId? }；code = 0 表示成功。
  • 列表类接口使用 limit 分页，单页上限见限频与限制。

相关说明​