文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>即时通信 IM>服务端 API>REST API>消息相关>发送消息>发送 C2C 流式消息

发送 C2C 流式消息

最近更新时间：2026-03-04 10:28:48

我的收藏

本页目录：

功能说明

从一个账号向另一个账号发送 C2C（单聊）流式消息。
流式消息支持实时内容流式传输，适用于 AI 助手回复、大文本传输等场景。
接口支持消息分片，允许内容分多次发送，客户端可以逐步接收。
接口不检查发送者和接收者的好友关系（包括黑名单），也不检查发送者是否被禁言。
流式消息 MsgSeq 字段：该字段由用户在发送消息时指定，可以重复。不由后台生成，也不是全局唯一的。

接口说明

请求URL示例

https://xxxxxx/v4/stream_msg/send_c2c_stream_msg?sdkappid=88888888&identifier=admin&usersig=xxx&random=99999999&contenttype=json

Running Environment

Operating System: Ubuntu 24.04.3 LTS / x86_64
Runtime Version: GNU bash, version 5.2.21(1)-release (x86_64-pc-linux-gnu)

请求参数说明

下表仅列出调用本接口时涉及修改的参数及其说明，更多参数详情请参见 REST API 简介。
参数
说明
xxxxxx
SDKAppID 所在国家/地区对应的专属域名:
中国：console.tim.qq.com
新加坡：adminapisgp.im.qcloud.com
首尔：adminapikr.im.qcloud.com
东京：adminapijpn.im.qcloud.com
法兰克福：adminapiger.im.qcloud.com
硅谷：adminapiusa.im.qcloud.com
雅加达：adminapiidn.im.qcloud.com
v4/stream_msg/send_group_stream_msg
请求接口。
sdkappid
创建应用时即时通信 IM 控制台分配的 json。
identifier
必须为 App 管理员账号，更多详情请参见 App 管理员。
usersig
App 管理员账号生成的签名，具体操作请参见 生成 UserSig。
random
请输入随机的32位无符号整数，取值范围0 - 4294967295。
contenttype
请求格式固定值为 json。

接口请求频率限制

分片间隔限制：每次分片之间的最长间隔不能超过 15 秒，超时后流式消息会自动结束。
体验版和开发版限制日累计发送量：1000条/天。
消息大小 < 128KB。
终止规则：流式消息一旦终止，该流式消息的后续请求将被拒绝。
调用频率：后台接口限制了续流频率为5次/秒。建议使用缓冲逻辑，而非每个字符都立即调用接口，推荐每 200 毫秒调用一次。

请求包示例

发送初始流式消息分片

{
    "SyncOtherMachine": 1,
    "To_Account": "123456789",
    "MsgSeq": 93847636,
    "MsgRandom": 1287657,
    "MsgBody": [
        {
            "MsgType": "TIMStreamElem",
            "MsgContent": {
                "CompatibleText": "当前版本过低，请升级后查看流式消息",
                "Chunks": [
                    {
                        "EventType": "data",
                        "Index": 1,
                        "Markdown": "你好，这是流式消息的第一个分片",
                        "IsLast": false
                    }
                ]
            }
        }
    ],
    "CloudCustomData": "your cloud custom data"
}

继续发送流式消息分片

{
    "SyncOtherMachine": 1,
    "To_Account": "123456789",
    "MsgSeq": 93847636,
    "MsgRandom": 1287657,
    "MsgBody": [
        {
            "MsgType": "TIMStreamElem",
            "MsgContent": {
                "StreamMsgID": "stream_msg_id_from_first_response",
                "Chunks": [
                    {
                        "EventType": "data",
                        "Index": 2,
                        "Markdown": " - 继续的内容",
                        "IsLast": false
                    },
                    {
                        "EventType": "data",
                        "Index": 3,
                        "Markdown": " - 最后一个分片",
                        "IsLast": true
                    }
                ]
            }
        }
    ]
}

请求包字段说明

字段
类型
属性
说明
From_Account
String
选填
消息发送方 UserID（用于指定发送消息方账号）。
To_Account
String
必填
消息接收方 UserID。
MsgSeq
Integer
选填
消息序号（32位无符号整数），由用户指定，用于消息排序和去重。详细规则请看本接口的功能说明。若不填写，后台会自动生成。
MsgRandom
Integer
必填
消息随机数（32位无符号整数），后台用于同一秒内的消息去重。请确保该字段填的是随机数。
SendMsgControl
Array
选填
消息发送控制选项，是一个String数组，只对本条消息有效。
NoUnread表示该条消息不计入未读数。
NoLastMsg 表示该条消息不更新会话列表。
WithMuteNotifications 表示该条消息的接收方对发送方的消息提示音设置生效（默认不生效）。
WithBlackListCheck 表示该条消息检查发送方和接收方黑名单。
WithFriendCheck 表示该条消息检查发送方和接收方好友关系。
WithSpeakingCheck 表示该条消息检查发送方是否被禁言。
MsgBody
Array
必填
消息内容，必须包含 TIMStreamMsgElem 类型的消息元素。
MsgType
String
必填
流式消息必须为 TIMStreamMsgElem。
MsgContent
Object
必填
流式消息内容对象，详见下文 StreamMsgContent 结构。
NeedReadReceipt
Integer
选填
该条消息是否需要已读回执：
0 为不需要。
1 为需要。
默认为 0。
OfflinePushInfo
Object
选填
离线推送信息配置，具体可参考 公共参数（OfflinePushInfo说明）。

StreamMsgContent 字段说明

字段
类型
属性
说明
CompatibleText
String
选填
用于系统兼容，设置提示文本，默认值为“当前版本过低，请升级后查看流式消息”。
StreamMsgID
String
选填
首次流式消息不需要填写此字段，后续续流需要包含此字段（首次响应中返回）。
Chunks
Array
必填
流式消息分片数组，详见下文 StreamChunk 结构。

StreamChunk 字段说明

字段
类型
属性
说明
EventType
String
必填
分片类型：
data ：AI 回复流式内容或普通数据。
Index
Integer
必填
分片索引，从1开始，严格递增。
Markdown
String
必填
流式 Markdown 内容。
IsLast
Boolean
必填
是否为最后一个分片；最后一个分片 IsLast=true。

应答包示例

正常应答(首条消息分片)
{
    "ActionStatus": "OK",
    "ErrorInfo": "",
    "ErrorCode": 0,
    "StreamMsgID": "stream_c2c_1234567890_abcdef",
    "MsgTime": 1672870301,
    "MsgKey": "c2c_msg_key_xxx",      
    "MsgId": "c2c_msg_id_xxx"
}
异常应答
{
    "ActionStatus": "FAIL",
    "ErrorInfo": "流式消息格式错误",
    "ErrorCode": 90300
}

应答包字段说明

字段
类型
说明
ActionStatus
String
请求处理的结果：
OK：处理成功。
FAIL：处理失败。
ErrorCode
Integer
错误码：
0：成功。
非0：失败。
ErrorInfo
String
错误信息。
StreamMsgID
String
流式消息唯一标识，用于续流发送。
MsgTime
Integer
消息时间戳，UNIX 时间戳。
MsgKey
String
消息的唯一键。
MsgId
String
消息 ID。

错误码说明

除非发生网络错误（例如502错误），否则该接口的 HTTP 返回码均为200。真正的错误码、错误信息是通过应答包体中的 ErrorCode、ErrorInfo 来表示的。
公共错误码（60000到79999）参见 错误码 说明文档。本 API 私有错误码如下：
错误码
描述
90300
流式消息格式错误。
90306
StreamMsgID 解析失败。
90308
UserSig 或 A2 无效。
90309
服务器内部错误。
90310
JSON 格式解析失败。
90311
MsgBody 格式错误。
90312
MsgBody 不是数组类型。
90315
请求频率超限。
中国站
目录