WhatsApp Webhook フィールドと送信先

各フィールドは何を運びますか？

messages は、顧客が番号に送信するすべての内容を運びます。テキスト、メディア参照、返信、リアクションが含まれます。smb_message_echoes は、チームが WhatsApp Business アプリから送信した内容を運びます。このフィールドは Coexistence 番号にのみ存在し、ソフトウェアが人間の返信を認識するために使われます。

account_update は接続状態を運びます。アプリがアカウントからアンインストールされたときの PARTNER_REMOVED、ACCOUNT_OFFBOARDED、ACCOUNT_RECONNECTED、制限や違反のイベントが含まれます。phone_number_quality_update は品質評価とスループットの変更を運びます。account_alerts は Meta がアカウントに対して発生させたアラートを運び、account_review_update は審査結果を運びます。

business_capability_update はメッセージ上限と機能の変更を運び、phone_number_name_update は表示名の承認と却下を運びます。

この分岐はアーキテクチャ上なぜ重要ですか？

会話内容がプロバイダーに届くかどうかを決めるためです。

上書き設定により、2 つのメッセージフィールドは Meta から直接エンドポイントに送信されます。6 つの運用フィールドは引き続きプロバイダーに送信されるため、誰もメッセージを保持せずにダッシュボードとアラート機能を実現できます。

そのため、「メッセージを保存しない」という説明は、ポリシーではなく構造に基づく場合があります。メッセージフィールドが別の場所に配信されるなら、それを保存できるコード経路はありません。この場合、上書き設定のないアカウントはデフォルトのコールバックに戻り、ハンドラーはイベントを永続化せずに破棄します。

ハンドラーはどのフィールドを想定すべきですか？

上書き設定がある場合は、2 つのメッセージフィールドだけです。それ以外のフィールドは、エラーにするのではなく無視するようハンドラーを実装するのが適切です。

Meta は時間とともにフィールドを追加するため、ペイロードの形に予告なくキーが増えることがあります。フィールド名で分岐し、認識できないものを無視するハンドラーなら動作し続けます。形を固定して想定するハンドラーは、初めて見たイベントでエラーになります。

smb_message_echoes も、ノイズとして扱わず明示的に処理する価値があります。これがないと、ソフトウェアは人間がすでに返信したことを把握できません。その結果、顧客が同じ質問に対する返信を 2 つ受け取ることになります。

よくある間違い

• 一般的なペイロードだと考える。すべてのイベントにはフィールド名があり、ハンドラーはそれで分岐すべきです。
• smb_message_echoes を無視する。これがないと、ソフトウェアはすでに返信した人間の上から返信します。
• 認識できないフィールドをスキップせずエラーにする。Meta は確認なくフィールドを追加します。

よくある質問

続きを読む