# QQ 机器人
# 简介
QQ 机器人通过开放的平台承载机器人的定制化功能，让开发者获得更畅快的开发体验。
# 亮点
便捷：通过开放接口的形式，QQ 开放平台允许开发者进行机器人定制化开发。
高效：提供一套标准化、易接入的API与websocket事件，可以帮助开发者实现机器人的快速开发和迭代。
趣味：机器人创新 C 端交互方式，通过指令的方式承载服务，让多样化服务变得触手可达。
赋能：频道、群、单聊等QQ场景全面打通，深度融入QQ社交生态，用户基础大，服务范围广。
# 接入流程
# 1. 阅读文档
为了更高效的进驻到 QQ 机器人平台，建议先阅读下列文档后再启动进驻工作：
# 2. 企业主体入驻
企业主体入驻开发者默认支持频道、群场景开发能力；个人主体入驻开发者默认仅支持频道场景开发能力。除默认开通的能力外，后续其他接口能力申请上，企业开发者与个人开发者也存在差异。
# 步骤总览
注意
企业入驻需要提供工商信息，包括：营业执照、对公账号，如不具备的用户请前往个人入口进行入驻。 邮箱一旦填写完毕进入激活步骤，则被占用，不可修改，所以选错主体类型的用户需要更换邮箱重新注册。
# 2.1 点击「立即注册」
温馨提示
服务的三个类目，将鼠标放上去，将会有相关应用的文档及对应便捷入口，在注册前可先阅读相关文档。
# 2.2 选择企业
# 2.3 填写邮箱
温馨提示
之前已经注册过的邮箱不需再注册，直接去登陆界面登陆即可。
# 2.4 激活邮箱
温馨提示
如未收到邮件，请检查垃圾箱或者点击重新发送进行尝试。
# 2.5 上传工商信息
温馨提示
请务必确认上传的营业执照与填写的主体信息保持一致，账号注册完毕，后续还存在其他主体认证步骤，信息不一致将会导致后续步骤出现问题。
# 2.6 绑定管理员
温馨提示
姓名和身份证号码务必与手机号码对应运营商实名登记的信息一致，否则会提示错误。
# 2.7 资质审核
- 管理员绑定完成后账号即注册成功，进入应用管理页后，需进行后续企业资质审核步骤。
- 此步骤可与第三步创建应用同步进行，但此步骤需尽快完成，否则会影响应用的提审。
- 入口：点击页面提示条上的「查看详情」，即可进入详情页面查看进度。
# 资质审核详细流程
审核中-资料审核： 注册完成即自动进入工商信息审核，此步骤无需开发者操作，但请随时关注状态变更。
审核中-待打款： 填写银行信息，点击查看详情，进入二级页面填写对公账户的银行信息，如系统没有对应【银行所在地的区】，可选择同市其他区。
审核中-银行打款中： 如银行信息审核无误，则 3 天内腾讯公司将会对填写的对公银行账户进行 1 元以下小额打款，请关注银行收款。
- 打款帐号主体：深圳市腾讯计算机系统有限公司，打款银行账号：755901658210820。
审核中-校验金额： 收到打款后，请在规定时间内于开发者管理端回填收到的打款金额进行验证。
- 金额校验次数有限，请确认收到打款后进入二级页面，填写具体的金额，如次数用完且校验不通过，该账号将被冻结。
# 3 个人主体入驻
企业主体入驻开发者默认支持频道、群场景开发能力；个人主体入驻开发者默认仅支持频道场景开发能力。除默认开通的能力外，后续其他接口能力申请上，企业开发者与个人开发者也存在差异。
# 步骤总览
# 3.1 点击「立即注册」
温馨提示
服务的三个类目，将鼠标放上去，将会有相关应用的文档及对应便捷入口，在注册前可先阅读相关文档。
# 3.2 选择个人
# 3.3 填写邮箱
温馨提示
之前已经注册过的邮箱不需再注册，直接去登陆界面登陆即可。
# 3.4 激活邮箱
温馨提示
如未收到邮件，请检查垃圾箱或者点击重新发送进行尝试。
# 3.6 绑定管理员
温馨提示
姓名和身份证号码务必与手机号码对应运营商实名登记的信息一致，否则会提示错误。
绑定成功即可进入应用管理页开始创建应用。
# 4 创建应用
创建机器人。
# 4.1 点击「创建机器人」
# 4.2 填写资料
# 4.2.1 机器人资料填写页面
# 4.2.2 进入管理端
资料提交成功后，即会生成appid，点击对应的应用即可跳转管理端。
# 5. 机器人发布流程
建议按照首页发布流程，分别完成机器人配置、开发、提交审核；审核通过并手动上线后，方可在QQ客户端添加机器人至对应场景。
# 6. 基础信息设置
机器人创建后首次上线前，在相关功能配置提交审核时，机器人基本信息将一并提交审核；
机器人首次上线后，机器人基本信息修改将单独提交审核，审核完成前其他模块不可提交审核；
基本信息修改限制：每月可修改
5次。
操作步骤：
（1）点击「修改」进入编辑，完成基础信息修改
（2）点击保存，扫描二维码确认保存
（3）等待审核通过
（4）审核通过后，前往「发布设置」，点击「上线」
# 7. 开发场景选择
在沙箱配置页面，不同类型开发者支持开发不同场景机器人功能
可开发的场景与开发者认证身份有关，详细如下：
| 认证身份 | QQ频道 | QQ群 | 消息列表单聊 |
|---|---|---|---|
| 企业开发者 | ✅ | ✅ | 申请后可开发 |
| 个人开发者 | ✅ | 暂不开放 | 暂不开放 |
# 7.1 配置沙箱环境
建议开发者根据实际的需要，选择在不同场景开发机器人，完成对应场景的沙箱环境配置。配置沙箱后，开发者可在「功能配置」、「使用范围与人员」页面解锁相应场景的配置能力。
沙箱频道仅可设置当前用户为频道主/管理员的频道、沙箱群仅可设置当前用户为群主/群管理员的群，且沙箱频道成员、沙箱群成员不可大于20人。
温馨提示
（1）配置沙箱群/频道，需要先在QQ客户端创建符合沙箱要求的QQ群/QQ频道；
（2）在频道场景，机器人仍然保留「公域」/「私域」机器人的区分，设置为公域机器人保存确认后不可切换为私域机器人，但在「使用范围与人员」可设置公域机器人的允许添加范围：“全部用户可添加”/“仅白名单用户可添加”；
（3）配置沙箱频道/群后，机器人会出现在沙箱频道/沙箱群的机器人列表当中。
# 7.2 添加机器人至沙箱环境
配置好沙箱环境后，可通过机器人资料卡将测试机器人添加进沙箱频道/沙箱群/沙箱账号，沙箱群/沙箱频道也可通过群/频道设置页的机器人列表添加机器人。
# 7.2.1 添加到沙箱频道
方法一：移动端点击沙箱频道封面图-->选择「机器人」进入商店页-->点击添加测试机器人
方法二：移动端登陆管理员QQ号-->扫描管理端频道机器人二维码-->打开机器人资料卡-->添加至频道-->选择配置好的沙箱频道-->确认添加
温馨提示
二维码可在「使用范围与人员」页面扫描。
【进入私信沙箱】
沙箱频道添加好测试机器人后，已经配置沙箱私信账号的QQ号，从沙箱频道打开机器人资料卡，选择私信，即进入私信沙箱环境
温馨提示
当账号在「沙箱配置」-「在频道私信配置」完成配置后，该账号从任意渠道进入该机器人的频道私信窗口，拉到的该机器人指令面板、基础信息资料等内容均为沙箱环境信息。
# 7.2.2 添加到沙箱群
方法一：移动端点击沙箱群"设置"-->选择「群机器人」进入商店页-->点击添加测试机器人
方法二：移动端登陆管理员QQ号-->扫描管理端QQ群和消息列表机器人二维码-->打开机器人web资料卡-->点击「添加到机器人」-->跳转到native资料卡-->分享到沙箱群-->打开native资料卡-->点击「添加到本群」-->选择配置好的沙箱群-->授权确认添加
温馨提示
二维码可在「使用范围与人员」页面扫描
# 7.2.3 添加到沙箱账号消息列表
移动端登陆管理员QQ号-->扫描管理端QQ群和消息列表机器人二维码-->打开机器人资料卡-->点击"发消息"-->授权确认添加-->进入消息列表开启沙箱单聊对话
# 8. 开发基础设置
获取与配置开发所需信息
# 8.1 机器人 AppID
此处主要展示机器人QQ号、AppID、Token、AppSecret。
温馨提示
此信息不要对外传播
# 8.2 回调地址
在跳转h5需要OAuth的时候使用 （如机器人服务是跳转小程序，可忽略），回调地址上限为10条。
# 8.3 消息URL白名单配置
填写机器人下发消息中所包含的链接域名，域名需在此处提交后才可生效，域名上限为20条，每年可修改50次。
温馨提示
域名需提前进行 ICP 备案，并通过域名校验才可报备成功。
# 8.4 频道用户意见反馈
为了帮助开发者获取 C 端用户对于机器人的评价与反馈，平台在频道场景为开发者接入了"兔小巢反馈空间"，开发者可以通过创建产品反馈空间。
频道用户意见反馈： 点击进入登陆后，根据提示创建产品，将会获得一个兔小巢反馈空间，C 端用户所填写的机器人反馈将同步至此空间，开发者以后可登陆此空间查看用户反馈。
产品ID填写： 需要在此处填写兔小巢反馈空间的产品 ID，C 端用户的机器人反馈才可同步至此处，详细获取路径如开发者端提示：设置-->产品设置-->产品 ID。
温馨提示
兔小巢创建与使用详情可点击用户反馈空间创建攻略 (opens new window)
# 8.5 IP白名单配置
为了防范接口调用安全风险，平台将支持机器人配置IP白名单。（当前只针对新增机器人默认启用ip白名单，后续会逐渐对旧的机器人进行灰度）
IP白名单功能启用之后，开放平台将会在正式环境对开发者的部署IP进行限制：只有白名单IP才能连接websocket和调用OPENAPI的接口。当前IP白名单只作用于正式环境，不影响机器人在沙箱环境的使用。接口域名如下：
- 获取调用凭证：https://bots.qq.com/app/getAppAccessToken 不区分正式环境、沙箱环境
- 正式环境：https://api.sgroup.qq.com/
- 沙箱环境：https://sandbox.api.sgroup.qq.com 沙箱环境地址只会收到在开发者平台配置的沙箱频道、沙箱私信QQ号、沙箱群、沙箱单聊QQ号的事件，且调用openapi仅能操作沙箱环境
对于新增机器人，平台默认启用IP白名单功能，并限制只有填写了IP白名单才能提审和上线。
温馨提示
IP白名单目的是保证开发者安全，请配置有效的公网唯一IP。
# 9. 发布设置
开发者可以通过【发布设置】来配置机器人指令与服务，此处配置的指令与服务将会在C端指令面板、资料卡等处展示，以便用户与机器人快捷完成交互，后端逻辑均需通过代码开发实现。
# 9.1 功能配置
功能配置分为服务配置、指令配置、快捷菜单配置。其中指令面板对应C端频道、群、消息列表单聊场景下输入框“/”拉起的指令面板，指令面板的服务与指令在“服务配置”、“指令配置”页面分别操作配置；快捷菜单对应C端消息列表单聊场景下拉起的输入框下的功能面板，快捷菜单的服务与指令在同一页面下操作配置。
# 9.1.1 服务配置
消息列表单聊、群聊、频道文字子频道 “/” 指令面板与机器人资料卡「服务」所展示的供用户快捷跳转机器人服务小程序页面的功能，开发者需在管理端配置，可配置功能上限为
24个。
名称：请简单凝练的描述功能，字数不超过
8个中文字符或16个英文字符，内容需符合平台运营规范。介绍：请简单的对功能进行介绍，字数不超过
40个中文字符或80个英文字符，内容需符合平台运营规范。appID：请输入小程序服务的
ID号。path：请输入小程序的路径。
extendData：请输入小程序
extendData，目前仅频道场景可用。权限菜单：请选择本服务是开放给所有用户还是仅针对频道主和管理员。
使用场景：请选择该指令所需配置的用户场景，包括QQ频道、频道私信、QQ群、消息列表等共四个场景，实际所展示的可配置场景取决于当前机器人开发者的角色、所具备的场景权限和沙箱配置状态。
注意
extendData仅支持在频道场景下开放频道ID、子频道ID，群场景、消息列表单聊场景暂无相关字段开放； 当配置了extendData字段且使用场景同时支持频道及其他场景时，用户在非频道场景打开该服务小程序，频道ID、子频道ID返回为空。
# 9.1.2 指令配置
消息列表单聊、群聊、频道文字子频道 “/” 指令面板与机器人资料卡「指令」所展示的供用户快捷输入的指令入口，开发者需在管理端配置，可配置功能上限为
24个。
指令名：请简单凝练地描述指令，字数不超过
8个中文字符或16个英文字符，内容需符合平台运营规范。指令介绍：请简单的对指令进行描述，字数不超过
15个中文字符或30个英文字符，内容需符合平台运营规范。权限菜单：请选择本指令是开放给所有用户还是仅针对频道主和管理员。
使用场景：请选择该指令所需配置的用户场景，包括QQ频道、频道私信、QQ群、消息列表等共四个场景，实际所展示的可配置场景取决于当前机器人开发者的角色、所具备的场景权限和沙箱配置状态。
开发者可添加、删减指令，管理端配置的功能顺序与 C 端机器人指令集展示的功能顺序一致，建议将常用/核心的指令前置。
# 9.1.3 快捷菜单
服务
开发者需在管理端配置用于 C 端的消息列表单聊场景快捷菜单的小程序服务，可配置功能上限为
12个。
名称：请简单凝练的描述功能，字数不超过
8个中文字符或16个英文字符，内容需符合平台运营规范。介绍：请简单的对功能进行介绍，字数不超过
40个中文字符或80个英文字符，内容需符合平台运营规范。appID：请输入小程序服务的
ID号。path：请输入小程序的路径。
指令
开发者需在管理端配置用于 C 端的消息列表单聊场景快捷菜单的功能指令，可配置功能上限为
12个。
指令名：请简单凝练地描述指令，字数不超过
8个中文字符或16个英文字符，内容需符合平台运营规范。指令介绍：请简单的对指令进行描述，字数不超过
15个中文字符或30个英文字符，内容需符合平台运营规范。
注意
指令、服务和快捷菜单模块暂不需要单独提审，自测完成后，填写自测报告与自测报告一起提审。
# 9.2 自测报告
开发者需下载机器人自测报告模版，在自测频道内根据模板要求测试机器人的功能，并填写完自测报告后上传。
# 10. 使用范围与人员配置
开发者可根据机器人实际运营需要控制可添加机器人至频道、群、消息列表单聊的范围。
- 机器人首次上线前，开发者可配置各场景下机器人使用范围为"全量"/"白名单"，切换为白名单后需等待机器人完成首次上线审核后方可配置添加白名单。
- 机器人首次上线后，使用范围的从"全量"切换为"白名单"无需等待审核结果，立即生效；使用范围从"白名单"切换为"全量"时需要等待审核结果。
- 审核结果返回前，不可重复提交审核。
- 频道白名单、群白名单、消息列表单聊用户白名单上限各
20条。
温馨提示
- 将频道/群/消息列表单聊的使用范围设置为全量，即允许全部频道/群/用户通过机器人资料卡添加该机器人，开发者可将机器人资料卡通过链接、二维码等形式分享给频道主/群主/管理员、用户进行机器人添加
- 频道/群/消息列表单聊的使用范围设置为白名单，即仅允许白名单内频道的频道主/管理员、群的群主/管理员、用户通过资料卡添加该机器人至对应频道群、消息列表单聊；
- 将指定频道、群、用户从白名单删除后，并不会在C端移除机器人与该频道、群、用户的关系链，但在QQ客户端操作机器人移除后，无法再通过机器人资料卡添加该机器人，并可能影响机器人在该关系链场景的消息对话服务。
# 11. 成员管理
# 11.1 角色
开发者管理端的角色共有两种：管理员和普通成员。
- 管理员 ：支持修改，但仅管理员本人可操作
- 普通成员 ：可添加最大限度为
50人
# 11.2 权限
- 登陆权限 ：拥有该权限的成员可登陆和查看开发者管理端信息，但不可编辑。
- 发布权限 ：拥有该权限的成员可编辑和提交服务、指令等模块。
- 开发设置 ：拥有该权限的成员可编辑和提交回调地址、URL 模块。
温馨提示
登陆权限是基础权限，要拥有发布权限和开发权限的前提是拥有登陆权限
# 12. 高阶功能
# 12.1 基础消息功能
【消息类型】机器人发送消息分为主动消息和被动消息：
- 被动消息 ：严格的 AB 对话形式（用户艾特机器人发送 A，机器人回复 B），被动消息有效期为
5分钟。 - 主动消息 ：主动触发类型的消息，满足条件机器人主动发送（如定时提醒），主动消息无需在管理者平台进行上传审核。
【主动消息限制 】
- 主动消息每日每个频道限制发送
20条，且仅允许在2个子频道下发主动消息。 - 暂不开放"入群欢迎语"服务。
- 监听事件"当机器人被添加进频道"后，限制机器人仅在
1个子频道内下发主动消息。 - 普通消息不支持图文+文本，如需配置图文+文本，可使用
ark消息实现。
# 12.2 Markdown能力申请
申请方式：点击 QQ机器人消息模板能力 (opens new window)，填写申请表进行能力申请。
申请条件：
- 私域机器人：已审核上架、使用目的 场景合理；
- 公域机器人：已审核上架、过去7天平均使用频道数达3个及以上、使用目的 场景合理。
- 群机器人：已审核上架、过去7天平均使用群数达3个及以上、使用目的 场景合理。
审核周期： 每月15-20日统一审核，审核结果会进行邮件通知。
机器人平台联系邮箱：[email protected]
