教程 August 12, 2026

消息账号运行时恢复：该刷新、重连、启动还是重新认证？

当 UnifyPort 消息账号收不到新消息时，不要先让用户重新登录。应先同时读取认证状态与 runtime_status：状态未知或陈旧时执行刷新；账号仍已认证但实时连接异常时执行重连；运行时被明确停止时执行启动；只有认证状态或 account.auth.required 事件要求用户操作时，才重新认证。

核心结论

status、认证状态与 runtime_status 是三个独立维度。
认证成功后，运行时通常会自动启动。
POST /runtime/refresh 用于同步状态，不会重启连接。
POST /runtime/reconnect 在保留当前认证的前提下重建异常连接。
Webhook 是状态信号；执行动作后仍要通过账号查询或刷新进行核对。

先分清三种状态

账号生命周期文档定义了三层状态：

status 是工作区控制的业务开关。
认证状态来自 GET /v1/accounts/{account_id}/auth，可能是 pending_auth、awaiting_qr_scan、awaiting_code、awaiting_password、authorized 或 failed。
runtime_status 表示实时连接，统一值包括 unknown、starting、running、stopping、stopped、reconnecting、disconnected 与 error。

这项区分可以避免两类误操作：账号仍为 authorized 时却要求用户重新扫码，以及认证已经失效时仍反复调用重连。

如果你处理的是平台异常或账号审核，而不只是连接状态，可先使用WhatsApp 账号审核中事故响应清单，分别排查平台事件、政策执行、运行时连接和 Webhook 消费端。

决策表：刷新、重连、启动或重新认证

观察到的状态	首个动作	原因
`runtime_status: unknown`	刷新	先同步提供方最新状态，再决定是否改动连接。
`running`，但已确认连接异常	重连	保留认证并重建实时连接。
`disconnected` 且认证为 `authorized`	重连，然后核对	认证仍有效，离线的是运行时。
`stopped` 且账号应在线	启动	已停止的运行时需要显式启动。
`starting`、`stopping` 或 `reconnecting`	先核对，不要重复发动作	已有操作进行中。
认证为 `pending_auth`、`awaiting_*` 或 `failed`	继续或重新发起对应认证流程	运行时动作不能代替用户认证。
收到 `account.auth.required`	按 `auth_payload` 重新认证	当前会话已需要用户操作。
`runtime_status: error`	刷新并检查错误上下文	不要假定所有错误都能用同一动作修复。

重连接口用于账号层面在线、但实时连接不健康的场景；启动接口控制运行时，不负责认证。

按顺序实施恢复

1. 同时读取账号与认证状态

curl https://api.unifyport.ai/v1/accounts/acc_8c21d0 \
  -H "X-Api-Key: $UNIFYPORT_API_KEY"

curl https://api.unifyport.ai/v1/accounts/acc_8c21d0/auth \
  -H "X-Api-Key: $UNIFYPORT_API_KEY"

账号对象提供 runtime_status；认证资源提供自己的 status，并可能提供 auth_payload 或 last_error。不要只根据运行时状态猜测认证情况。

2. 未知状态先刷新

curl -X POST https://api.unifyport.ai/v1/accounts/acc_8c21d0/runtime/refresh \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

刷新会同步并返回标准化的 runtime_status，也适合在启动、重连或认证动作后核对本地状态。它不会替代 Webhook 消费端或消息存储。

3. 认证仍有效时才重连

curl -X POST https://api.unifyport.ai/v1/accounts/acc_8c21d0/runtime/reconnect \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

即时响应可能为 reconnecting。这表示操作正在进行，不代表消息流已经恢复；随后仍需核对状态。

4. 被停止的运行时才启动

curl -X POST https://api.unifyport.ai/v1/accounts/acc_8c21d0/runtime/start \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

认证成功通常会自动启动运行时，因此不要把重新登录当成调用 start 的固定前置步骤。

5. 只在认证证据明确时重新认证

account.auth.required 可携带 auth_status、runtime_status，以及与提供方和认证方式相关的二维码、URL、PIN 或验证码。将对应步骤展示给账号所有者，并继续正确的认证流程；不要把会话材料写入日志。

Webhook 用于告警，查询用于核对

可以订阅 account.status.updated、account.started、account.auth.required、account.auth.succeeded 和 account.auth.failed，也可以使用 subscribed_events: ["*"]。具体公开结构见标准事件目录。

account.status.updated 能报告提供方观察到的认证或运行时变化，但并不保证覆盖每一次请求触发的转换。因此在重连、启动或认证后，应使用账号查询或 runtime refresh 核对结果。接收事件前还要验证签名；Webhook HMAC、防重放与重试指南说明了原始请求体签名规则。

读取认证状态与 runtime_status
若认证需要用户操作：执行对应认证流程
否则若为 unknown：刷新
否则若为 disconnected：重连
否则若为 stopped：启动
否则若操作进行中：核对
否则若为 running：不做改动
否则：刷新并带错误上下文升级处理

限制与边界

运行时恢复并不能证明 Webhook 地址、队列、数据库或下游自动化都正常。如果账号为 running 但应用仍收不到消息，应单独检查 Webhook 投递与消费链路。

重连也不保证历史消息重放。UnifyPort 没有用于读取消息历史的 REST API，也不承诺补发遗漏事件。WhatsApp 在启动或重连后可能提供有限的尽力而为历史同步，但它不是完整归档；入站事件到达时应立即保存。

常见问题

`runtime_status: disconnected` 是否一定要重新扫码？

不一定。先检查认证状态；如果仍为 authorized，应重连运行时。只有认证状态或 account.auth.required 明确要求时才启动新认证流程。

refresh 与 reconnect 有什么区别？

refresh 读取并标准化最新连接状态；reconnect 会主动重建异常连接。

每次认证成功后都要调用 start 吗？

通常不需要。认证成功后运行时一般自动启动；只有观察到的状态确实需要时才调用 start。

账号为 running，但仍没有消息怎么办？

检查 Webhook 状态、签名验证、HTTP 确认响应、重试、队列处理和存储。提供方连接正常与事件消费链路正常是两件事。

下一步

按账号生命周期文档实现上述决策表，并将刷新运行时状态接口加入值班手册。

官方来源

以下 UnifyPort 官方文档核对于 2026 年 8 月 12 日：