User preferences webhoooks

This reference describes trigger events and payload contents for the WhatsApp Business Account user_preferences webhook.

WhatsApp users can use the Offers and announcements setting to stop or resume marketing template messages from individual businesses, which can trigger a user_preferences webhook.

See the following documents to learn more about this setting:

Cloud API: User preferences for marketing messages
On-Premises API: User preferences for marketing messages

Triggers

A WhatsApp user stops marketing messages.
A WhatsApp user resumes marketing messages.

Cloud API syntax

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "",
              "phone_number_id": ""
            },
            "contacts": [
              {
                "profile": {
                  "name": ""
                },
                "wa_id": ""
              }
            ],
            "user_preferences": [
              {
                "wa_id": "",
                "detail": "",
                "category": "marketing_messages",
                "value": "",
                "timestamp": 
              }
            ]
          },
          "field": "user_preferences"
        }
      ]
    }
  ]
}

Cloud API parameters

Placeholder	Description	Example value
String	Business display phone number.	`15550783881`
String	Business phone number ID.	`106540352242922`
String	Marketing message preference. Values can be: `stop` `resume`	`stop`
String	Description of marketing message preference. Values can be: `User requested to stop marketing messages` `User requested to resume marketing messages`	`User requested to stop marketing messages`
Integer	Unix timestamp indicating when the webhook was triggered.	`1739321024`
String	WhatsApp Business Account ID.	`102290129340398`
String	WhatsApp user ID.	`16505551234`
String	WhatsApp user's name as it appears in their profile in the WhatsApp client.	`Sheena Nelson`

Cloud API example

{
  "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_preferences": [
              {
                "wa_id": "16505551234",
                "detail": "User requested to resume marketing messages",
                "category": "marketing_messages",
                "value": "resume",
                "timestamp": 1731705721
              }
            ]
          },
          "field": "user_preferences"
        }
      ]
    }
  ]
}

On-Premises API syntax

{
  "contacts": [
    {
      "profile": {
        "name": ""
      },
      "wa_id": ""
    }
  ],
  "messages": [
    {
      "from": "",
      "id": "",
      "system": {
        "body": "",
        "marketing": "",
        "type": "user_preference_changed"
      },
      "timestamp": ,
      "type": "system"
    }
  ]
}

On-Premises API parameters

Placeholder	Description	Example value
String	Marketing message preference. Values can be: `stop` `resume`	`stop`
String	Description of marketing message preference. Values can be: `chose to stop receiving marketing messages on WhatsApp from your business` `chose to resume receiving marketing messages on WhatsApp from your business`	`+16505551234 requested to stop marketing messages`
Integer	Unix timestamp indicating when the webhook was triggered.	`1739321024`
String	WhatsApp message ID.	`wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=`
String	WhatsApp user ID.	`16505551234`
String	WhatsApp user's name as it appears in their profile in the WhatsApp client.	`Sheena Nelson`
String	WhatsApp user phone number.	`+16505551234`

On-Premises API example

{
  "contacts": [
    {
      "profile": {
        "name": "Sheena Nelson"
      },
      "wa_id": "16505551234"
    }
  ],
  "messages": [
    {
      "from": "+16505551234",
      "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
      "system": {
        "body": "+16505551234 requested to stop marketing messages",
        "marketing": "stop",
        "type": "user_preference_changed"
      },
      "timestamp": 1739321024,
      "type": "system"
    }
  ]
}