消息进阶

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

平台调用风格

异步风格：Future<RcResult<T>>；错误码在 res.code，不使用异常表达业务失败。

接口一览​

操作语义传输返回
updateMessageExpansion更新已发送消息的扩展 KV（合并语义）。仅单聊/群聊/超级群支持，且消息须在发送时开启可扩展；单次 ≤20 对、单条 ≤300 对，key 1-32 字符 [A-Za-z0-9+=_-]、value ≤4096。REST（客户端）{messageId:string, expansion:Record<string,string>}
getMessageExpansion读取已发送消息的扩展 KV（IDL rev19；客户端 REST `GET /api/apps/{appkey}/messages/{messageId}/expansion`），返回 `{messageId, expansion}`；无扩展/已全部删除时 expansion 为空 map。仅会话参与者可读（非参与者 1003）；未知消息 1001；单聊对端用户不存在 1004、群不存在 1005、聊天室消息 1012。只读、幂等、不触发事件（写入仍由 updateMessageExpansion / removeMessageExpansion 完成）。REST（客户端）{messageId:string, expansion:Record<string,string>}
removeMessageExpansion删除消息扩展 KV（按 key）。语义与融云 removeMessageExpansion 对齐：消息须可扩展，删除不存在的 key 不报错。REST（客户端）{messageId:string, removed:string[], expansion:Record<string,string>}
addMessageReaction为指定消息添加回应（reactionId 由业务定义，1-16 字符；同一用户对同一消息同一 reactionId 重复添加视为幂等）。单条消息最多 50 种回应、每种回应最多 100 个用户。REST（客户端）{messageId:string, reactionId:string, userId:string, reactionTime:uint64}
removeMessageReaction移除自己对指定消息的回应；reactionId 须与添加时一致，未添加过时返回成功（removed=false）。REST（客户端）{messageId:string, reactionId:string, removed:boolean}
batchGetMessageReactionSummaries批量查询消息回应摘要（1-100 个 messageId）。返回按 messageId 分组：每个回应含总数、当前用户是否已回应、最近参与用户（最多 10 个）；不存在回应的消息返回空数组。REST（客户端）Record<string, ReactionSummary[]>（ReactionSummary={reactionId:string,totalCount:uint32,hasCurrentUserReacted:boolean,reactionTime:uint64,users:{userId:string,reactionTime:uint64}[]}）
getMessageReactions分页查询指定消息的回应列表（count 1-50，默认 20；pageToken 不透明，空串表示第一页）。REST（客户端）{reactions:ReactionSummary[], pageToken?:string, totalCount:uint32}
getMessageReactionUsers分页查询某个回应的参与用户（count 1-50，默认 20；pageToken 不透明）。REST（客户端）{users:{userId:string,reactionTime:uint64}[], pageToken?:string, totalCount:uint32}
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）。REST（客户端）StreamMessage
appendStreamMessage追加一个流式增量（IDL rev17；客户端 REST `POST /api/apps/{appkey}/messages/stream/append`），返回累计文本/分段/状态的 StreamMessage；服务端同时向会话全部在线参与者广播 `stream_changed`（complete=false）。`seq` 重复时覆盖该段（乱序安全）。仅流发送者可调用（其他人 1003）；流不存在 1001、已结束 1001。REST（客户端）StreamMessage
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。REST（客户端）{streamId:string, messageId:string, text:string, status:streaming|ended, complete:bool, message?:Message}
getStreamMessage查询流式消息快照（IDL rev17；客户端 REST `GET /api/apps/{appkey}/messages/stream/{streamId}`），与 append 响应同形（StreamMessage）。仅会话参与者可见（单聊双方、群成员、聊天室在线成员；其他人 1003）；未知流 1001。REST（客户端）StreamMessage
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 字（缺省 `<n> 条聊天记录`）；条目 text 按 textMaxChars（缺省 300）截断、全部条目合计 <=16KB；构造结果序列化后仍受 `limits.messageBytes`（5KB）约束，发送时超限为 1007。本地CombineContent

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

跨端方法名​

操作AndroidWebElectronmacOSFlutterNative (C ABI)iOS
updateMessageExpansionupdateMessageExpansionupdateMessageExpansionupdateMessageExpansionupdateMessageExpansionupdateMessageExpansion—func
getMessageExpansiongetMessageExpansiongetMessageExpansiongetMessageExpansiongetMessageExpansiongetMessageExpansion—func
removeMessageExpansionremoveMessageExpansionremoveMessageExpansionremoveMessageExpansionremoveMessageExpansionremoveMessageExpansion—func
addMessageReactionaddMessageReactionaddMessageReactionaddMessageReactionaddMessageReactionaddMessageReaction—func
removeMessageReactionremoveMessageReactionremoveMessageReactionremoveMessageReactionremoveMessageReactionremoveMessageReaction—func
batchGetMessageReactionSummariesbatchGetMessageReactionSummariesbatchGetMessageReactionSummariesbatchGetMessageReactionSummariesbatchGetMessageReactionSummariesbatchGetMessageReactionSummaries—func
getMessageReactionsgetMessageReactionsgetMessageReactionsgetMessageReactionsgetMessageReactionsgetMessageReactions—func
getMessageReactionUsersgetMessageReactionUsersgetMessageReactionUsersgetMessageReactionUsersgetMessageReactionUsersgetMessageReactionUsers—func
startStreamMessagestartStreamMessagestartStreamMessagestartStreamMessagestartStreamMessagestartStreamMessage—func
appendStreamMessageappendStreamMessageappendStreamMessageappendStreamMessageappendStreamMessageappendStreamMessage—func
completeStreamMessagecompleteStreamMessagecompleteStreamMessagecompleteStreamMessagecompleteStreamMessagecompleteStreamMessage—func
getStreamMessagegetStreamMessagegetStreamMessagegetStreamMessagegetStreamMessagegetStreamMessage—func
combineMessagescombineMessagescombineMessagescombineMessagescombineMessagescombineMessages—func

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

updateMessageExpansion​

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

updateMessageExpansion(String messageId, Map<String, String> expansion)
REST（客户端）since 1.1.0
参数
参数类型说明
messageIdstring必填；消息 ID（服务端生成）
expansionRecord<string,string>必填；字段含义见类型定义
返回

{messageId:string, expansion:Record<string,string>} 成功返回的数据；失败时按错误码处理

示例
Dart
final res = await engine.updateMessageExpansion('m_10001', {'k1': 'v1', 'k2': 'v2'});
if (res.code != 0) throw Exception(res.msg);
错误码
错误码名称分类HTTP可重试说明
1001INVALID_PARAMETER客户端 / 参数 / 权限400否参数错误
1004USER_NOT_FOUND客户端 / 参数 / 权限404否用户不存在
1026MESSAGE_NOT_EXPANDABLE客户端 / 参数 / 权限400否消息不可扩展（发送时未开启可扩展，或会话类型不支持）
1027EXPANSION_LIMIT_EXCEEDED客户端 / 参数 / 权限400否消息扩展超出限制（单次 20 对 / 单条 300 对 / 键值长度）

getMessageExpansion​

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

getMessageExpansion(String messageId)
REST（客户端）幂等since 1.3.0
参数
参数类型说明
messageIdstring必填；消息 ID（服务端生成）
返回

{messageId:string, expansion:Record<string,string>} 成功返回的数据；失败时按错误码处理

示例
Dart
final res = await engine.getMessageExpansion('m_10001');
if (res.code != 0) throw Exception(res.msg);
错误码
错误码名称分类HTTP可重试说明
1001INVALID_PARAMETER客户端 / 参数 / 权限400否参数错误
1003FORBIDDEN客户端 / 参数 / 权限403否无权限
1004USER_NOT_FOUND客户端 / 参数 / 权限404否用户不存在
1005GROUP_NOT_FOUND客户端 / 参数 / 权限404否群组不存在
1012CHATROOM_NOT_FOUND客户端 / 参数 / 权限404否聊天室不存在

removeMessageExpansion​

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

removeMessageExpansion(String messageId, List<String> keys)
REST（客户端）since 1.1.0
参数
参数类型说明
messageIdstring必填；消息 ID（服务端生成）
keysstring[]必填；字段含义见类型定义
返回

{messageId:string, removed:string[], expansion:Record<string,string>} 成功返回的数据；失败时按错误码处理

示例
Dart
final res = await engine.removeMessageExpansion('m_10001', ['k1']);
if (res.code != 0) throw Exception(res.msg);
错误码
错误码名称分类HTTP可重试说明
1001INVALID_PARAMETER客户端 / 参数 / 权限400否参数错误
1004USER_NOT_FOUND客户端 / 参数 / 权限404否用户不存在
1026MESSAGE_NOT_EXPANDABLE客户端 / 参数 / 权限400否消息不可扩展（发送时未开启可扩展，或会话类型不支持）

addMessageReaction​

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

addMessageReaction(int conversationType, String targetId, String messageId, String reactionId)
REST（客户端）since 1.1.0
参数
参数类型说明
conversationTypeConversationType必填；会话类型枚举（ConversationType）
targetIdstring必填；目标会话 ID：单聊为对方 userId，群聊为 groupId，聊天室为 chatroomId
messageIdstring必填；消息 ID（服务端生成）
reactionIdstring必填；字段含义见类型定义
options{pushConfig?:object}可选；选项对象（字段见类型列）：{ pushConfig?:object }
返回

{messageId:string, reactionId:string, userId:string, reactionTime:uint64} 成功返回的数据；失败时按错误码处理

示例
Dart
final res = await engine.addMessageReaction(1, 'user2', 'm_10001', 'like');
if (res.code != 0) throw Exception(res.msg);
错误码
错误码名称分类HTTP可重试说明
1001INVALID_PARAMETER客户端 / 参数 / 权限400否参数错误
1004USER_NOT_FOUND客户端 / 参数 / 权限404否用户不存在
1028REACTION_INVALID客户端 / 参数 / 权限400否回应标识非法（1-16 字符）
1029REACTION_LIMIT_EXCEEDED客户端 / 参数 / 权限400否单条消息回应种类超出上限（50）
1030REACTION_USER_LIMIT_EXCEEDED客户端 / 参数 / 权限400否单个回应参与用户超出上限（100）

removeMessageReaction​

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

removeMessageReaction(int conversationType, String targetId, String messageId, String reactionId)
REST（客户端）since 1.1.0
参数
参数类型说明
conversationTypeConversationType必填；会话类型枚举（ConversationType）
targetIdstring必填；目标会话 ID：单聊为对方 userId，群聊为 groupId，聊天室为 chatroomId
messageIdstring必填；消息 ID（服务端生成）
reactionIdstring必填；字段含义见类型定义
返回

{messageId:string, reactionId:string, removed:boolean} 成功返回的数据；失败时按错误码处理

示例
Dart
final res = await engine.removeMessageReaction(1, 'user2', 'm_10001', 'like');
if (res.code != 0) throw Exception(res.msg);
错误码
错误码名称分类HTTP可重试说明
1001INVALID_PARAMETER客户端 / 参数 / 权限400否参数错误
1004USER_NOT_FOUND客户端 / 参数 / 权限404否用户不存在
1028REACTION_INVALID客户端 / 参数 / 权限400否回应标识非法（1-16 字符）

batchGetMessageReactionSummaries​

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

batchGetMessageReactionSummaries(int conversationType, String targetId, List<String> messageIds)
REST（客户端）since 1.1.0
参数
参数类型说明
conversationTypeConversationType必填；会话类型枚举（ConversationType）
targetIdstring必填；目标会话 ID：单聊为对方 userId，群聊为 groupId，聊天室为 chatroomId
messageIdsstring[]必填；消息 ID 列表
返回

Record<string, ReactionSummary[]>（ReactionSummary={reactionId:string,totalCount:uint32,hasCurrentUserReacted:boolean,reactionTime:uint64,users:{userId:string,reactionTime:uint64}[]}） 成功返回的数据；失败时按错误码处理

示例
Dart
final res = await engine.batchGetMessageReactionSummaries(1, 'user2', ['m_10001']);
if (res.code != 0) throw Exception(res.msg);
错误码
错误码名称分类HTTP可重试说明
1001INVALID_PARAMETER客户端 / 参数 / 权限400否参数错误
1004USER_NOT_FOUND客户端 / 参数 / 权限404否用户不存在

getMessageReactions​

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

getMessageReactions(int conversationType, String targetId, String messageId, {int? count, String? pageToken})
REST（客户端）since 1.1.0
参数
参数类型说明
conversationTypeConversationType必填；会话类型枚举（ConversationType）
targetIdstring必填；目标会话 ID：单聊为对方 userId，群聊为 groupId，聊天室为 chatroomId
messageIdstring必填；消息 ID（服务端生成）
options{count?:uint32, pageToken?:string}可选；选项对象（字段见类型列）：{ count?:uint32, pageToken?:string }
返回

{reactions:ReactionSummary[], pageToken?:string, totalCount:uint32} 成功返回的数据；失败时按错误码处理

示例
Dart
final res = await engine.getMessageReactions(1, 'user2', 'm_10001');
if (res.code != 0) throw Exception(res.msg);
错误码
错误码名称分类HTTP可重试说明
1001INVALID_PARAMETER客户端 / 参数 / 权限400否参数错误
1004USER_NOT_FOUND客户端 / 参数 / 权限404否用户不存在

getMessageReactionUsers​

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

getMessageReactionUsers(int conversationType, String targetId, String messageId, String reactionId, {int? count, String? pageToken})
REST（客户端）since 1.1.0
参数
参数类型说明
conversationTypeConversationType必填；会话类型枚举（ConversationType）
targetIdstring必填；目标会话 ID：单聊为对方 userId，群聊为 groupId，聊天室为 chatroomId
messageIdstring必填；消息 ID（服务端生成）
reactionIdstring必填；字段含义见类型定义
options{count?:uint32, pageToken?:string}可选；选项对象（字段见类型列）：{ count?:uint32, pageToken?:string }
返回

{users:{userId:string,reactionTime:uint64}[], pageToken?:string, totalCount:uint32} 成功返回的数据；失败时按错误码处理

示例
Dart
final res = await engine.getMessageReactionUsers(1, 'user2', 'm_10001', 'like');
if (res.code != 0) throw Exception(res.msg);
错误码
错误码名称分类HTTP可重试说明
1001INVALID_PARAMETER客户端 / 参数 / 权限400否参数错误
1004USER_NOT_FOUND客户端 / 参数 / 权限404否用户不存在
1028REACTION_INVALID客户端 / 参数 / 权限400否回应标识非法（1-16 字符）

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）。

startStreamMessage(int conversationType, String targetId, {StartStreamMessageOptions? options})
REST（客户端）since 1.2.0
参数
参数类型说明
params{conversationType:ConversationType, targetId:string, content?:Content}必填；对象：{ conversationType:ConversationType, targetId:string, content?:Content }
返回

StreamMessage 成功返回的数据；失败时按错误码处理

示例
Dart
final res = await engine.startStreamMessage(1, 'user2');
if (res.code != 0) throw Exception(res.msg);
错误码
错误码名称分类HTTP可重试说明
1001INVALID_PARAMETER客户端 / 参数 / 权限400否参数错误
1004USER_NOT_FOUND客户端 / 参数 / 权限404否用户不存在
1005GROUP_NOT_FOUND客户端 / 参数 / 权限404否群组不存在

appendStreamMessage​

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

appendStreamMessage(String streamId, String delta, {AppendStreamMessageOptions? options})
REST（客户端）since 1.2.0
参数
参数类型说明
streamIdstring必填；字段含义见类型定义
deltastring必填；字段含义见类型定义
options{seq?:uint32}可选；选项对象（字段见类型列）：{ seq?:uint32 }
返回

StreamMessage 成功返回的数据；失败时按错误码处理

示例
Dart
final res = await engine.appendStreamMessage('st_10001', '新的增量文本');
if (res.code != 0) throw Exception(res.msg);
错误码
错误码名称分类HTTP可重试说明
1001INVALID_PARAMETER客户端 / 参数 / 权限400否参数错误
1003FORBIDDEN客户端 / 参数 / 权限403否无权限

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。

completeStreamMessage(String streamId)
REST（客户端）since 1.2.0
参数
参数类型说明
streamIdstring必填；字段含义见类型定义
返回

{streamId:string, messageId:string, text:string, status:streaming|ended, complete:bool, message?:Message} 成功返回的数据；失败时按错误码处理

示例
Dart
final res = await engine.completeStreamMessage('st_10001');
if (res.code != 0) throw Exception(res.msg);
错误码
错误码名称分类HTTP可重试说明
1001INVALID_PARAMETER客户端 / 参数 / 权限400否参数错误
1003FORBIDDEN客户端 / 参数 / 权限403否无权限

getStreamMessage​

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

getStreamMessage(String streamId)
REST（客户端）幂等since 1.2.0
参数
参数类型说明
streamIdstring必填；字段含义见类型定义
返回

StreamMessage 成功返回的数据；失败时按错误码处理

示例
Dart
final res = await engine.getStreamMessage('st_10001');
if (res.code != 0) throw Exception(res.msg);
错误码
错误码名称分类HTTP可重试说明
1001INVALID_PARAMETER客户端 / 参数 / 权限400否参数错误
1003FORBIDDEN客户端 / 参数 / 权限403否无权限

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。

combineMessages(List<Message> messages, {CombineMessagesOptions? options})
本地幂等since 1.3.0
参数
参数类型说明
messagesMessage[]必填；字段含义见类型定义
options{title?:string, senderNames?:Record<string,string>, textMaxChars?:uint32}可选；选项对象（字段见类型列）：{ title?:string, senderNames?:Record, textMaxChars?:uint32 }
返回

CombineContent 成功返回的数据；失败时按错误码处理

示例
Dart
final res = await engine.combineMessages([message]);
if (res.code != 0) throw Exception(res.msg);
错误码
错误码名称分类HTTP可重试说明
1001INVALID_PARAMETER客户端 / 参数 / 权限400否参数错误

相关文档​