发送群组流式消息

大约 7 分钟

发送群组流式消息

功能说明

即时通讯 IM 支持在单聊和群组聊天时发送流式消息。流式消息是一种边生成、边发送、边接收的实时消息传输机制。它将长文本或复杂内容拆分为连续的数据片段，以低延迟、分批次的方式实时推送给接收方，无需等待整个内容完全生成即可开始传输。

目前，即时通讯 IM 仅在 单聊和群组聊天 中支持 文本类型的流式消息，不支持 聊天室。流式消息的典型应用场景如下：

  • AI 对话：大语言模型（LLM）生成较长回复时，可逐段输出与展示，避免用户长时间等待，确保提供更流畅的交互体验。
  • 协同编辑与实时分享：在内容尚未完全构思完成时，即可逐步分享思路或文稿。

流式消息 仅支持通过服务端 API 下发，SDK 负责接收，但不提供发送能力。

使用限制

发送 一条流式消息 时，必须遵守以下规则：

  • 发送间隔：相邻分片的发送间隔不能超过 30 秒，超时则返回错误 14033 并终止流式消息。
  • 发送时长：所有分片的发送总时长不能超过 30 分钟，超时再发送分片则返回错误 14034。
  • 总长度：所有分片的文本内容总长度不能超过 128 KB，超限则返回错误 14032 并终止流式消息。
  • 终止后：流式消息一旦被终止，其后续的所有分片发送请求都将被拒绝。

发送与接收流程

img

调用发送群聊流式消息 API

调用频率上限

100 条/秒/App Key

请求 URL

POST https://{host}/{org_name}/{app_name}/stream_message/chatgroup

关于请求 URL 中的参数说明，详见 请求 URL 参数介绍。

请求示例

例如，一条流式消息包含两个消息分片，各分片的请求示例如下。

  • 发送首个消息分片：

当发送单片流式消息（即整个消息仅由一个分片组成）时，需传入 finish 参数设为 true，以表示本次传输结束。如有需要，还可同时传入 finishReason 参数，用于说明传输结束的原因。

# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -L 'http://XXXX/XXXX/XXXX/stream_message/chatgroup' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "from": "222",
    "to": "301018534445057",
    "body": {
        "msg": "第一个分片",
        "seq": 0,
        "type": "markdown"
    }
    "ext": {
    }
}'
  • 发送第二个消息分片：
curl -L 'http://XXXX/XXXX/XXXX/stream_message/chatgroup' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "from": "222",
    "to": "301018534445057",
    "body": {
        "msgId": "1499712384170721280",
        "msg": "第二个分片，finish。",
        "seq": 1,
        "finish": true,
        "finishReason": 0,
        "type": "markdown"
    }
}'

请求 header 参数

关于 Content-Type、Accept 和 Authorization 字段的说明，详见 请求 header 参数说明。

请求 body 参数

参数类型是否必需描述
fromString是

提示


- 服务器不会校验该用户 ID 是否存在。即使传入不存在的 ID，消息仍会正常下发。
- 服务器不会检查接收方是否已将发送方加入黑名单，也不会校验发送方是否被禁言。
- 若传入空字符串 ("")，请求将失败。

toString是消息接收方所属群组的 ID。

提示


- 只能传入一个群组 ID，且该群组的成员数量不得超过 200 人。
- 服务器不会校验群组 ID 是否存在。即使传入的群组 ID 不存在，消息仍会正常发送，不会收到错误提示。

bodyJSON是消息内容。字段说明请见下方 body 参数详情。
extJSON否消息扩展字段，可用于传递自定义数据。不允许为 null。服务端会以 首个分片 的 ext 为准，后续分片的该字段会被透传。

请求体中的 body 字段说明详见下表。

参数类型是否必须描述
seqInt是分片序号。流式消息按序拆分为多个分片发送，首个分片序号为 0，后续依次递增，用于将分片合并为原消息。
typeString否文本格式类型，仅首个分片需传入。
- （默认）text：纯文本
- markdown：Markdown 格式
finishBool否标识当前分片是否为最后一个。
- （默认）false：否
- true：是
发送最后一个分片时需设为 true。若消息结束后仍对同一 msgId 发送新分片，将返回错误码 14035。
msgIdString是消息 ID。首次发起流式消息时本字段为空，后续分片需传入首次 API 调用返回的 msgId。
该 ID 对应完整的流式消息，其下的各个分片通过 seq 字段编号区分。
msgString是消息内容。
finishReasonInt否自定义结束原因码，仅当 finish 为 true 时生效。可用于标识消息正常结束、被中止等场景。

响应示例

{
    "path": "/stream_message/chatgroup",
    "uri": "https://a1-qa-hsb.agora.com/113230417254974/moderation/stream_message/chatgroup",
    "timestamp": 1766743799730,
    "organization": "113230417254974",
    "application": "dd7f0328-5f3e-448d-9674-2e0434c5931b",
    "action": "post",
    "data":
    {
        "msgId": "1499712384170721280"
    },
    "duration": 0,
    "applicationName": "moderation"
}

响应 body 字段

如果返回的 HTTP 状态码为 200，表示请求成功，响应包体中的 data 字段如下：

参数类型描述
dataJSON响应内容。
data.msgIdString流式消息的唯一 ID。仅在首次分片请求的响应中返回，后续分片请求需携带此 msgId。

响应体中的其他参数说明如下表所示：

字段类型描述
pathString请求路径，为请求 URL 的一部分，开发者无需关注。
uriString请求 URL。
timestampLongUnix 时间戳，单位为毫秒。
organizationString组织唯一标识，与请求参数 org_name 一致，由环信分配给每个组织。
applicationString应用在环信系统中的唯一标识，由系统自动生成，开发者无需处理。
actionString请求对应的 HTTP 方法。
durationInt请求从发起到响应的总耗时，单位为毫秒。
applicationNameString应用名称，即环信控制台中创建应用时填写的名称，与请求参数 app_name 一致。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 响应状态码 了解可能的原因。

错误码

HTTP 状态码错误提示说明
14001param from can't be emptyfrom 为必填参数，不能为空。
14002param to can't be emptyto 为必填参数，不能为空。
14005param body can't be emptybody 为必填参数，不能为空。
14030param body.seq is illegalbody.seq 参数无效。若未传入或传入值小于 0，会触发此错误。
14031can not find stream message by msgId未找到与传入的 msgId 对应的流式消息。例如，在发送第二个分片时传入了错误或已不存在的 msgId。
14032stream message total length exceeds limit流式消息的总长度超过 128 KB 限制。
14033stream message chunk interval timeout相邻两个分片的发送间隔超过 30 秒。
14034stream message total timeout整条流式消息的发送总时长超过 30 分钟。
14035stream message has already finished流式消息已完成传输。当 finish 已设为 true 后，若再尝试对同一消息发送分片，会触发此错误。
14036stream message from user mismatch当前请求的 from 值与首个分片中传入的值不一致。
14037stream message to mismatch当前请求的 to 值与首个分片中传入的值不一致。
14038stream message chunk seq too small当前分片的 seq 值必须大于上一个分片的 seq。分片序号需连续递增。

其他消息功能

流式消息支持的消息功能如下表所示：

功能是否支持
发送消息是（仅支持通过 RESTful API 发送）
消息漫游是
消息扩展是
定向发送否
消息已读回执否
消息输入状态否
消息回复（Reaction）是
消息置顶是
消息撤回是
消息单向删除是
消息修改是
消息搜索是
会话未读数是
会话最后一条消息是
离线推送是
内容审核否
消息翻译是
发送前回调否
发送后回调否
消息发送成功后在发送方多客户端同步否
发送方和接收方的本地数据库存储
上次编辑于:
环信 IM 文档
© 环信 2026