教學 August 12, 2026

訊息帳號執行階段復原：該重新整理、重連、啟動還是重新驗證？

當 UnifyPort 訊息帳號收不到新訊息時，不要先要求使用者重新登入。應先讀取驗證狀態與 runtime_status：狀態未知或過期時重新整理；帳號仍已驗證但即時連線異常時重連；執行階段已停止時啟動；只有驗證狀態或 account.auth.required 事件要求使用者操作時，才重新驗證。

重點整理

status、驗證狀態與 runtime_status 是三個不同層次。
驗證成功後，執行階段通常會自動啟動。
POST /runtime/refresh 同步狀態，不會重啟連線。
POST /runtime/reconnect 保留目前驗證並重建異常連線。
Webhook 是訊號；執行動作後仍需用帳號查詢或 refresh 核對。

先分清三種狀態

帳號生命週期文件定義了三層狀態：

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 時就要求重新掃描 QR Code，也能避免驗證已失效後仍一直重連。

若你處理的是平台事件或帳號審查，可先使用WhatsApp 帳號審查中事件應變清單，把平台狀況、政策執行、執行階段故障與 Webhook 消費端故障分開判斷。

決策表：重新整理、重連、啟動或重新驗證

觀察結果	第一個動作	原因
`runtime_status: unknown`	Refresh	先同步服務提供方的最新狀態。
`running`，但已確認連線異常	Reconnect	保留驗證並重建即時連線。
`disconnected` 且驗證為 `authorized`	Reconnect，再核對	驗證仍有效，離線的是執行階段。
`stopped` 且帳號應在線	Start	已停止的執行階段需要明確啟動。
`starting`、`stopping` 或 `reconnecting`	先核對	已有動作進行中，不要重複送出。
驗證為 `pending_auth`、`awaiting_*` 或 `failed`	繼續相符的驗證流程	執行階段控制不能取代使用者驗證。
收到 `account.auth.required`	依 `auth_payload` 重新驗證	現有工作階段需要使用者操作。
`runtime_status: error`	Refresh 並檢查錯誤內容	不要假定每個錯誤都用相同方式處理。

Reconnect API用於帳號層級仍在線、但即時連線不健康的情況；Start API控制執行階段，不負責驗證。

依序實作復原流程

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. unknown 先 refresh

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 '{}'

Refresh 會同步並回傳標準化的 runtime_status。啟動、重連或驗證後，本機狀態不明時也可用它核對；它不會取代 Webhook 接收器或訊息儲存。

3. 驗證仍有效時才 reconnect

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. stopped 才 start

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，以及依服務提供方與驗證模式而異的 QR Code、URL、PIN 或驗證碼。把所需步驟交給帳號擁有者，並依正確流程繼續；不要把工作階段資料寫進日誌。

Webhook 用於告警，查詢用於核對

可訂閱 account.status.updated、account.started、account.auth.required、account.auth.succeeded 與 account.auth.failed，或使用 subscribed_events: ["*"]。公開結構請見標準事件目錄。

account.status.updated 能回報服務提供方觀察到的變化，但不保證涵蓋每次請求造成的狀態轉換。因此重連、啟動或驗證後，應用帳號查詢或 refresh 核對。處理事件前也要驗證簽章；Webhook HMAC、防重送與重試指南說明了原始請求內容的簽章規則。

讀取驗證狀態與 runtime_status
若驗證需要使用者操作：執行相符的驗證流程
否則若為 unknown：refresh
否則若為 disconnected：reconnect
否則若為 stopped：start
否則若動作進行中：核對
否則若為 running：不變更
否則：refresh 並附錯誤內容升級處理

限制與取捨

執行階段復原不能證明 Webhook 端點、佇列、資料庫或下游自動化都正常。若帳號為 running，應用程式卻收不到訊息，請另外檢查 Webhook 投遞與消費流程。

重連也不保證歷史訊息重送。UnifyPort 沒有讀取訊息歷史的 REST API，也不保證補送遺漏內容。WhatsApp 在啟動或重連後可能提供有限的盡力同步，但不是完整封存；入站事件抵達時應立即儲存。

常見問題

`runtime_status: disconnected` 一定要重新掃描 QR Code 嗎？

不一定。先看驗證狀態；若仍為 authorized，請重連執行階段。只有驗證狀態或 account.auth.required 明確要求時才開始新驗證流程。

refresh 與 reconnect 有何不同？

Refresh 讀取並標準化最新狀態；reconnect 會主動重建異常連線。

每次驗證成功都要呼叫 start 嗎？

通常不用。驗證成功後多半自動啟動；只有觀察到的狀態確實需要時才呼叫 start。

running 但仍沒有訊息，該查什麼？

檢查 Webhook 狀態、簽章驗證、HTTP 確認、重試、佇列處理與儲存。連線健康與事件消費健康是兩個條件。

下一步

依帳號生命週期文件實作決策表，並把重新整理執行階段狀態加入維運手冊。

官方來源

以下 UnifyPort 官方文件核對於 2026 年 8 月 12 日：