rocket_launch 接入指南

三步接入，跑通私域触达

以下以「WAR-战争游戏」为例，演示完整接入过程。

创建应用

扫码登录控制台，创建应用并关联数字员工

接入登录

接入「使用 Q助理登录」，配置回调地址

调用 API

获取用户信息，随时推送私域消息

以「WAR-战争游戏」为例的完整接入示例

第一步 · 创建应用并关联数字员工

进入开发者控制台，用 Q助理扫码登录，点击「创建应用」，填写：

字段	示例
应用名称	WAR-战争游戏
应用简介	跨服策略战争游戏，Q助理账号一键登录
回调地址	`https://war.game.com/oauth/callback`
应用类型	Web / App / 小程序 / 桌面端
授权信息范围	基础信息（必选）+ 手机号（可选，开启时填写用途声明）

创建时选择关联数字员工「战争助手」（必选），保存 AppKey 与仅展示一次的 AppSecret；之后可在控制台「应用列表」中编辑应用配置。

第二步 · 接入「使用 Q助理登录」

在游戏登录页放置「使用 Q助理登录」按钮，点击后跳转授权页：

跳转授权页（前端）

// 前端跳转授权页
<a href="https://open.qzhuli.com/oauth/authorize?app_key=YOUR_APP_KEY&redirect_uri=https%3A%2F%2Fwar.game.com%2Foauth%2Fcallback&state=RANDOM_STATE&scope=user_info">使用 Q助理 登录</a>

平台会展示二维码并完成扫码确认。用户同意后，Q助理回调到你的 redirect_uri 并携带一次性 code；用户取消则回调 error=access_denied。服务端应先校验回调中的 state。

第三步 · 换取会话并触达

用 code 换取用户 token，并获取应用 token（服务端）

# 服务端用回调 code 换取用户 token（用于查询该用户资料）
curl -X POST https://open.qzhuli.com/oauth/access_token \
  -H "Content-Type: application/json" \
  -H "X-QZ-App-Key: YOUR_APP_KEY" \
  -H "X-QZ-Timestamp: UNIX_MS_TIMESTAMP" \
  -H "X-QZ-Nonce: RANDOM_NONCE_AT_LEAST_16" \
  -H "X-QZ-Sign: HMAC_SHA256_SIGNATURE" \
  -d '{"app_secret":"YOUR_APP_SECRET","grant_type":"authorization_code",
       "code":"ONE_TIME_CODE","redirect_uri":"https://war.game.com/oauth/callback"}'

# 再换取应用 token（用于消息、统计等应用级 API）
curl -X POST https://open.qzhuli.com/oauth/access_token \
  -H "Content-Type: application/json" \
  -H "X-QZ-App-Key: YOUR_APP_KEY" \
  -H "X-QZ-Timestamp: UNIX_MS_TIMESTAMP" \
  -H "X-QZ-Nonce: A_NEW_RANDOM_NONCE" \
  -H "X-QZ-Sign: A_NEW_HMAC_SHA256_SIGNATURE" \
  -d '{"app_secret":"YOUR_APP_SECRET","grant_type":"client_credentials"}'

# 用户已自动连接你的数字员工「战争助手」，成为你的私域用户。
# 使用应用 token 向该用户推送消息：
curl -X POST https://open.qzhuli.com/open/message/push \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer APP_ACCESS_TOKEN" \
  -H "X-QZ-App-Key: YOUR_APP_KEY" \
  -H "X-QZ-Timestamp: UNIX_MS_TIMESTAMP" \
  -H "X-QZ-Nonce: A_NEW_RANDOM_NONCE" \
  -H "X-QZ-Sign: A_NEW_HMAC_SHA256_SIGNATURE" \
  -d '{"q_uid":"q_USER_ID","title":"新赛季开启",
       "message":"指挥官，新赛季已开启，速来集结！",
       "url":"https://war.game.com/season","message_id":"season_2026"}'

每次服务端请求都需要新的时间戳、随机串和签名；签名计算规则见 API 文档。用户 token 用于查询该用户资料，消息与统计等应用级接口使用应用 token。

check_circle 接入完成后，该用户即出现在你的控制台「私域用户」列表，你可随时向他发送消息（含群发、短信兜底），触达他只需要一条 API 调用。

手机号用途声明文案模板

商家开启「获取用户手机号」时，须填写「手机号用途声明」，授权页将展示标准文案：

「WAR-战争游戏」希望获取你的手机号

用途说明：用于向你发送账号安全提醒、游戏活动通知，以及在你需要时与你取得联系。

你可以在 Q助理「我的 → 授权管理」中随时查看或撤销该项授权。若选择暂不授权，本次登录/授权不会完成，可返回后重新发起授权。

同意并授权暂不授权

合规红线：实际用途必须与声明一致；用户可随时撤销手机号授权。

常见问题

扫码时用户可在授权页快捷注册 Q助理账号（手机号注册），注册后即可完成授权登录与连接。

可在控制台重置 AppSecret，并建议开启服务器 IP 白名单——设置后仅白名单内 IP 的请求被认可，白名单之外的调用一律拒绝。

可以。一个应用可关联一个数字员工，一个数字员工可被多个应用关联，同一商家多应用可共享同一私域用户池。

进入控制台「私域用户」可查看用户列表、连接时间与消息触达状态；列表中的手机号默认脱敏展示。已授权的完整手机号通过用户信息接口按授权范围返回；「数据统计」可查看登录授权数、连接数、消息发送 / 已读数与已读率。