顧客の WhatsApp やソーシャル接続が切れたことを知る方法
easyCoexistence は、顧客の接続が確立、切断、削除、または停止されたときに、署名付きのステータスイベントをプラットフォームへ送信します。WhatsApp 番号では connection.connected、Meta の理由を伴う connection.disconnected、connection.removed、connection.suspended、connection.token_missing が送信されます。ソーシャルアカウントでは、token_missing を除く channel.* の同等イベントが送信されます。いずれも X-EC-Signature で署名された JSON の POST で、エンドポイントが 2xx を返すまで、約 33 時間にわたりバックオフ付きで再送されます。
PRIMARY_INACTIVITY: プライマリデバイスが約 14 日間非アクティブだったため、Coexistence 番号の接続を切断したことを示す Meta の理由です。
COMPANION_INACTIVITY: コンパニオンデバイスが約 30 日間非アクティブだったことを示す Meta の理由です。
切断を報告する Webhook です。Meta は常にアプリのデフォルトのコールバック URL に送信し、オーバーライド先には送信しません。
2xx 以外の応答を受けた後、ステータスイベントが再試行される頻度です。間隔は 1 分から 24 時間まで、約 33 時間にわたります。
エンドポイントがステータスイベントで受け入れるべき、署名済みタイムスタンプ t の最古の値です。HMAC は定数時間で比較します。
どのようなステータスイベントがありますか?
9 種類あり、1 つのエンドポイントと 1 つの署名シークレットを共有する 2 つのファミリーに分かれています。番号は connection.*、ソーシャルアカウントは channel.* を使うため、番号向けに書かれた受信側は名前で channel イベントをスキップできます。エンドポイントはダッシュボードの「Profile」、「Developers」の順に進んで設定するか、MCP ツール set_partner_events_url で設定します。署名シークレットは URL を保存したときに 1 度だけ表示されます。
connection イベントにはどのような情報が含まれますか?
配信の id(UUID)、イベント名、ISO 8601 形式の occurred_at、そして id、external_ref、connect_session_id、phone、name、waba_id、phone_number_id、status、token_ready を含む connection オブジェクトです。一部のイベントはトップレベルのフィールドを追加します。connection.disconnected と connection.suspended には reason が付きます。detected_by は、Meta の Webhook ではなく easyCoexistence 独自の定期チェックで切断を検出した場合に health_check になります。connect セッションがイベントを生んだ場合は 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 の代わりに channel オブジェクトを含みます。これは 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 はありません。ソーシャルのサインインでは常に顧客自身のトークンが得られるためです。connect セッションから生じた 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 日ルール)。新しい connect セッションで番号を再接続できます。ACCOUNT_DISCONNECTED: Meta による施行、または顧客によってアカウントが切断されました。顧客がアクセスを削除したか、アカウントを削除した可能性があります。COMPANION_INACTIVITY: コンパニオンデバイスが約 30 日間非アクティブでした。BUSINESS_DOWNGRADE: この番号は一般向けの WhatsApp アプリに登録されていました。CHANGE_NUMBERとUSER_RE_REGISTERED: 顧客が番号を変更したか、新しいデバイスで再登録しました。
ステータスイベントにはどのヘッダーが付きますか?
すべての試行で 5 つのヘッダーが付きます。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 時間まで間隔を広げながら、合計 7 回、約 33 時間かけて再試行され、その後破棄されます。配信先は、パブリック IP に解決される HTTPS アドレスに限られます。エンドポイントが設定されていない間に発生したイベントはキューに入れられず、エンドポイントを削除すると、保留中のものもすべて停止します。
同じ id を一度だけ処理し、occurred_at を確認するのはなぜですか?
再試行は、本文と X-EC-Delivery の両方で同じ id を持つ配信を完全に繰り返すためです。また、再試行されたイベントが新しいイベントより後に届くことがあるためです。処理した id を保存し、重複はスキップしてください。そのうえで、occurred_at を、その接続について記録した最後の状態と比較してください。古い可能性のあるイベントに基づいて行動する前には、GET /connections/{id} または GET /channels/{id} を読み取ってください。
番号が切断されたとき、プラットフォームは何をすべきですか?
理由に基づいて行動してください。PRIMARY_INACTIVITY の後は、顧客に WhatsApp Business アプリを開いてもらい、同じ番号の新しい connect セッションを送ってください。同じ WhatsApp Business Account で再接続すると、接続 ID は保持され、Webhook の送信先が元に戻り、connection.connected が送信されます。その後、認証情報を再度読み取ってください。connection.token_missing は、その実行で Meta がトークンを発行しなかったことを意味します。切断につながる account_update は、アプリ自身のコールバックにのみ Meta から送られ、お客様の URL には送られません。そのため、このイベントがプラットフォームに切断を知らせる手段になります。
ソーシャルアカウントが切断されたとき、プラットフォームは何をすべきですか?
channel.disconnected を受け取ったら、同じチャネルの新しい connect セッションで、同じ channel ID のままアカウントを再度サインインさせてください。channel.removed はアクセスがなくなったことを意味します。トークンは破棄され、Webhook の送信先もクリアされるため、顧客が再接続した際には送信先を再度設定してください。停止された番号またはチャネルは、サブスクリプションが再び有効になった後に再接続すると復帰します。
よくある間違い
- 再試行を新しいイベントとして扱うこと。本文と X-EC-Delivery に同じ id が含まれるため、処理済みの id を記録してください。そうしないと、1 回の切断で顧客に 2 度アラートが届くことがあります。
- 到着順にイベントを適用すること。再試行されたイベントは新しいイベントの後に届くことがあるため、occurred_at を比較するか、行動する前に接続を読み取ってください。
- バックエンドを更新せずに、タイプミスを直すためイベント URL を再保存すること。保存すると新しい署名シークレットが発行されるため、エンドポイントがそれを使うようになるまで、すべての配信で署名検証に失敗します。
- 応答する前に処理を行うこと。10 秒を超えるハンドラーは失敗とみなされ、イベントは再送されます。そのため、先に 2xx で応答し、その後で処理してください。
easyCoexistence は、顧客の WhatsApp 番号とソーシャルアカウントを 24 時間体制で監視し、接続、切断、削除、停止が起きるたびに署名付きのイベントをプラットフォームに送信します。番号が切断された場合は、Meta の理由も含まれます。接続 1 件あたり月額 US$ 9 から、接続を増やすほど下がり US$ 0.75 まで。最初の 3 日間は無料です。
よくある質問
PRIMARY_INACTIVITY とはどういう意味ですか?
WhatsApp Business アプリがプライマリデバイスで約 14 日間使われなかったため、Coexistence 番号の接続を切断したことを示す Meta の理由です。その顧客の新しい connect セッションで、番号を再接続できます。
ステータスイベントにはメッセージが含まれますか?
いいえ。ステータスイベントは接続の状態を扱います。番号のメッセージは Meta から、その番号自身の Webhook 送信先に送られ、ソーシャルのコメントと DM は各チャネルの送信先に送られます。
イベント URL はどこで設定しますか?
ダッシュボードの「Profile」、「Developers」の順に進むか、MCP ツール set_partner_events_url を使用してください。署名シークレットは 1 度だけ表示され、URL を再保存すると新しいものが発行されます。
番号だけを扱う場合、channel イベントは無視してよいですか?
はい。channel.* イベントには独自の名前があり、connection の代わりに channel オブジェクトを持つため、名前が connection で始まらないイベントは受信側でスキップできます。
続きを読む
最初のチャンネルを 2 分で接続しましょう。
プラットフォームの審査を待つ必要はありません。WhatsApp、Instagram、TikTok などのチャンネルを接続して、AI に投稿、返信、レポートを任せてみてください。
- 3 日間無料
- いつでも解約可能
- 公式 API のみ使用
- 24/7 監視
確認日