System messages webhook reference

Updated: Aug 11, 2026

Copy for LLM

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

Unlike other incoming messages webhooks, system messages webhooks don’t include a contacts array.

Triggers

A WhatsApp user changes their WhatsApp phone number.

A WhatsApp user’s business-scoped user ID (BSUID) changes.

The type value tells you which identifier changed and what the notification includes:

user_changed_number — the user changed their phone number and the new number can be shared with you. The notification includes the new phone number.

user_changed_user_id — the user’s BSUID changed. The notification reports only the BSUID change; no phone number is included.

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>"
            },
            "messages": [
              {
                "from": "<WHATSAPP_USER_PHONE_NUMBER>",
                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<WEBHOOK_TRIGGER_TIMESTAMP>",
                "type": "system",
                "system": {
                  "body": "User <WHATSAPP_USER_PROFILE_NAME> changed from <WHATSAPP_USER_PHONE_NUMBER> to <NEW_WHATSAPP_USER_PHONE_NUMBER>",
                  "wa_id": "<NEW_WHATSAPP_USER_ID>",
                  "type": "<SYSTEM_CHANGE_TYPE>",
                  "user_id": "<NEW_BSUID>",
                  "parent_user_id": "<NEW_PARENT_BSUID>",
                  "previous_user_id": "<PREVIOUS_BSUID>",
                  "previous_parent_user_id": "<PREVIOUS_PARENT_BSUID>"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

wa_id and from are omitted if the user has enabled the username feature and their phone number cannot be shared with you. parent_user_id and previous_parent_user_id are omitted unless you have enabled parent BSUIDs. previous_user_id and previous_parent_user_id are omitted when the user’s previous BSUID is unavailable.

Parameters

Placeholder	Description	Example value
`<BUSINESS_DISPLAY_PHONE_NUMBER>` String	Business display phone number.	`15550783881`
`<BUSINESS_PHONE_NUMBER_ID>` String	Business phone number ID.	`106540352242922`
`<NEW_BSUID>` String	The user’s current business-scoped user ID. Omitted if business-scoped user IDs are not enabled for your business.	`US.13491208655302741918`
`<NEW_PARENT_BSUID>` String	The user’s current parent business-scoped user ID. Omitted unless you have enabled parent business-scoped user IDs.	`US.ENT.506847293015824`
`<NEW_WHATSAPP_USER_ID>` String	New WhatsApp user ID. A WhatsApp user’s ID and phone number may not match.	`12195555358`
`<NEW_WHATSAPP_USER_PHONE_NUMBER>` String	New WhatsApp user phone number. A WhatsApp user’s phone number and ID may not match.	`12195555358`
`<PREVIOUS_BSUID>` String	The business-scoped user ID the user had before the change. Omitted when it is unavailable.	`US.10230984751029384756`
`<PREVIOUS_PARENT_BSUID>` String	The parent business-scoped user ID the user had before the change. Omitted when it is unavailable or you have not enabled parent business-scoped user IDs.	`US.ENT.918273645500112`
`<SYSTEM_CHANGE_TYPE>` String	Type of system message. `user_changed_number` if the user changed their phone number and the new number can be shared with you. `user_changed_user_id` if the user’s business-scoped user ID changed; no phone number is included in that case.	`user_changed_number`
`<WEBHOOK_TRIGGER_TIMESTAMP>` String	Unix timestamp indicating when the webhook was triggered.	`1739321024`
`<WHATSAPP_BUSINESS_ACCOUNT_ID>` String	WhatsApp Business Account ID.	`102290129340398`
`<WHATSAPP_MESSAGE_ID>` String	WhatsApp message ID.	`wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=`
`<WHATSAPP_USER_PHONE_NUMBER>` String	WhatsApp user phone number. A WhatsApp user’s phone number and ID may not match.	`16505551234`
`<WHATSAPP_USER_PROFILE_NAME>` String	WhatsApp user’s name as it appears in their profile in the WhatsApp client.	`Sheena Nelson`

Example

A WhatsApp user changed their phone number, and the new number can be shared with you:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "messages": [
              {
                "from": "16505551234",
                "id": "wamid.HBgLMTk4MzU1NTE5NzQVAgASGAoxMTgyMDg2MjY3AA==",
                "timestamp": "1750269342",
                "system": {
                  "body": "User Sheena Nelson changed from 16505551234 to 12195555358",
                  "wa_id": "12195555358",
                  "type": "user_changed_number",
                  "user_id": "US.13491208655302741918",
                  "parent_user_id": "US.ENT.506847293015824",
                  "previous_user_id": "US.10230984751029384756",
                  "previous_parent_user_id": "US.ENT.918273645500112"
                },
                "type": "system"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

A WhatsApp user’s business-scoped user ID changed, and no phone number can be shared with you:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "messages": [
              {
                "id": "wamid.HBgLMTk4MzU1NTE5NzQVAgASGAoxMTgyMDg2MjY3AA==",
                "timestamp": "1750269342",
                "system": {
                  "body": "User changed from US.10230984751029384756 to US.13491208655302741918",
                  "type": "user_changed_user_id",
                  "user_id": "US.13491208655302741918",
                  "parent_user_id": "US.ENT.506847293015824",
                  "previous_user_id": "US.10230984751029384756",
                  "previous_parent_user_id": "US.ENT.918273645500112"
                },
                "type": "system"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}