account_update Webhook と切断理由の全一覧

account_update にはどのようなイベントが含まれますか？

アカウントから WhatsApp Business アプリがアンインストールされたときは、PARTNER_REMOVED が送られます。これは正式な切断シグナルです。フィールドが false になったことから切断を推測するより、このイベントを基に処理してください。

番号が完全に利用停止されたときは ACCOUNT_OFFBOARDED、以前削除された接続が復旧したときは ACCOUNT_RECONNECTED が送られます。さらに、ACCOUNT_RESTRICTION や ACCOUNT_VIOLATION などの措置イベントと、名前に DISABLED または BAN を含むイベントもあります。

認証や承認の結果もここに届き、イベント名には VERIFIED または APPROVED が含まれます。ハンドラーはイベント名で分岐し、認識できないイベントは失敗させず情報として扱ってください。Meta は予告なくイベントを追加するためです。

切断理由にはどのようなものがありますか？

6 つあり、それぞれ意味が大きく異なります。

PRIMARY_INACTIVITY は、WhatsApp Business アプリがプライマリデバイスで約 14 日間開かれなかった場合です。復旧可能で、最もよく発生します。

COMPANION_INACTIVITY はコンパニオンデバイスでの同様の非アクティブ状態で、期間は約 30 日間と長めです。

BUSINESS_DOWNGRADE は、番号が一般向け WhatsApp アプリに戻ったことを示します。Business アプリが必要な Coexistence は終了します。

CHANGE_NUMBER は電話番号自体が変更された場合です。USER_RE_REGISTERED は新しいデバイスで再登録された場合です。ACCOUNT_DISCONNECTED は利用者が意図的に切断したか、措置によって切断された場合です。

この理由は disconnection_info.initiated_by とともに届き、利用者とシステムのどちらが実行したかを示します。

イベントより理由が重要なのはなぜですか？

PARTNER_REMOVED だけでは、どのように対応すべきか分からないためです。

PRIMARY_INACTIVITY による削除なら、番号は復旧します。企業がアプリを開いて再接続すれば、すべて再開します。これを顧客の離脱として扱うと、今も顧客である相手に解約メールを送ることになります。

BUSINESS_DOWNGRADE や ACCOUNT_DISCONNECTED による削除は別の状況です。一時的なものとして扱うと、接続がいつまでも保留状態に残ります。

理由なしで削除が届いた場合は、initiated_by が代替シグナルになります。利用者が実行した削除なら意図的と判断できますが、理由不明のシステムによる削除はそうとは限りません。この違いは、後でサポート対応に任せるのではなく、コードで判定する価値があります。

よくある間違い

• すべての PARTNER_REMOVED を同じように扱うこと。理由によって、2 週間の停止なのか顧客の離脱なのかが分かれます。
• このイベントではなく、フィールドが false になったことから切断を推測すること。それが誤アラートの原因になります。
• 認識できないイベント名で処理を失敗させること。Meta はイベントを追加するため、ハンドラーは未知のイベントをスキップしてください。

よくある質問

続きを読む