Receive notifications

Last update: 6 hours ago by Irais Aguirre

The platform forwards inbound WhatsApp events — messages, delivery statuses, group and Flows events, and calls — to your webhook.

The platform sends you the following types of notifications:

Messages, files, locations, and contacts sent by your customer, in the following scenarios:
- a. In reply to a message sent from your platform.
- b. When your customer starts the conversation.
Status of the messages you sent. You are notified of one of the following statuses:
- a. Sent: The message was sent successfully.
- b. Delivered: The message was delivered to your customer.
- c. Read: Your customer read the message.
- d. Failed: The message could not be sent to your customer.
- e. Deleted: Your customer deleted the message.
Contact registration status (see section 2), if the service returned the processing status.
Group events: group creation and deletion, participant changes, join requests, group settings, and group suspension (see Groups).
Flows events: Flow status changes and alerts for its endpoint (see Flows).
Call events (see Calling API) and, in general, any other Meta event is forwarded as-is to your webhook.

Considerations:

You may receive duplicate notifications.

Pages in this section:

Webhook: how notifications are delivered and what your webhook must respond.
Message notifications: general structure and text, audio, document, image, location, video, voice message, sticker, and shared contact messages.
Interactive replies: quick replies, shopping cart, and WhatsApp Flows replies.
Status notifications: status of the messages you sent.
User changed phone number: system notification when the user's phone number or BSUID changes.
Group notifications: group events and status of messages sent to a group.
Flows notifications: Flow status changes and alerts.

Usernames and BSUID

WhatsApp lets users set a username (for example, @testusername) that's shown in the app instead of their phone number. Once a user turns it on, their phone number may stop appearing in notifications.

So that you can always identify the user, Meta assigns every user a business-scoped user ID (BSUID):

Meta generates it automatically, and it's always included in messaging notifications, whether or not the user has a username.
Format: an ISO 3166 alpha-2 country code, a dot, and up to 128 alphanumeric characters. For example, US.13491208655302741918.
It's only valid for business phone numbers in the same business portfolio. If you use a BSUID with a number from another portfolio, the message isn't delivered.
If the user changes their phone number, their BSUID is regenerated and you receive a system notification (see User changed phone number).
If the business has linked portfolios, you also receive a parent BSUID (parent_user_id), for example, US.ENT.506847293015824.

When the phone number is included

If the user doesn't have a username, you always receive both their phone number and their BSUID. If they do have one, the phone number is only included when at least one of these is true:

The business messaged or called the user's phone number in the last 30 days.
The user messaged or called the business in the last 30 days.
The user is in the business's contact book.

These conditions are evaluated for each business phone number.

How to identify the user

Incoming messages: use from (phone number) if it's present; otherwise, use from_user_id (BSUID).
Status of sent messages: use recipient_id (phone number) if it's present; otherwise, use recipient_user_id (BSUID).

Store the BSUID from the first message so you can keep identifying the user even if they turn on a username or change their number.

Sending messages with a BSUID

The to field accepts either a phone number or a BSUID; the service detects which one you're using. Use the phone number when you know it, and the BSUID when the user doesn't share their number.

You can't use a BSUID with one-tap, zero-tap or copy code authentication templates; those require a phone number.