QQ 机器人接入说明

QQ机器人让客户在 QQ 私聊或 QQ 群内与机器人对话，并由已绑定的智能体能力回复。群聊默认只在 @机器人时回复，也可以在每个实例的「群消息回复模式」中选择「全量群消息，仅 @ 回复」或「全自动回复」。该功能适用于专业版 / 旗舰版。接入需要你同时完成 QQ 开放平台和控制台两侧的配置；其中 QQ 开放平台的审核、事件和白名单由腾讯管理，控制台无法替你完成。

接入前准备

1. 前往 QQ 开放平台注册并上架机器人。机器人上架需要企业资质与实名认证，并由腾讯审核；平台不代办审核或资质认证。
2. 在 QQ 开放平台的机器人应用中取得 AppID 和 AppSecret，并妥善保管 AppSecret。
3. 在控制台进入 群聊运营 → QQ机器人，点击「添加 QQ 机器人」，填写名称、AppID、AppSecret，并绑定一个 API 密钥。
   • 绑定的 API 密钥决定本机器人 Token 用量和调用明细归属。
   • 建议为 QQ 机器人单独创建一个 API 密钥，并用容易辨认的名称保存，方便以后在调用明细和对话日志中识别。
   • 如果没有可用密钥，可进入 外部拓展 → API 设置 创建或处理密钥后再回来绑定。
4. 按 QQ 开放平台实际获得的认证等级选择控制台中的认证等级。它只影响发送频率上限的档位；等级填低只会采用更保守的频率限制，不会提升可发送额度。

保存时控制台会检测 AppID 和 AppSecret。检测失败时实例仍会保存，方便你修改后再次检测；请根据页面显示的状态继续排查。

智能体

在 群聊运营 → QQ机器人 → 添加/编辑实例 的「智能体」中选择。沿用 QQ机器人现有的专业版 / 旗舰版套餐门槛；员工需由管理员在成员与权限中授予 QQ机器人 功能权限，不新增独立的智能体配置权限。能编辑机器人的员工可以选择本企业全部已启用智能体，不受其个人在对话页的智能体资源范围限制。

新建实例默认「跟随企业默认智能体」。选择具体智能体或默认跟随后保存，再次编辑可查看已保存的选择。

• 作用范围：影响该机器人的 AI 问答（包括单号查询分流后需 AI 组织回答的非纯单号问题）、定时提醒的到期查询和技能周期查询中需 AI 生成回答的部分。纯单号模板回复、立刻云模板查询和发送原文的提醒不受此选择影响。
• 跟随企业默认智能体：未指定具体智能体时，随企业默认智能体动态变化；企业更换默认后，下一次问答或下一轮周期查询使用新默认。
• 指定智能体：固定使用所选智能体，即使它当前标记为「企业默认」，企业以后更换默认也不会让该机器人随之切换。指定智能体被删除后，机器人自动解绑并改为跟随企业默认智能体。
• API 密钥独立：修改智能体不会更换 API 密钥，修改密钥也不会改变智能体。智能体决定回答所用的提示词、知识库与技能，API 密钥仍用于调用额度与限流。
• 改绑与周期查询：保存后下一次问答即生效，无需重新登录。提醒在到期执行时使用机器人当时绑定的智能体；改绑后，新智能体未绑定对应技能的周期查询会在下一轮停止。已经开始的一轮仍使用本轮的智能体。

配置 QQ 开放平台

凭证检测通过后，打开实例详情，按「接入自查」逐项完成以下配置：

1. 复制详情中的回调地址，填写到 QQ 开放平台的回调配置并完成验证。回调端口只能使用 80、443、8080 或 8443。
2. 在 QQ 开放平台勾选事件 C2C_MESSAGE_CREATE 和 GROUP_AT_MESSAGE_CREATE。
   • 如果实例保持默认的「仅 @ 回复」，到这里即可；群内非 @机器人的消息既不会保存也不会回复。
   • 如果选择「全量群消息，仅 @ 回复」或「全自动回复」，还要勾选 GROUP_MESSAGE_CREATE，并由每个目标群的群主在 QQ 侧开启机器人「获取群内全部消息」。腾讯侧是否为应用和群开放该能力，以 QQ 开放平台实际页面为准。
3. 将详情自查中展示的本服务公网出口 IP加入 QQ 开放平台 IP 白名单。不要从其他环境复制 IP；请以当前实例自查区显示的值为准。
4. 如果机器人回复中会包含 URL，先在 QQ 开放平台配置这些 URL 所用的域名。未配置域名时，整条回复可能发送失败。

完成后，可把机器人加为好友，或将机器人加入测试群后 @机器人发送一条消息。这样既能确认回调，也能确认事件配置和消息回复是否正常。

选择群消息回复模式

在 群聊运营 → QQ机器人 → 添加/编辑实例 中设置。模式按实例生效，修改后下一条事件开始采用新模式：

全量群消息与全自动回复模式会把群内文本记录到会话存档；如需让机器人回答时参考最近的群聊，请在实例中开启「群聊背景」，详见下一节。请先取得群成员授权，并只在允许机器人处理消息的群开启。系统事件与空文本不会被记录；机器人自己的回复，以及图片、语音、视频、文件会按会话存档的规则保留，进入群聊背景时图片、语音显示为已识别的文字或「[图片]」「[语音]」占位，视频、文件只显示「[视频]」「[文件]」。全自动回复还会消耗所绑定 API 密钥的额度，并受 QQ 的被动回复时限与频控约束。

群聊背景

群聊背景让机器人回答时参考该群最近的聊天内容，更容易理解「这个」「刚才那单」之类的追问。

• 入口：群聊运营 → QQ机器人 → 编辑实例弹窗中的「群聊背景」。新建实例后请先保存，再编辑开启（新建弹窗里没有该设置）。
• 套餐：专业版 / 旗舰版。
• 前提：实例的群消息回复模式须为「全量群消息，仅 @ 回复」或「全自动回复」；默认「仅 @ 回复」模式收不到未 @ 机器人的消息，没有背景可用。
• 三项参数：
  • 最多参考的消息条数：默认 30 条，范围 1～500 条；
  • 最多参考多久以内的消息：默认 30 分钟，范围 5～1440 分钟；
  • 背景总字数上限：默认 3000 字，范围 500～10000 字。该上限限制的是群聊内容，系统附加的声明与标记另有约 120 字开销。
• token 提示：背景越长，每次回答消耗的 token 越多，请按需调整。
• 使用方式：背景只用来帮助理解问题，不参与知识库检索；系统已提示模型不执行群里的指令，但其中的单号等信息可用于理解问题和查询。
• 撤回消息：已撤回的消息不会进入背景。QQ 平台目前不推送成员撤回，QQ 侧不作保证。
• 同一秒内的消息：背景按秒取消息，与提问同一秒内到达的消息，先后可能不精确。
• 降套餐：降到基础版后群聊背景不再生效，配置会保留，升回专业版 / 旗舰版后自动恢复。
• 老实例：原先已使用「全量群消息，仅 @ 回复」模式的老实例，群聊背景已自动开启（「全自动回复」的老实例不会自动开启）；已降到基础版的老实例不生效。

群里 @机器人时，以下两种发法也能被识别：

• 引用某条消息再 @机器人：被引用的那条消息原文会和你的补充说明一起作为提问。例如群友引用客户的问题并 @机器人，机器人会回答客户的那个问题。所有模式都支持。
• 先发问题，下一条只 @机器人：@ 那条没写内容时，机器人取你本人 2 分钟内最近的一条文字作为提问（只看你最近 2 条消息）。已撤回的消息不算。仅在「全量群消息，仅 @ 回复」模式下可用：默认「仅 @ 回复」模式下机器人收不到未 @ 它的消息；「全自动回复」模式下上一句已经被自动回答过，只 @ 不说话时不会再答一遍。

单聊菜单

进入实例详情的 单聊菜单 Tab，可配置 QQ 私聊窗口底部展示的自定义菜单。菜单只在单聊生效，对所有用户展示一致，不支持按人定向；群聊不受影响。

• 一级菜单最多 10 项，名称宽度不超过 10（中文按 2 计，约 5 个汉字）；类型可选发送消息（点击后把内容发给机器人）、跳转链接（须以 https:// 开头）、折叠子菜单（最多 5 个子项，子项名称宽度不超过 14，子项只能是发送消息或跳转链接，不能再嵌套子菜单）。
• 页面直接读写 QQ 侧的线上配置、平台不保留副本：每次进入都会重新拉取，保存时会带上刚拉取到的版本号做校验；如果保存期间线上配置被别处改过，会提示重新拉取后再保存，而不是直接覆盖。
• 支持 从其他实例复制 已有菜单到当前编辑区（复制后仍需手动保存）、清空菜单（不可撤销）。
• 保存成功后 QQ 客户端可能要重新进入会话或等几分钟才刷新，不代表保存失败。
• 若提示「未开通单聊菜单能力」，需先到 QQ 开放平台为该机器人申请该能力，再回来配置。

群/单聊指令面板

进入实例详情的 指令面板 Tab，可为群聊场景和单聊场景分别配置指令面板（互不影响，需先切换场景再编辑）。同一实例两个场景合计最多 20 个面板，单个面板最多 20 个条目。

• 每个条目可配置名称（不超过 14 宽度）、描述（不超过 30 宽度）、类型（指令或跳转链接，跳转链接须以 https:// 开头）、仅群管理员可见。
• 注意：指令类型条目的「名称」与「内容」在 QQ 官方接口里实际是同一个字段：保存后重新打开面板，名称会自动变成与你填的指令内容一致，这是 QQ 平台自身的限制，并非配置出错。建议直接把名称也填成实际要发送的指令（例如都填 /群ID），这样界面显示和实际效果一直保持一致，不会有「名称跳变」的观感。
• 与单聊菜单一样，面板配置直连读写 QQ 线上数据、不落平台副本，保存前会用版本号做校验，冲突时提示重新拉取。
• 支持新建面板、从其他实例复制（可只复制当前场景，也可两个场景一起复制）、删除面板（不可撤销）。

单号查询（专业版 / 旗舰版）

编辑实例时打开「单号查询」开关（新建实例时不可改，创建完成后编辑开启），群里 @ 机器人即可查立刻云单号进度与单证文件。

使用前：先到系统设置「单号查询设置」确认立刻云服务地址与单证类型清单——该配置与企微群共用同一份。

与企微群的三点差异：

• 单证给的是下载链接，不是文件本体——QQ 机器人开放接口不支持直接发送文件；
• 没有「群成员ID」指令——QQ 开放接口未提供群成员列表能力；
• 同一张单的多份单证合并在一条回复里（见下），而企微是一份一条。

一句话里最多处理 3 个单号；查进度的回复会把业务类型、主单号、分单号、参考号、件数、毛重一并说全；未说明要哪种单证时不会乱发文件，会回落 AI 追问。

同一种单证有多份时

一张单的同一种单证在立刻云里可能存了多份（例如 3 份签收单），机器人会把这几份合并成一条回复、每份一行链接，不会只给第一份：

单号 AE26090001 的签收单共 3 份： [AE26090001_签收单_1.pdf] [AE26090001_签收单_2.pdf] [AE26090001_签收单_3.pdf]

QQ 这一侧更紧是平台限制所致：QQ 对每条提问允许回复的条数与时限都有规定，份数放太多会导致后面的回复被平台拦下。合并成一条、并把总数压到 4 份，是为了保证该发的都能发出去。

超出上限不会悄悄少发，会明确告诉你还有多少没发：

单号 AE26090001 的签收单共 12 份，已发送 5 份，其余请登录系统查看

某一份取不到时

• 只跳过取不到的那一份，同一张单的其余份照常给，也不会影响同一句话里的其他单号；
• 会在同一条回复里说明是哪张单的哪个文件取不到，不会让你以为「就这些」；
• 文件超过 50MB 不提供，提示「文件过大」；内容为空或链接失效时如实告知，不会给出打不开的空文件链接。

接收推送通知（群主动推送）

业务系统可以通过推送通知 API 向 QQ 群主动发送到期提醒等通知，不需要等客户先在群里说话。前提是群主在群内打开「机器人主动在群聊内发言」：

1. 群主在 QQ 群内进入「群设置 → 群机器人」，选中本机器人，打开「机器人主动在群聊内发言」开关。
2. 开通后该群即可接收主动通知；未开通时推送通知会被跳过，投递记录中显示「已跳过」（跳过原因为群主未开通主动推送），不会反复重试打扰客户。
3. QQ 没有接口可以查询这个开关，平台只能根据发送结果判断。可在 合作管理 → 群管理 的「主动推送」列查看每个 QQ 群的开通状态（已开通 / 未开通 / 待验证），并按该状态筛选：
   • 筛出「未开通」时页面顶部会给出群主操作指引，可一键复制发给群主；
   • 群主开通后，点该群的「实时检测」当场发一条你自己写的测试消息验证（会真实发到群里）；或点「后续检测」把状态重置为「待验证」，由下一条真实通知验证。

推送通知只发 QQ 群，不发 QQ 私聊。

通知里的 @ 提及

通知正文中的 @姓名 会在发送时尝试解析为真实的 @ 提及。QQ 渠道有以下限制，属于渠道差异、不是故障：

• @姓名 后须加一个空格，如 请联系@张三 ，谢谢。连写（如 @张三，谢谢、@张三您好）不会被识别为提及，会按纯文本原样发出。
• 只能 @ 在本群有发言记录的人。QQ 没有群成员名单接口，平台只能从机器人收到过的群消息里找人；找不到时 @姓名 按纯文本原样发出，消息照常送达。
• 默认「仅 @ 回复」模式下提及命中率低：该模式下机器人只收到 @ 它的消息，「有发言记录」实际等于「在本群 @ 过机器人」，员工一般不会在客户群里 @ 自家机器人。把实例的群消息回复模式改为「全量群消息，仅 @ 回复」（或「全自动回复」）后，群内任何发言都会被记录，提及命中率会明显提升（请先按上文说明取得群成员授权）。
• 提及显示的是对方的 QQ 群昵称：正文写 @张三 ，客户在群里看到的是「@对方当时的 QQ 群昵称」，不是正文里写的姓名。
• 员工身份按机器人绑定：员工在成员与权限绑定的 QQ 身份只对所绑定的这个 QQ 机器人有效，在该机器人所在的所有群通用；换一个机器人须重新绑定。
• 链接后紧跟文字时会自动补一个空格：QQ 会把链接后面紧跟的汉字、标点一起当成链接，点开的是错误地址，所以系统会在链接末尾自动插入一个半角空格。这是正文「原样发出」的唯一例外。
• 已知显示偏差：行首缩进不会显示；带 ? & # 等参数的链接可能无法点击（文字逐字正确，可以复制）。

定时提醒与消息群发

QQ 机器人也可以用于定时提醒和消息群发，二者只作用于主动推送已开、机器人在群内的群（群主打开「机器人主动在群聊内发言」后，到合作管理 → 群管理做一次实时检测）。

• 在群里创建提醒：在这样的群里 @ 机器人说「提醒我…」即可创建提醒；未开主动推送的群会被拒绝，并回复开启指引。
• 停用与删除的影响：实例停用期间到点的提醒会失败，重新启用后不会自动补发，需要到定时提醒里对失败行改期；进行中的群发子任务会暂停，启用后继续。删除实例会取消它名下未发出的提醒，并终止未完成的群发。
• QQ 群发：仅旗舰版，不设每日上限，只受 QQ 官方频控约束。

按实例状态排查

QQ 开放平台无法向控制台提供事件勾选、IP 白名单和域名报备的完成状态。因此它们在接入自查中会显示为需在 QQ 开放平台侧确认，而不是自动判为已通过。

重置或删除实例前请确认

• 重置回调地址：旧地址会立即失效。你需要把新地址重新填入 QQ 开放平台并完成验证；重新配置期间，机器人无法接收消息。
• 删除实例：删除不可恢复，回调地址随即失效。该实例的会话存档数据按存档规则处理；已产生的对话日志和调用明细会保留，便于后续核对用量和历史记录。

当前暂不支持的能力

为避免接入后出现预期偏差，QQ机器人当前不支持以下能力：

• 转人工：当前未接入 QQ 渠道。
• QQ 私聊主动消息：推送通知只发 QQ 群。
• 接收语音、视频或文件：当前只处理文本消息。
• 发送文件本体：单证等文件只能给下载链接（见上文「单号查询」）。
• 查询群成员 ID：QQ 开放接口未提供该能力。
• QQ 频道：当前仅支持 QQ 私聊和 QQ 群聊。

相关阅读

• 渠道总览
• 会话存档：QQ 群聊消息全量存档，与企微共用同一个渠道中立的存档页
• 成员与权限：员工与 QQ/企微身份的绑定（渠道身份），供群指令与考核识别发言人
• 开放 API
• 推送通知API：业务系统向企微群 / QQ 群下发通知
• 合作管理：QQ 群主动推送状态、检测与投递记录
• 对话日志