消息进阶

在已发送消息上叠加业务状态：消息扩展（KV，合并/删除语义）、表情回应（reaction）、流式消息（增量文本）与合并转发（本地构造）。四类能力都受单条消息体积与条数限制约束，错误码在页内逐项列出。

接口一览​

本页 13 个操作，其中 13 个在本平台绑定中声明了方法签名。

跨端方法名​

方法名在 GA 平台之间保持一致（规则 A）；Native C ABI 只覆盖部分操作，其余操作以 — 标注。

updateMessageExpansion​

更新已发送消息的扩展 KV（合并语义）。仅单聊/群聊/超级群支持，且消息须在发送时开启可扩展；单次 ≤20 对、单条 ≤300 对，key 1-32 字符 [A-Za-z0-9+=_-]、value ≤4096。

const res = await client.updateMessageExpansion('m_10001', { k1: 'v1', k2: 'v2' });
if (res.code !== 0) throw new Error(res.msg);
const data = res.data;

getMessageExpansion​

读取已发送消息的扩展 KV（IDL rev19；客户端 REST `GET /api/apps/{appkey}/messages/{messageId}/expansion`），返回 `{messageId, expansion}`；无扩展/已全部删除时 expansion 为空 map。仅会话参与者可读（非参与者 1003）；未知消息 1001；单聊对端用户不存在 1004、群不存在 1005、聊天室消息 1012。只读、幂等、不触发事件（写入仍由 updateMessageExpansion / removeMessageExpansion 完成）。

const res = await client.getMessageExpansion('m_10001');
if (res.code !== 0) throw new Error(res.msg);
const data = res.data;

removeMessageExpansion​

删除消息扩展 KV（按 key）。语义与融云 removeMessageExpansion 对齐：消息须可扩展，删除不存在的 key 不报错。

const res = await client.removeMessageExpansion('m_10001', ['k1']);
if (res.code !== 0) throw new Error(res.msg);
const data = res.data;

addMessageReaction​

为指定消息添加回应（reactionId 由业务定义，1-16 字符；同一用户对同一消息同一 reactionId 重复添加视为幂等）。单条消息最多 50 种回应、每种回应最多 100 个用户。

const res = await client.addMessageReaction(ConversationType.PRIVATE, 'user2', 'm_10001', 'like');
if (res.code !== 0) throw new Error(res.msg);
const data = res.data;

removeMessageReaction​

移除自己对指定消息的回应；reactionId 须与添加时一致，未添加过时返回成功（removed=false）。

const res = await client.removeMessageReaction(ConversationType.PRIVATE, 'user2', 'm_10001', 'like');
if (res.code !== 0) throw new Error(res.msg);
const data = res.data;

batchGetMessageReactionSummaries​

批量查询消息回应摘要（1-100 个 messageId）。返回按 messageId 分组：每个回应含总数、当前用户是否已回应、最近参与用户（最多 10 个）；不存在回应的消息返回空数组。

const res = await client.batchGetMessageReactionSummaries(ConversationType.PRIVATE, 'user2', ['m_10001']);
if (res.code !== 0) throw new Error(res.msg);
const data = res.data;

getMessageReactions​

分页查询指定消息的回应列表（count 1-50，默认 20；pageToken 不透明，空串表示第一页）。

const res = await client.getMessageReactions(ConversationType.PRIVATE, 'user2', 'm_10001');
if (res.code !== 0) throw new Error(res.msg);
const data = res.data;

getMessageReactionUsers​

分页查询某个回应的参与用户（count 1-50，默认 20；pageToken 不透明）。

const res = await client.getMessageReactionUsers(ConversationType.PRIVATE, 'user2', 'm_10001', 'like');
if (res.code !== 0) throw new Error(res.msg);
const data = res.data;

startStreamMessage​

开始一条流式消息（IDL rev17；客户端 REST `POST /api/apps/{appkey}/messages/stream/start`）。发送者取自用户 token；`content.text` 作为初始文本。返回 StreamMessage（streamId/messageId/status='streaming'/createdAt/text/segments），SDK 本地保留一个可增量渲染的流式占位消息。支持单聊（1）、群聊（2）、系统通知（4）；聊天室（3）暂不支持（1001）。

const res = await client.startStreamMessage({ conversationType: ConversationType.PRIVATE, targetId: 'user2' });
if (res.code !== 0) throw new Error(res.msg);
const data = res.data;

appendStreamMessage​

追加一个流式增量（IDL rev17；客户端 REST `POST /api/apps/{appkey}/messages/stream/append`），返回累计文本/分段/状态的 StreamMessage；服务端同时向会话全部在线参与者广播 `stream_changed`（complete=false）。`seq` 重复时覆盖该段（乱序安全）。仅流发送者可调用（其他人 1003）；流不存在 1001、已结束 1001。

const res = await client.appendStreamMessage('st_10001', '新的增量文本');
if (res.code !== 0) throw new Error(res.msg);
const data = res.data;

completeStreamMessage​

结束流式消息（IDL rev17；客户端 REST `POST /api/apps/{appkey}/messages/stream/end`）：累计文本按 start 预分配的 messageId 落库为一条普通文本消息（恰一次），随后广播 `stream_changed`（complete=true）。返回 {streamId,messageId,text,status,complete,message?}。仅流发送者可调用（1003）；空文本或已结束 1001。

const res = await client.completeStreamMessage('st_10001');
if (res.code !== 0) throw new Error(res.msg);
const data = res.data;

getStreamMessage​

查询流式消息快照（IDL rev17；客户端 REST `GET /api/apps/{appkey}/messages/stream/{streamId}`），与 append 响应同形（StreamMessage）。仅会话参与者可见（单聊双方、群成员、聊天室在线成员；其他人 1003）；未知流 1001。

const res = await client.getStreamMessage('st_10001');
if (res.code !== 0) throw new Error(res.msg);
const data = res.data;

combineMessages​

本地构造合并转发内容（IDL rev19，transport=local，不做网络 IO）：把 Message[] 转换为 `{type:'combine', title, items:[{senderId,senderName?,contentType,text?,timestamp?}]}`（`CombineContent`），随后直接 `sendMessage(conversationType, targetId, content)`。items 必须 1..=100（本地 1001）；title <=64 字（缺省 ` 条聊天记录`）；条目 text 按 textMaxChars（缺省 300）截断、全部条目合计 <=16KB；构造结果序列化后仍受 `limits.messageBytes`（5KB）约束，发送时超限为 1007。

const res = await client.combineMessages([message]);
if (res.code !== 0) throw new Error(res.msg);
const data = res.data;

相关文档​

• 功能列表：103 个操作与签名
• 状态码：错误码与重试策略
• API 参考：类与成员
• IMLib 集成指南