Skip to content

好友/私聊 API ​

私聊消息相关的 API 操作,包括私聊消息发送、消息管理等功能。

权限要求

需要机器人拥有私聊权限和相应的 Intent 配置

📱 私聊消息管理 ​

发送私聊消息 ​

向指定用户发送私聊消息。

方法名: bot.user(userId).send(message, source?, options?) / bot.sendPrivateMessage(userId, message, source?, options?)

参数:

参数名类型必填描述
userIdstring✅用户 ID
messageSendable✅消息内容
sourceQuotable❌引用消息
optionsSendOptions❌msgSeq 指定消息序号,timeout 设置发送超时,isWakeup 发送互动召回消息;详见发送选项
typescript
await bot.user(user_id).send('Hello!')

await bot.sendPrivateMessage(user_id, 'Hello, World!')

// 发送富媒体消息
import { segment } from 'qq-official-bot'
await bot.messageService.sendPrivateMessage(user_id, [
    segment.text('这是一张图片:'),
    segment.image('https://example.com/image.jpg')
])

// 被动回复私聊消息(source 为 Quotable:id 为 msg_id,或 event_id,二选一)
await bot.messageService.sendPrivateMessage(user_id, '这是回复', {
    id: original_message_id
})

// 发送结果包含平台时间与引用索引,可用于之后引用机器人自己的消息
const result = await bot.sendPrivateMessage(user_id, 'Hello')
console.log(result.timestamp, result.ref_idx)

互动召回消息 ​

用户与机器人互动后 30 天内,机器人可向该用户下发一条召回消息。isWakeup 与被动回复互斥,开启后 SDK 不会携带 msg_id / event_id;仅单聊可用。

typescript
await bot.sendPrivateMessage(user_id, '好久不见,来看看新功能吧', undefined, { isWakeup: true })

输入中状态 ​

在被动回复窗口内展示「对方正在输入」(msg_type=6),持续 1-60 秒:

typescript
bot.on('message.private.friend', async (event) => {
    await event.inputNotify(15)        // 等价于 bot.user(event.user_id).sendInputNotify(15, event)
    const answer = await generate(event.raw_message)
    await event.reply(answer)
})

图文卡片 ​

单聊可用 segment.card({ title, description, url, pic_url }) 发送图文卡片,详见图文卡片。

撤回私聊消息 ​

撤回指定的私聊消息。

方法名: bot.messageService.recallPrivateMessage(userId, messageId) / bot.recallPrivateMessage(userId, messageId)

参数:

参数名类型必填描述
userIdstring✅用户 ID
messageIdstring✅消息 ID
typescript
// 使用服务模块(推荐)
const result = await bot.messageService.recallPrivateMessage(user_id, message_id)
if (result.success) {
    console.log('私聊消息撤回成功')
}

// 使用传统方法(向后兼容)
const success = await bot.recallPrivateMessage(user_id, message_id)

流式发送私聊消息 ​

仅单聊可用,群聊不支持。每个分片共用 stream_msg_id,index 从 0 递增;首片由服务端返回 id,后续分片必须带上。

官方文档:流式发送单聊消息

方法名: bot.createPrivateStream(userId, options?) / bot.sendPrivateStream(userId, chunks, options?) / bot.sendPrivateStreamMessage(userId, payload)

typescript
bot.on('message.private', async (event) => {
    const stream = event.replyStream({
        contentType: 'markdown',
        inputMode: 'replace',
    })

    await stream.write('正在生成回答,请稍候')
    await stream.write('。目前已完成大部分内容')
    await stream.end(',以下是最终结果。')
})

// 直接消费 LLM token 流
await bot.sendPrivateStream(user_id, tokenIterator, {
    source: event,
    contentType: 'markdown',
    inputMode: 'replace',
})

replace 模式下 SDK 会把已下发前缀拼成全文再发,满足官方「须以上游已下发前缀开头」的约束。append 则每次只下发本次新增文本。

底层也可自己控分片:

typescript
const first = await bot.sendPrivateStreamMessage(user_id, {
    input_mode: 'replace',
    input_state: 1,
    index: 0,
    content_type: 'markdown',
    content_raw: '正在生成回答,请稍候',
    msg_id: event.id,
    msg_seq: 1,
})

await bot.sendPrivateStreamMessage(user_id, {
    input_mode: 'replace',
    input_state: 10,
    index: 1,
    content_type: 'markdown',
    content_raw: '正在生成回答,请稍候。目前已完成全部内容。',
    msg_id: event.id,
    stream_msg_id: first.id,
    msg_seq: 1,
})
字段说明
input_modeappend(默认)拼接增量;replace 下发当前全文
input_state1 生成中,10 生成结束
content_typetext 或 markdown
is_wakeuptrue 时不校验 msg_id / event_id 有效期

🎯 私聊消息类型 ​

文本消息 ​

typescript
// 纯文本
await bot.messageService.sendPrivateMessage(user_id, 'Hello World!')

// 带格式文本
await bot.messageService.sendPrivateMessage(user_id, '**粗体** 和 *斜体* 文本')

富媒体消息 ​

typescript
import { segment } from 'qq-official-bot'

// 图片消息
await bot.messageService.sendPrivateMessage(user_id, 
    segment.image('https://example.com/image.jpg')
)

// 语音消息
await bot.messageService.sendPrivateMessage(user_id,
    segment.record('https://example.com/audio.mp3')
)

// 视频消息
await bot.messageService.sendPrivateMessage(user_id,
    segment.video('https://example.com/video.mp4')
)

// 混合消息
await bot.messageService.sendPrivateMessage(user_id, [
    segment.text('用户资料:'),
    segment.image('https://example.com/avatar.jpg'),
    segment.text('\n欢迎使用我们的服务!')
])

卡片消息 ​

typescript
// Ark 消息(JSON 卡片)
await bot.messageService.sendPrivateMessage(user_id, {
    ark: {
        template_id: 23,
        kv: [
            { key: 'title', value: '卡片标题' },
            { key: 'desc', value: '卡片描述' },
            { key: 'img', value: 'https://example.com/image.jpg' }
        ]
    }
})

// Embed 消息
await bot.messageService.sendPrivateMessage(user_id, {
    embed: {
        title: '嵌入消息标题',
        description: '这是一条嵌入消息',
        color: 0xFF0000,
        fields: [
            { name: '字段1', value: '值1' },
            { name: '字段2', value: '值2' }
        ]
    }
})

🔗 事件处理 ​

监听私聊事件 ​

typescript
// 监听私聊消息
bot.on('message.private', async (event) => {
    console.log('收到私聊:', event.raw_message)
    console.log('发送者:', event.sender.user_name)
    console.log('用户 ID:', event.user_id)
    console.log('头像:', event.sender.avatar) // 2026-11-16 起单聊事件携带昵称与头像
    console.log('消息类型:', event.content_type) // 0 文本,3 卡片,101 并行消息,102 聊天记录,103 引用
    console.log('引用索引:', event.msg_idx)      // 用于引用回复与去重
    
    // 自动回复
    await event.reply('收到你的私聊了!')
})

// 监听好友消息
bot.on('message.private.friend', async (event) => {
    console.log('收到好友消息:', event.raw_message)
    await event.reply('Hello, my friend!')
})

好友与订阅事件 ​

typescript
// 添加好友:scene 为加好友场景值,scene_param 为分享链接的 callback_data
bot.on('notice.friend.increase', (event) => {
    console.log(event.user_id, event.scene, event.scene_param, event.time)
})

// 订阅消息授权状态变更(SUBSCRIBE_MESSAGE_STATUS)
bot.on('notice.friend.subscribe', (event) => {
    for (const item of event.allowed) {
        console.log('允许订阅', item.template_id, item.subscribe_id)
    }
    console.log('拒绝订阅', event.refused.map(item => item.template_id))
})

私聊消息过滤 ​

typescript
// 只处理特定用户的私聊
bot.on('message.private', async (event) => {
    if (event.user_id === target_user_id) {
        await event.reply('这是来自指定用户的私聊')
    }
})

// 过滤机器人消息
bot.on('message.private', async (event) => {
    if (event.sender.user_id === bot.self_id) return // 忽略自己的消息
    
    await event.reply('只回复其他用户的私聊')
})

📊 TypeScript 接口 ​

typescript
// 私聊消息事件接口
interface PrivateMessageEvent extends Message {
    message_type: 'private'
    sub_type: 'friend' | 'temp' | 'direct'
    user_id: string
    sender: {
        user_id: string
        user_name: string
        permissions: string[]
    }
    
    // 方法
    reply(message: Sendable): Promise<any>
    recall(): Promise<boolean>
}

// 服务方法返回类型
interface ApiResponse<T> {
    success: boolean
    data?: T
    error?: {
        code: number
        message: string
    }
}

⚠️ 注意事项 ​

  1. 权限要求: 发送私聊需要相应的 Intent 权限配置
  2. 频率限制: 私聊有发送频率限制,请合理控制发送速度
  3. 消息类型: 不同平台支持的私聊消息类型可能有差异
  4. 用户关系: 某些情况下需要先建立好友关系才能发送私聊
  5. 机器人限制: 部分机器人类型可能无法主动发起私聊
  6. 消息长度: 私聊消息有长度限制,超长消息会被截断

📚 相关链接 ​