服务端消息与业务扩展

客户业务服务可以把项目、工作流或智能体的结果送入 IM 会话，复用消息持久化、会话序列与投递能力。接收者点击业务内容时，仍需通过客户系统的业务鉴权。

扩展消息入口

POST /external/message/send 使用服务端 HMAC 签名，接受已注册的 x.* 业务扩展类型，不接收普通 txt 或未注册类型。

以下以已注册的名片类型 x.mixin.card 展示请求结构：

{
  "conversationType": "PRIVATE",
  "fromUserId": 90001,
  "toUserId": 90002,
  "clientMsgId": "demo-card-operation-001",
  "type": "x.mixin.card",
  "content": {
    "userId": "90003",
    "name": "测试联系人"
  },
  "meta": {
    "traceId": "demo-trace-001",
    "businessId": "demo-business-001"
  }
}

这里的账号、动作与追踪 ID 都是演示值。实际发送方和接收方须已同步，且具备对应会话权限。重复请求应复用同一逻辑动作标识，不把示例 ID 作为所有请求的固定值。

字段	含义
conversationType	PRIVATE 或 GROUP
fromUserId	实际授权的 IM 发送用户
toUserId / groupId	单聊目标或群聊目标，按类型填写
type、content	已注册类型与匹配的 JSON 内容
clientMsgId	用于定位和关联同一消息
meta	引用、@、追踪和业务关联等元数据

返回结果用于定位已进入投递链路的消息，不代表对端已读。重试规则见 Server API 鉴权。普通客户端文本聊天见 发送第一条消息。

文件消息

文件消息使用配套文件发送接口，前置条件是文件已由实际发送用户上传，并具有服务端返回的存储标识。调用方不能通过传入任意 URL、MIME 或文件大小替代服务端元数据校验。

上传、短效链接与接收者访问规则见 文件与媒体附件。

智能体与流式回复

智能体消息通过 start → chunk → finish 流式流程逐步呈现回复。客户系统负责模型调用、知识库、工作流与业务决策，IM 负责过程消息呈现与最终消息入库。

流式分片使用稳定流标识与序号；完成后归并为一条正式消息，不把每个字都保存成独立聊天记录。断线恢复应以最终消息历史为依据，不能假设所有临时分片都永久保存。

智能体用户映射、群成员权限和客户端呈现需在交付时一起联调。其他扩展类型先约定注册与渲染规则，再投入使用，见 消息类型与扩展。