Event catalogue

User preferences

A customer changed their marketing-message preference. One event per item in user_preferences, with that item's wa_id and user_id on the envelope. A failed status with error 131050 also produces this

A customer changed their marketing-message preference. One event per item in user_preferences, with that item's wa_id and user_id on the envelope. A failed status with error 131050 also produces this type, with data.kind: "error_signal" (see Message status). Routed by phone number.

Event type: user.preferences. Fixture payloads are the WhaBuzz Demo tenant's real ids with a fictional customer number; id, tenant_id and created_at in envelopes are illustrative.

#Customer stopped, then resumed, marketing messages

What Meta POSTs to WhaBuzz (fixtures/meta/user_preferences_stop_resume.json):

json

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "26059971920328384",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "14692311132",
              "phone_number_id": "1013622581841046"
            },
            "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 stop marketing messages",
                "category": "marketing_messages",
                "value": "stop",
                "timestamp": 1731705700
              },
              {
                "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"
        }
      ]
    }
  ]
}

What your endpoint receives (event 1 of 2, entry[0].changes[0].value.user_preferences[0]), as the body of a signed POST. raw is abbreviated here; on the wire it is the full body above.

json

{
  "id": "evt_01JAB3K9X2S8C4M7Q1V5R6T0YZ",
  "type": "user.preferences",
  "api_version": "2026-10-16",
  "created_at": "2024-11-15T21:21:40.481Z",
  "tenant_id": "a578246e-b97f-48e6-ae42-939ec3ccf917",
  "waba_id": "26059971920328384",
  "phone_number_id": "1013622581841046",
  "display_phone_number": "14692311132",
  "wamid": null,
  "wa_id": "16505551234",
  "user_id": "US.13491208655302741918",
  "dedupe_key": "user_preferences:<sha256 of the canonical number and item>",
  "data": {
    "messaging_product": "whatsapp",
    "metadata": {
      "display_phone_number": "14692311132",
      "phone_number_id": "1013622581841046"
    },
    "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 stop marketing messages",
        "category": "marketing_messages",
        "value": "stop",
        "timestamp": 1731705700
      }
    ],
    "field": "user_preferences"
  },
  "raw": {
    "…": "the complete Meta POST body, byte for byte, as shown above"
  },
  "raw_path": "entry[0].changes[0].value.user_preferences[0]"
}

What your endpoint receives (event 2 of 2, entry[0].changes[0].value.user_preferences[1]), as the body of a signed POST. raw is abbreviated here; on the wire it is the full body above.

json

{
  "id": "evt_01JAB3K9X2S8C4M7Q1V5R6T0YZ",
  "type": "user.preferences",
  "api_version": "2026-10-16",
  "created_at": "2024-11-15T21:22:01.481Z",
  "tenant_id": "a578246e-b97f-48e6-ae42-939ec3ccf917",
  "waba_id": "26059971920328384",
  "phone_number_id": "1013622581841046",
  "display_phone_number": "14692311132",
  "wamid": null,
  "wa_id": "16505551234",
  "user_id": "US.13491208655302741918",
  "dedupe_key": "user_preferences:<sha256 of the canonical number and item>",
  "data": {
    "messaging_product": "whatsapp",
    "metadata": {
      "display_phone_number": "14692311132",
      "phone_number_id": "1013622581841046"
    },
    "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"
  },
  "raw": {
    "…": "the complete Meta POST body, byte for byte, as shown above"
  },
  "raw_path": "entry[0].changes[0].value.user_preferences[1]"
}

This page as Markdown: /events/user-preferences.md. All docs in one file: /llms-full.txt. Status.

Start

Guides

API reference

Webhook events

Reference

User preferences

#Customer stopped, then resumed, marketing messages