ログイン無料トライアルを開始
Meta Tech Provider

WhatsApp user_preferences Webhook: 顧客がマーケティングメッセージを停止・再開したとき

user_preferences Webhook は、WhatsApp ユーザーが「オファーとお知らせ」設定でマーケティングメッセージを停止または再開したことを、企業に通知します。各イベントには、カテゴリ marketing_messages、値 stop または resume、詳細の文、ユーザーの wa_id と BSUID、Unix タイムスタンプが含まれます。同じ設定にある「興味あり」「興味なし」のフィードバックでは送信されません。

easyCoexistence は、お使いの WhatsApp Business アプリの番号を Coexistence 経由で Meta の Cloud API に接続するため、アプリに保持したままの番号で AI や自動化を動かせます。

2

設定できる値は stop と resume の 2 種類で、どちらも marketing_messages カテゴリに属します。

131050

マーケティング用メッセージテンプレートを、マーケティングメッセージを停止したユーザーに送った場合の失敗ステータスコードです。

Default callback

Meta による user_preferences の送信先は、WhatsApp Business Account や番号単位で上書きできません。

whatsapp_business_management

messages と calls 以外の Webhook(user_preferences を含む)にアプリが必要とする権限。

user_preferences Webhook はどのような場合に送信されますか?

顧客が「オファーとお知らせ」で、企業からのマーケティングメッセージを停止または再開すると送信されます。この 2 つの操作だけがトリガーです。同じ設定の「興味あり」「興味なし」の選択では Webhook は送信されません。ただし「興味なし」は、そのユーザーとの間のユーザーごとのマーケティング送信上限を引き下げることがあり、マーケティングメッセージをすべて停止するかを尋ねる 2 つ目の画面も開きます。その画面で停止をタップした場合に限り、user_preferences が送信されます。

ペイロードにはどのような内容が含まれますか?

contacts 配列と並んで、フィールド名 user_preferences の下に user_preferences 配列が含まれます。ここでの timestamp は整数ですが、ステータス Webhook では文字列で送られます。wa_id は、顧客がユーザー名を使っていて電話番号を共有できない場合に省略されます。user_id は、企業スコープのユーザー ID が有効でない場合に、parent_user_id は親 BSUID が有効でない限り省略されます。以下は再開時の Meta の例です。

Meta's example: a customer resumes marketing messages
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "wa_id": "16505551234",
                "user_id": "US.13491208655302741918",
                "parent_user_id": "US.ENT.506847293015824"
              }
            ],
            "user_preferences": [
              {
                "wa_id": "16505551234",
                "user_id": "US.13491208655302741918",
                "parent_user_id": "US.ENT.506847293015824",
                "detail": "User requested to resume marketing messages",
                "category": "marketing_messages",
                "value": "resume",
                "timestamp": 1731705721
              }
            ]
          },
          "field": "user_preferences"
        }
      ]
    }
  ]
}

顧客が停止した場合、システムはどう対応すべきですか?

その顧客に対して停止を記録し、再開の通知を受けるまで、すべてのマーケティング送信から除外してください。detail フィールドには「User requested to stop marketing messages」または「User requested to resume marketing messages」という文が入りますが、コードが読むべきなのは value です。

  • BSUID と電話番号の両方で設定を保存してください。どちらも、イベントによっては欠けていることがあるためです。
  • マーケティングメッセージテンプレートの送信対象から顧客を除外してください。除外しなくても、Meta は 131050 により送信を拒否します。
  • 設定は顧客単位でのみ適用してください。Meta は親 BSUID レベルでは停止設定を適用しません。
  • 再開を受けたら除外を解除し、Meta のオプトインポリシーで求められるとおり、自社のオプトイン記録は保持してください。

user_preferences がサーバーに届かない場合はどうなりますか?

Meta は停止を必ず適用します。そのため、Webhook が欠けても失敗した送信が発生するだけで、ポリシー違反にはなりません。停止した顧客にマーケティングテンプレートを送ると、API はリクエストを受け付けますがメッセージは送信されず、ステータス failed、コード 131050、title「Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business」のステータス Webhook が送信されます。この失敗を停止イベントと同じように扱い、記録したうえで、その顧客へのマーケティング送信を今後止めてください。

easyCoexistence で接続した番号ではどう動きますか?

user_preferences は、Meta が送信先の上書きを許可しているフィールドには含まれません。そのため、Meta はアカウントを購読しているアプリのデフォルトのコールバックにのみ送信します。easyCoexistence で接続した番号の場合、そのアプリは easyCoexistence のものであり、現時点では user_preferences を購読していません。したがって、このイベントは直接の送信先にも Forward URL にも届きません。131050 の失敗ステータスは messages フィールドで送られるため、届きます。

AI が send_template でマーケティングテンプレートを送る場合は、停止リストを自社システムで管理し、送信前に確認してください。easyCoexistence は停止リストを保持していません。

よくある間違い

  • 「興味なし」を停止として扱うこと。Webhook は送信されず、配信も止まりませんが、その顧客へのマーケティング上限は下がることがあります。
  • wa_id だけで設定を管理すること。ユーザー名を使い電話番号を共有できない顧客では wa_id が省略されます。BSUID も保存してください。
  • 親 BSUID 配下のすべての顧客に停止を適用すること。Meta は設定をユーザー単位で適用し、親レベルでは適用しません。
  • 131050 の後に再試行し、停止として記録しないこと。再試行はいずれも同じように失敗します。
EasyCoexistence で実現する

この経路で送信されるマーケティングテンプレートは、お客様自身の WhatsApp Business Account から送信されます。停止した顧客を示す失敗ステータスは、サーバーに直接、または署名付きの転送として届きます。接続済みの番号 1 件あたり月額 US$ 9 から、番号を増やすほど下がり US$ 0.75 まで。最初の 3 日間は無料トライアルです。

よくある質問

停止は、顧客自身のメッセージへの返信もブロックしますか?

Meta のドキュメントでは、停止はマーケティングメッセージを対象とすると説明されており、返されるエラーもマーケティングメッセージを名指ししています。顧客が企業に送ったメッセージへの返信は、別のカテゴリであるサービスメッセージです。

企業のブロックは user_preferences をトリガーしますか?

いいえ。Webhook は「オファーとお知らせ」設定での停止と再開にのみ反応します。ブロックは別の操作であり、このフィールドでは報告されません。

再開はオプトインに該当しますか?

顧客がマーケティングメッセージを再び受け取ることを選んだという意味です。Meta のポリシーに基づく自社のオプトイン義務は引き続き適用されるため、その顧客がいつ、どのように同意したかの記録を保管してください。

どの Webhook フィールドを購読すればよいですか?

user_preferences です。アプリのダッシュボードの WhatsApp > Configuration で、WhatsApp Business Account を購読しているアプリに対して設定します。messages とは別のフィールドで、whatsapp_business_management が必要です。

続きを読む

始める準備はできましたか?

WhatsApp Coexistence の設定は数分で完了し、数か月もかかりません。スマートフォン上のアプリも引き続き使えます。

無料トライアルを始める

確認日