接收事件

account.auth.failed

一次認證嘗試失敗。

帳號失敗事件

部分 WhatsApp account.auth.failed 事件包含可選 data.error 物件；如有提供，code、numeric_code、message 都係非空字串。請喺事件內讀取，同 HTTP 錯誤回應分開處理。

舊事件及範圍外事件可能冇 data.error；請保持 last_error 兼容，缺少或未知碼沿用現有帳號失敗流程。帳號列表或詳情唔會因此新增此物件。呢啲分類唔證明永久封禁，亦冇固定恢復期限。

安全接收並接受處理後仍傳回 2xx 確認投遞。帳號失敗同 HTTP 投遞失敗要分開處理，唔好因帳號失敗拒收 Webhook 而觸發重投。重試及重放沿用原規則，歷史事件唔會補齊錯誤。

account_auth_failed20100

帳號授權失敗，但具體原因未確定。沿用現有失敗流程，唔好自行推斷受限或登出原因。

處理與重試: 查詢目前授權流程，確認係咪需要用戶操作。唔好單憑本次失敗重新發起授權，亦唔好向已過期或已結束嘅會話重複提交。

示意 JSON；message 會隨實際原因變化

{
  "id": "<EVENT_ID>",
  "type": "account.auth.failed",
  "provider": "whatsapp",
  "account_id": "<ACCOUNT_ID>",
  "occurred_at": "2026-10-16T00:00:00Z",
  "data": {
    "auth_status": "failed",
    "runtime_status": "disconnected",
    "event": {
      "kind": "account_auth_status",
      "auth_status": "failed",
      "runtime_status": "disconnected"
    },
    "error": {
      "code": "account_auth_failed",
      "numeric_code": "20100",
      "message": "Account authentication failed. The specific cause could not be determined."
    }
  }
}

account_logged_out20101

目前帳號會話已失效。引導用戶按呢個渠道支援嘅流程重新授權。

處理與重試: 引導用戶按呢個渠道支援嘅流程重新授權。完成授權後再查運行狀態，確認連線就緒，先恢復依賴連線嘅操作。

示意 JSON；message 會隨實際原因變化

{
  "id": "<EVENT_ID>",
  "type": "account.auth.failed",
  "provider": "whatsapp",
  "account_id": "<ACCOUNT_ID>",
  "occurred_at": "2026-10-16T00:00:00Z",
  "data": {
    "auth_status": "failed",
    "runtime_status": "disconnected",
    "event": {
      "kind": "account_auth_status",
      "auth_status": "failed",
      "runtime_status": "disconnected"
    },
    "error": {
      "code": "account_logged_out",
      "numeric_code": "20101",
      "message": "The account session is no longer valid. Reauthorization is required."
    }
  }
}

account_restricted20102

呢個 WhatsApp account.auth.failed 事件用 data.error.code=account_restricted、numeric_code=20102 標示目前登入受限。唔證明永久封禁，亦唔說明幾時可恢復。

處理與重試: 停止自動傳送同重試，引導用戶到官方 WhatsApp 客戶端檢查及處理限制。問題解決並完成所需重新授權後再恢復；之前係 running 唔證明限制已解除。

示意 JSON；message 會隨實際原因變化

{
  "id": "<EVENT_ID>",
  "type": "account.auth.failed",
  "provider": "whatsapp",
  "account_id": "<ACCOUNT_ID>",
  "occurred_at": "2026-10-16T00:00:00Z",
  "data": {
    "auth_status": "failed",
    "runtime_status": "disconnected",
    "event": {
      "kind": "account_auth_status",
      "auth_status": "failed",
      "runtime_status": "disconnected"
    },
    "error": {
      "code": "account_restricted",
      "numeric_code": "20102",
      "message": "Account login is restricted. Check the official WhatsApp app for details."
    }
  }
}

事件載荷

{
  "id": "evt_auth_5e6f7a8b9c",
  "type": "account.auth.failed",
  "provider": "whatsapp",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T13:25:00Z",
  "data": {
    "auth_status": "failed",
    "runtime_status": "disconnected",
    "last_error": "logged_out_from_another_device",
    "event": {
      "kind": "account_auth_status",
      "auth_status": "failed"
    }
  }
}

備註

舊事件及範圍外事件可能冇 data.error；請保持 last_error 兼容，缺少或未知碼沿用現有帳號失敗流程。帳號列表或詳情唔會因此新增此物件。呢啲分類唔證明永久封禁，亦冇固定恢復期限。