WhatsApp user_preferences Webhook: 顧客がマーケティングメッセージを停止・再開したとき
user_preferences Webhook は、WhatsApp ユーザーが「オファーとお知らせ」設定でマーケティングメッセージを停止または再開したことを、企業に通知します。各イベントには、カテゴリ marketing_messages、値 stop または resume、詳細の文、ユーザーの wa_id と BSUID、Unix タイムスタンプが含まれます。同じ設定にある「興味あり」「興味なし」のフィードバックでは送信されません。
easyCoexistence は、お使いの WhatsApp Business アプリの番号を Coexistence 経由で Meta の Cloud API に接続するため、アプリに保持したままの番号で AI や自動化を動かせます。
設定できる値は stop と resume の 2 種類で、どちらも marketing_messages カテゴリに属します。
マーケティング用メッセージテンプレートを、マーケティングメッセージを停止したユーザーに送った場合の失敗ステータスコードです。
Meta による user_preferences の送信先は、WhatsApp Business Account や番号単位で上書きできません。
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 の例です。
{
"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 の後に再試行し、停止として記録しないこと。再試行はいずれも同じように失敗します。
この経路で送信されるマーケティングテンプレートは、お客様自身の 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 の設定は数分で完了し、数か月もかかりません。スマートフォン上のアプリも引き続き使えます。
無料トライアルを始める確認日