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

Cloud API 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_preferences": [
              {
                "wa_id": "<WHATSAPP_USER_ID>",
                "detail": "<PREFERENCE_DESCRIPTION>",
                "category": "marketing_messages",
                "value": "<PREFERENCE>",
                "timestamp": <WEBHOOK_SENT_TIMESTAMP>
              }
            ]
          },
          "field": "user_preferences"
        }
      ]
    }
  ]
}

Cloud API parameters

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": "<WHATSAPP_USER_NAME>"
      },
      "wa_id": "<WHATSAPP_USER_ID>"
    }
  ],
  "messages": [
    {
      "from": "<WHATSAPP_USER_PHONE_NUMBER>",
      "id": "<WHATSAPP_MESSAGE_ID>",
      "system": {
        "body": "<PREFERENCE_DESCRIPTION>",
        "marketing": "<PREFERENCE>",
        "type": "user_preference_changed"
      },
      "timestamp": <WEBHOOK_TRIGGER_TIMESTAMP>,
      "type": "system"
    }
  ]
}

On-Premises API parameters

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