教學 August 12, 2026

訊息帳戶 Runtime 復原：應該 Refresh、Reconnect、Start 還是重新認證？

當 UnifyPort 訊息帳戶收不到新訊息，不要先要求用戶重新登入。先同時讀取認證狀態與 runtime_status：狀態未知或過期時 refresh；帳戶仍已認證但即時連線異常時 reconnect；runtime 已停止時 start；只有認證狀態或 account.auth.required 事件要求用戶操作時，才重新認證。

重點

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

先分清三種狀態

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

status 是 workspace 控制的業務開關。
認證狀態來自 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，也可避免認證已失效後仍不斷 reconnect。

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

決策表：refresh、reconnect、start 或重新認證

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

Reconnect API用於帳戶層面仍在線、但即時連線不健康的情況；Start API控制 runtime，不處理認證。

依次序實作復原流程

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。不要只憑 runtime 狀態推測認證情況。

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 receiver 或訊息儲存。

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

認證成功通常會自動啟動 runtime，所以重新登入不應是每次 start 的固定前置步驟。

5. 只在認證證據明確時重新認證

account.auth.required 可帶有 auth_status、runtime_status，以及按服務供應方與認證模式而異的 QR Code、URL、PIN 或驗證碼。向帳戶持有人展示所需步驟，再繼續正確的認證流程；不要把 session 資料寫入 log。

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

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

account.status.updated 能回報服務供應方觀察到的變化，但不保證涵蓋每次請求造成的狀態轉換。因此 reconnect、start 或認證後，應用帳戶查詢或 refresh 核對。處理事件前亦要驗證簽署；Webhook HMAC、防重放與重試指南說明原始 request body 的簽署規則。

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

限制與取捨

Runtime 復原不能證明 Webhook endpoint、queue、資料庫或下游自動化都正常。若帳戶為 running，應用程式仍收不到訊息，請另外檢查 Webhook 投遞與消費流程。

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

常見問題

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

不一定。先看認證狀態；若仍為 authorized，請 reconnect。只有認證狀態或 account.auth.required 明確要求時才開始新認證流程。

refresh 與 reconnect 有甚麼分別？

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

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

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

running 但仍沒有訊息，應檢查甚麼？

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

下一步

按帳戶生命週期文件實作決策表，並把Refresh runtime state加入維運手冊。

官方來源

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