如何得知客戶的 WhatsApp 或社交連接何時中斷
easyCoexistence 會在客戶的連接連上、中斷、被移除或暫停時,發送經平台簽署的狀態事件。WhatsApp 號碼會發送 connection.connected、附有 Meta 原因的 connection.disconnected、connection.removed、connection.suspended 或 connection.token_missing;社交帳戶則發送對應的 channel.* 事件,但沒有 token_missing。每個事件都是 JSON POST,以 X-EC-Signature 簽署,並以退避方式重試約 33 小時,直至你的端點回應 2xx 為止。
PRIMARY_INACTIVITY:主要裝置閒置約 14 天時 Meta 給出的原因,會令 Coexistence 號碼中斷連接。
COMPANION_INACTIVITY:附屬裝置閒置約 30 天時 Meta 給出的原因。
回報連接中斷的 Webhook。Meta 一律發送至應用程式的預設 Webhook 網址,從不發送至覆寫的網址。
任何非 2xx 回應後,狀態事件被重試的次數,間隔為 1 分鐘至 24 小時,歷時約 33 小時。
端點對狀態事件應接受的最舊簽署時間戳 t,並以恆定時間比對 HMAC。
有哪些狀態事件?
共九項,分屬兩個系列,共用同一個端點與同一組簽署密鑰。號碼使用 connection.*,社交帳戶使用 channel.*,因此只處理號碼的接收端可按名稱略過頻道事件。請在控制台中依次進入 Profile、Developers 設定端點,或使用 MCP 工具 set_partner_events_url;簽署密鑰只會在儲存 URL 時顯示一次。
連接事件包含什麼?
傳送的 id(UUID)、事件名稱、ISO 8601 格式的 occurred_at,以及一個 connection 物件,其中包含 id、external_ref、connect_session_id、phone、name、waba_id、phone_number_id、status 與 token_ready。部分事件會加入頂層欄位:connection.disconnected 與 connection.suspended 會有 reason;當 easyCoexistence 自己的定期檢查(而非 Meta 的 Webhook)發現中斷時,detected_by 會設為 health_check;若事件由連接會話產生,則會有 connect_session_id。
{
"id": "5c2a9e70-…",
"event": "connection.disconnected",
"occurred_at": "2026-10-31T10:15:02.114Z",
"connection": {
"id": "<CONNECTION_ID>",
"external_ref": "customer_4821",
"connect_session_id": "cs_…",
"phone": "+55 11 9…",
"name": "Clínica Sorriso",
"waba_id": "<WABA_ID>",
"phone_number_id": "<PHONE_NUMBER_ID>",
"status": "disconnected",
"token_ready": true
},
"reason": "PRIMARY_INACTIVITY"
}頻道事件包含什麼?
與連接事件相同的結構,只是以 channel 物件取代 connection。該物件與 GET /channels/{id} 的檢視相同:id、channel(所屬網絡)、external_ref、connect_session_id、name、username、external_id、status、token_ready、webhook_url、disconnected_reason、last_checked_at 與 created_at。頻道沒有 token_missing,因為社交登入一定會取得客戶自己的權杖;而由連接會話產生的 channel.connected 也會在頂層附上 connect_session_id。
{
"id": "0b7e41d2-…",
"event": "channel.disconnected",
"occurred_at": "2026-10-31T10:15:02.114Z",
"channel": {
"id": "<CHANNEL_ID>",
"channel": "tiktok",
"external_ref": "customer_4821",
"connect_session_id": "cs_…",
"name": "Clínica Sorriso",
"username": "clinicasorriso",
"external_id": "<TIKTOK_OPEN_ID>",
"status": "disconnected",
"token_ready": false,
"webhook_url": "https://hooks.example.com/social",
"disconnected_reason": "<THE_NETWORK'S_MESSAGE>",
"last_checked_at": "2026-10-31T10:15:02.000Z",
"created_at": "2026-10-28T16:40:09.000Z"
}
}中斷原因代表什麼?
connection.disconnected 上的 reason,是 Meta 放在其 account_update Webhook 的 disconnection_info 內的代碼,適用於 WhatsApp Business 應用程式與 Cloud API 上的號碼。若 Meta 未提供,則為 null。Meta 參考文件中的代碼如下:
PRIMARY_INACTIVITY:運行 WhatsApp Business 應用程式的手機閒置約 14 天,即 14 天規則。新的連接會話可重新連接該號碼。ACCOUNT_DISCONNECTED:帳戶因 Meta 的執行措施或客戶而中斷,客戶可能已移除存取權限或刪除帳戶。COMPANION_INACTIVITY:附屬裝置閒置約 30 天。BUSINESS_DOWNGRADE:該號碼曾以消費者版 WhatsApp 應用程式註冊。CHANGE_NUMBER與USER_RE_REGISTERED:客戶更改了號碼,或在新裝置上重新註冊。
狀態事件附帶哪些標頭?
共五項,每次嘗試都會附上:Content-Type application/json、User-Agent easyCoexistence-webhooks/1、X-EC-Event(事件名稱)、X-EC-Delivery(與內文 id 相同)與 X-EC-Signature。簽署格式為 t=<unix>,v1=<hex>,其中 v1 是以你帳戶的簽署密鑰為密鑰,對 t、一個句點與原始內文所計算的 HMAC-SHA256。簽署密鑰以 whsec_ 開頭。每次嘗試都會重新簽署,因此重試時的 t 會不同,但內文相同。
import hashlib, hmac, json, os, time
SECRET = os.environ["EC_EVENTS_SECRET"].encode() # whsec_..., shown once in Profile > Developers
def verify(raw: bytes, header: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or abs(time.time() - int(t)) > 300:
return False # missing, or more than 5 minutes off
mac = hmac.new(SECRET, t.encode() + b"." + raw, hashlib.sha256).hexdigest()
return hmac.compare_digest(mac, v1)
def handle(raw: bytes, headers) -> int:
if not verify(raw, headers.get("X-EC-Signature", "")):
return 401
event = json.loads(raw)
if already_processed(event["id"]): # the X-EC-Delivery id, the same on every retry
return 200
enqueue(event) # act on event["event"]; the latest occurred_at wins
return 200失敗的傳送如何重試?
首次嘗試會在事件發生時即時發出。非 2xx 回應、10 秒內無回應、網絡錯誤或重定向,均視為失敗。事件會以逐漸拉長的間隔再次嘗試,由 1 分鐘至 24 小時,合共七次嘗試、歷時約 33 小時,之後才會捨棄。傳送只會發往解析為公共 IP 的 HTTPS 地址。在未設定端點時發生的事件永不排隊,移除端點則會停止所有待處理的傳送。
為何每個 id 只處理一次並檢查 occurred_at?
因為重試會完全重複同一次傳送,內文與 X-EC-Delivery 中的 id 皆相同;而重試的事件也可能在較新的事件之後才抵達。請記錄已處理的 id 並略過重複的事件。然後比較 occurred_at 與你為該連接記錄的最後狀態,或在根據可能已過時的事件採取行動前,先讀取 GET /connections/{id} 或 GET /channels/{id}。
號碼中斷時平台應如何處理?
按原因採取行動。PRIMARY_INACTIVITY 發生後,請客戶開啟 WhatsApp Business 應用程式,並為同一號碼發送新的連接會話。在同一個 WhatsApp Business Account 上重新連接,可保留其連接 ID、恢復你的 Webhook 目的地,並發送 connection.connected;之後你應重新讀取其憑證。connection.token_missing 則表示該次操作 Meta 未發出權杖。中斷背後的 account_update 只會發送至應用程式自己的 Webhook 網址,而不會發送至你的 URL,因此這個事件正是讓你的平台得知中斷的途徑。
社交帳戶中斷時平台應如何處理?
收到 channel.disconnected 後,以同一頻道 ID 的新連接會話,即可再次登入該帳戶。channel.removed 表示存取權限已失效:權杖會被刪除,Webhook 目的地亦會被清除,因此若客戶重新連接,須重新設定目的地。號碼或頻道被暫停時,待你的訂閱重新生效後,重新連接一次即可恢復。
常見錯誤
- 將重試視為新事件。重試時內文與 X-EC-Delivery 中的 id 相同,因此請記錄已處理的 id,否則同一次中斷可能令客戶收到兩次通知。
- 按抵達順序套用事件。重試的事件可能在較新的事件之後才抵達,因此應比較 occurred_at,或在採取行動前先讀取連接。
- 只為修正錯字而重新儲存事件 URL,卻未更新後端。儲存會發出新的簽署密鑰,在你的端點改用新密鑰前,每次傳送都會驗證失敗。
- 未先回應便開始處理。若處理程式耗時超過 10 秒即視為失敗,事件會被重送,因此應先回應 2xx,之後再處理。
easyCoexistence 全天候監察每位客戶的 WhatsApp 號碼與社交帳戶,在連接、中斷、被移除或暫停時,向你的平台發送經簽署的事件;若號碼中斷,事件會附上 Meta 的原因。每個連接每月由 US$ 9 降至 US$ 0.75,連接越多越便宜,首 3 天免費。
常見問題
PRIMARY_INACTIVITY 是什麼意思?
這是 Meta 的原因代碼,表示 Coexistence 號碼的 WhatsApp Business 應用程式在主要裝置上約 14 天未被使用,因而被中斷連接。為該客戶建立新的連接會話,即可重新連接該號碼。
狀態事件包含訊息嗎?
不包含。狀態事件只涵蓋連接的狀態。號碼的訊息由 Meta 發送至其自身的 Webhook 目的地,社交留言與私訊則發送至各頻道的目的地。
在哪裡設定事件 URL?
在控制台中依次進入 Profile、Developers,或使用 MCP 工具 set_partner_events_url。簽署密鑰只會顯示一次,再次儲存 URL 會發出新的密鑰。
如果只處理號碼,可以忽略頻道事件嗎?
可以。channel.* 事件有自己的名稱,並以 channel 物件取代 connection,因此接收端可以略過任何名稱不以 connection 開頭的事件。
繼續閱讀
兩分鐘內連接您的第一個頻道。
無需等待平台審核。連接 WhatsApp、Instagram、TikTok 或其他頻道,然後請您的 AI 發佈貼文、回覆訊息或匯報數據,並看着它運作。
- 免費試用 3 天
- 隨時取消
- 只用官方 API
- 24/7 監察
驗證日期