取消 UnifyPort 授权:避免旧二维码重新出现在登录界面
要取消 UnifyPort 授权流程,应对支持的渠道调用 POST /v1/accounts/{account_id}/auth/cancel,请求体为 {}。关闭二维码弹窗只是本地界面操作。先隐藏旧登录材料,阻止迟到响应重新显示它,再提交取消请求,读取授权状态后决定是否提供新的登录入口。请求超时表示结果待确认,不等于取消失败。
要点
- 文档列出的取消支持包括 Telegram、WhatsApp 和 TikTok;不能根据支持扫码登录就推断支持取消。
- 操作响应中的
cancelled与消息账号当前授权状态是不同的观察结果。 - 按账号协调开始、取消及凭据提交,包括不同浏览器标签页的请求。
- 取消授权不是删除账号、调整计费,也不能证明平台上的所有会话都已撤销。
先选对控制操作
| 用户意图 | 对应操作 |
|---|---|
| 暂时隐藏登录界面 | 关闭界面,并明确授权是否继续 |
| 放弃当前授权尝试 | 使用受支持的取消授权操作 |
| 暂停已有连接 | 停止运行时,不要重置授权 |
| 移除 UnifyPort 消息账号资源 | 使用独立的账号删除流程 |
计划暂停运行时指南处理的是已经连接的账号。本文解决的是操作者不想继续完成的授权尝试。
取消授权参考涵盖验证码、二维码和会话导入流程,但渠道支持限定为 Telegram、WhatsApp、TikTok。LINE、Zalo 支持二维码登录,不代表它们支持这个取消操作。
二维码过期不等于取消整个尝试
Telegram 的官方二维码登录规范说明了登录令牌过期、生成替代二维码,以及由已登录应用接受令牌的过程。因此,旧二维码图片不能作为持久的登录状态。但这份规范不定义 UnifyPort 的取消契约,也不保证关掉浏览器窗口就会停止授权。
UnifyPort 的读取授权状态接口返回 status、auth_fields、auth_payload、expires_at 和 last_error。应读取当前状态及材料,不要使用保存的截图。二维码、验证码、密码和会话材料都不应进入日志或分析系统。
如果需要首次接入,而不是取消流程,请阅读 Telegram 验证码与二维码接入指南。本文增加的是一道控制:只有当前有效的尝试,才能更新界面或继续提交请求。
让同一账号的授权动作顺序执行
以下是应用设计建议,不是服务端事务保证:
- 将界面绑定到经过核对的工作空间和
account_id,检查操作者是否有权管理该消息账号。 - 在后端按账号维护一个有效的授权控制流程。协调其他标签页及其他操作者,而不只是防止当前按钮被双击。
- 点击取消时,将本地尝试标记为失效,隐藏敏感材料,禁用验证码和密码提交,并停止安排新的轮询。
- 更新本地界面代次,避免已经发出的请求在返回后重新显示旧登录界面。
- 由后端提交取消请求。在核对结果前,不开放重新开始按钮。
下面的浏览器端示例丢弃过期的读取响应。generation 和 loginVisible 是应用自定义变量,不是 UnifyPort 字段:
let generation = 0;
let loginVisible = true;
async function refreshLogin(readAuth, render) {
const observedGeneration = generation;
const auth = await readAuth();
if (!loginVisible || observedGeneration !== generation) return;
render(auth);
}
function abandonLocalAttempt(clearSensitiveUi) {
loginVisible = false;
generation += 1;
clearSensitiveUi();
}
这段保护逻辑不能取消已经发出的 HTTP 请求、撤回平台上已经完成的批准,或阻止另一个标签页。后端协调和状态读取仍然必要。Webhook 接收端应保持可用;迟到的授权事件应触发状态核对,而不是自动重新打开旧二维码弹窗。
提交取消,再读取当前状态
以下为未实际执行的示例。变量应来自后端安全配置及经过核对的账号选择:
curl -X POST \
"https://api.unifyport.ai/v1/accounts/${ACCOUNT_ID}/auth/cancel" \
-H "X-Api-Key: ${UNIFYPORT_API_KEY}" \
-H "Content-Type: application/json" \
-d '{}'
curl \
"https://api.unifyport.ai/v1/accounts/${ACCOUNT_ID}/auth" \
-H "X-Api-Key: ${UNIFYPORT_API_KEY}"
取消接口示例返回 HTTP 200,且 data.status: "cancelled"。账号生命周期文档将放弃等待中的授权描述为转回 pending_auth。不要把操作结果复制到所有账号状态字段中。
| 观察结果 | 建议处理 |
|---|---|
取消已确认,当前为 pending_auth | 保持旧材料隐藏,允许用户明确开始新尝试 |
| 超时或无法读取响应 | 标记结果待确认,再次变更前先读状态 |
| 仍在等待输入 | 保持旧界面失效,继续核对或升级处理,不并发启动另一个流程 |
当前为 authorized | 将其视为当前授权证据,不显示“已退出”,也不要自动再次取消 |
批准与取消同时发生时,公开契约没有保证哪一个会原子性地获胜。保留脱敏请求诊断信息,由操作者根据实际状态决定下一步。不要承诺文档未列出的取消 Webhook。
重新开始需要新的明确决定
生命周期文档说明,已授权时启动验证码、二维码或会话授权会返回 409 account_already_authorized。这不意味着可以自动取消健康账号后重试。先确认用户确实需要重新授权。
对于已经放弃的等待流程,先核对取消结果,再创建新的本地界面代次,并按账号配置的授权模式调用对应启动操作。只显示新取得的材料。授权完成后,还要单独读取账号的 runtime_status,才能判断连接是否就绪。
UnifyPort 提供非官方接口。取消操作不是平台其他会话的统一退出功能,也不会解除平台安全控制。
常见问题
关闭二维码弹窗就取消授权了吗?
不是。关闭弹窗只改变应用界面;服务端取消需要调用受支持的 API 操作。
二维码过期后应自动取消吗?
不应。过期的是登录材料。除非用户明确放弃,否则应读取当前授权状态并按渠道流程更新材料。
请求超时后能显示取消成功吗?
不能。应显示结果待确认并核对状态,不立即启动新流程,也不连续重复提交取消。
取消会停止计费或删除消息吗?
取消契约没有这样的保证。账号退役、计费、已存消息清理和授权控制应分别处理。
下一步与参考资料
对照取消授权参考实现流程。建议测试迟到轮询响应、双标签页、批准与取消竞争、响应丢失,以及有意重新开始。这些是建议的测试场景,不是已取得的测试结果。
资料核对日期:2026-11-12。
让消息接入变成一条稳定的产品管线。
先用统一 API 跑通发送,再用标准事件把所有入站消息接回业务系统。