user_preferences webhook reference

Updated: Aug 13, 2026

Copy for LLM

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

The user_preferences webhook notifies you of changes to a WhatsApp user’s marketing message preferences.

Triggers

A WhatsApp user stops marketing messages.

A WhatsApp user resumes marketing messages.

Note: This webhook triggers only when a user stops or resumes marketing messages. It does not trigger when a user indicates Interested or Not interested feedback through the Offers and announcements setting.

Syntax

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<WHATSAPP_USER_NAME>"
                },
                "wa_id": "<WHATSAPP_USER_ID>",
                "user_id": "<BSUID>",
                "parent_user_id": "<PARENT_BSUID>"
              }
            ],
            "user_preferences": [
              {
                "wa_id": "<WHATSAPP_USER_ID>",
                "user_id": "<BSUID>",
                "parent_user_id": "<PARENT_BSUID>",
                "detail": "<PREFERENCE_DESCRIPTION>",
                "category": "marketing_messages",
                "value": "<PREFERENCE>",
                "timestamp": <WEBHOOK_SENT_TIMESTAMP>
              }
            ]
          },
          "field": "user_preferences"
        }
      ]
    }
  ]
}

wa_id is omitted if the user has enabled the username feature and their phone number cannot be shared with you. user_id is omitted if business-scoped user IDs are not enabled for your business. parent_user_id is omitted unless you have enabled parent BSUIDs.

Note:parent_user_id is included for identification only. It is not used to apply user preferences, and a preference is never applied at the parent BSUID level.

Parameters

Placeholder	Description	Example value
`<BSUID>` String	The user’s business-scoped user ID. Omitted if business-scoped user IDs are not enabled for your business.	`US.13491208655302741918`
`<BUSINESS_DISPLAY_PHONE_NUMBER>` String	Business display phone number.	`15550783881`
`<BUSINESS_PHONE_NUMBER_ID>` String	Business phone number ID.	`106540352242922`
`<PARENT_BSUID>` String	The user’s parent business-scoped user ID. Omitted unless you have enabled parent business-scoped user IDs.	`US.ENT.506847293015824`
`<PREFERENCE>` String	Marketing message preference. Values can be: `stop` — Indicates the WhatsApp user has opted to stop receiving marketing messages from you. `resume` — Indicates the WhatsApp user has opted to resume receiving marketing messages from you.	`stop`
`<PREFERENCE_DESCRIPTION>` 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`
`<WEBHOOK_TRIGGER_TIMESTAMP>` Integer	Unix timestamp indicating when the webhook was triggered.	`1739321024`
`<WHATSAPP_BUSINESS_ACCOUNT_ID>` String	WhatsApp Business Account ID.	`102290129340398`
`<WHATSAPP_USER_ID>` String	WhatsApp user ID. Note that a WhatsApp user’s ID and phone number may not always match.	`16505551234`
`<WHATSAPP_USER_PROFILE_NAME>` String	WhatsApp user’s name as it appears in their profile in the WhatsApp client.	`Sheena Nelson`

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_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"
        }
      ]
    }
  ]
}