Webhooks have a top level array field indicating what is being communicated. The members of the array are JSON objects with detailed fields relevant to the Webhook.
WhatsApp Business Management API webhooks can contain the following objects:
Parameter | Description |
---|---|
|
This is the object that was subscribed to. For embedded signup
, this is always |
This object contains the details of the change that triggered the webhooks call. |
entry
ObjectParameter | Description |
---|---|
|
ID of Whatsapp Business Accounts this webhook belongs to. |
|
Time for the entry. |
|
Changes that triggered the webhooks call —see |
changes
field
Contains the type of notification you are getting on that webhook.
Supported Values
account_alerts
account_review_update
account_update
business_capability_update
message_template_quality_update
message_template_status_update
phone_number_name_update
phone_number_quality_update
security
template_category_update
value
Contains details of the changes related to the specified field
—see value
object
.
value
ban_info
Added to webhooks when an account has been banned. This object includes two properties:
waba_ban_state
: Options are: DISABLE
REINSTATE
SCHEDULE_FOR_DISABLE
waba_ban_date
current_limit
Contains the current tier limit where this account is.
Supported Values
TIER_50
TIER_250
TIER_1K
TIER_10K
TIER_100K
TIER_UNLIMITED
decision
Used if a decision about accounts or phone numbers has been made.
Supported Values
APPROVED
REJECTED
display_phone_number
Includes the display phone number of the business account account that triggered the notification.
event
Used when an event happened in a specific WABA. Click the arrow on the left column to see all available options.
Display name updates
APPROVED
: The review was approved. If a business was previously unable to download their certificate, that business should now be able to use their display name by downloading the certificate.DEFERRED
: The review is deferred and the business can use their display name by downloading the certificate.REJECTED
: The review was rejected, with the given rejection reason. If a business was previously unable to download their certificate, that business needs to reapply for a display name review to get access to the certificate. If a business is already using their certificate, the display name review rejection does not affect their operation. However, passing the review is necessary for the business to grow its message and account limits.Message template quality update
Previous quality score:
GREEN
RED
UNKNOWN
YELLOW
New quality score:
GREEN
RED
UNKNOWN
YELLOW
Message template status updates
APPROVED
DISABLED
IN_APPEAL
PENDING
REINSTATED
REJECTED
FLAGGED
Phone number updates
DOWNGRADE
FLAGGED
ONBOARDING
UNFLAGGED
UPGRADE
Template Category Update
Previous categories:
MARKETING
OTP
TRANSACTIONAL
New categories:
AUTHENTICATION
MARKETING
UTILITY
Two-step verification code
PIN_CHANGED:
Two-step verification code is updated (Cloud API only)PIN_RESET_REQUEST:
Request to disable Two-step verification codePIN_RESET_SUCCESS:
Two-step verification code is disabledWABA updates
ACCOUNT_RESTRICTION
: Used to report that a restriction has been put in place when a WABA violates WhatsApp Business Platform policies.DISABLED_UPDATE
VERIFIED_ACCOUNT
max_daily_conversation_per_phone
Always present when field=business_capability_update
.
Indicates the number of template messages you can send with each of your WhatsApp Business Account's business phone numbers that have an approved display name. See Messaging Limits .
max_phone_numbers_per_business
Includes the maximum number of phone numbers that can belong to a business.
When field=business_capability_update, a webhook will have either max_phone_numbers_per_business or max_phone_numbers_per_waba present.
max_phone_numbers_per_waba
Includes the maximum number of phone numbers that can belong to a WABA.
When field=business_capability_update, a webhook will have either max_phone_numbers_per_business or max_phone_numbers_per_waba present.
reason
Template rejection reason. Possible values:
ABUSIVE_CONTENT
— Content has been determined to be abusive.INCORRECT_CATEGORY
— Category has been determined to be incorrect. See Template Categories
.INVALID_FORMAT
— Duplicate content or missing examples.NONE
- Default, set when template is approved.SCAM
— Content has been determined to be a scam. rejection_reason
If a request was rejected, this field displays the reason for that rejection.
requested_verified_name
This field displays the name that was sent to be verified.
restriction_info
enum
Used to report restrictions imposed on a specific WABA, when that WABA violates WhatsApp Business Platform policies .
This field includes a list of restriction types and their corresponding expiration dates. Possible restriction types are:
RESTRICTED_ADD_PHONE_NUMBER_ACTION
RESTRICTED_BIZ_INITIATED_MESSAGING
RESTRICTED_CUSTOMER_INITIATED_MESSAGING
Expiration dates are provided in DateTime format.
requester
ID of the user who requested to disable, or has already disabled or updated, the two-step verification code.
{ "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>", "time": <TIMESTAMP>, "changes": [ { "value": { "event": "APPROVED", "message_template_id": <TEMPLATE_ID>, "message_template_name": "<TEMPLATE_NAME>", "message_template_language": "<LANGUAGE_AND_LOCALE_CODE>", "reason": "NONE" }, "field": "message_template_status_update" } ] } ], "object": "whatsapp_business_account" }
{ "object": "whatsapp_business_account" "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>", "time": <TIMESTAMP>, "changes": [ { "value": { "event": "REJECTED", "message_template_id": <TEMPLATE_ID>, "message_template_name": "<TEMPLATE_NAME>", "message_template_language": "<LANGUAGE_AND_LOCALE_CODE>", "reason": "<REJECTION_REASON>" }, "field": "message_template_status_update" } ] } ] }
{ "object": "whatsapp_business_account", "entry": [ { "id": "WHATSAPP-BUSINESS-ACCOUNT-ID", "time": TIMESTAMP, "changes": [ { "field": "message_template_status_update", "value": { "event": "FLAGGED", "message_template_id": TEMPLATE-ID, "message_template_name": "My message template", "message_template_language": "en-US", "reason": null, "disable_info": { "disable_date": "DATE", } } } ] } ] }
{ "object": "whatsapp_business account", "entry": [ { "id": "10908...", "time": 1661885238, "changes": [ { "value": { "event": "PAUSED", "message_template_id": 6048..., "message_template_name": "welcome", "message_template_language": "en_US", "reason": "NONE", "other_info": { "title": "SECOND_PAUSE", "description": "Your WhatsApp message template has been paused for 6 hours until Aug 31 at 12:47 AM UTC because it continued to have issues." } }, "field": "message_template_status_update" } ] } ], }
{ "object": "whatsapp_business account", "entry": [ { "id": "10310...", "time": TIMESTAMP, "changes": [ { "value": { "event": "PENDING_DELETION", "message_template_id": 1137..., "message_template_name": "<MY_TEMPLATE_NAME>", "message_template_language": "en_US", "reason": "NONE" } }, "field": "message_template_status_update" } ] } ], }
{ "object": "whatsapp_business_account", "entry": [ { "id": "<ID>", "time": <TIME>, "changes": [ { "field": "template_category_update", "value": { "message_template_id": <MESSAGE_TEMPLATE_ID>, "message_template_name": "<MESSAGE_TEMPLATE_NAME>", "message_template_language": "<MESSAGE_TEMPLATE_LANGUAGE", "previous_category": "<PREVIOUS_CATEGORY>", "new_category": "<NEW_CATEGORY>" } } ] } ] }
{ "object": "whatsapp_business_account", "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>", "time": <TIMESTAMP>, "changes": [ { "field": "message_template_quality_update", "value": { "previous_quality_score": "<PREVIOUS_QUALITY_SCORE>", "new_quality_score": "<NEW_QUALITY_SCORE>", "message_template_id": <TEMPLATE_ID>, "message_template_name": "<TEMPLATE_NAME>", "message_template_language": "<LANGUAGE_AND_LOCALE_CODE>" } } ] } ] }
{ "object": "whatsapp_business_account", "entry": [ { "id": "WHATSAPP-BUSINESS-ACCOUNT-ID", "time": TIMESTAMP, "changes": [ { "field": "phone_number_name_update", "value": { "display_phone_number": "PHONE_NUMBER", "decision": "APPROVED", "requested_verified_name": "WhatsApp", "rejection_reason": null } } ] } ] }
{ "object": "whatsapp_business_account", "entry": [ { "id": "WHATSAPP-BUSINESS-ACCOUNT-ID", "time": TIMESTAMP, "changes": [ { "field": "phone_number_quality_update", "value": { "display_phone_number": "PHONE_NUMBER", "event": "FLAGGED", "current_limit": "TIER_10K" } } ] } ] }
{ "object": "whatsapp_business_account", "entry": [ { "id": "WHATSAPP-BUSINESS-ACCOUNT-ID", "time": TIMESTAMP, "changes": [ { "field": "account_update", "value": { "phone_number": "PHONE_NUMBER", "event": "VERIFIED_ACCOUNT" } } ] } ] }
{ "object": "whatsapp_business_account", "entry": [ { "id": "WHATSAPP-BUSINESS-ACCOUNT-ID", "time": TIMESTAMP, "changes": [ { "field": "account_update", "value": { "event": "DISABLED_UPDATE" "ban_info": { "waba_ban_state": ["SCHEDULE_FOR_DISABLE", "DISABLE", "REINSTATE"], "waba_ban_date": "DATE" } } } ] } ] }
{ "object": "whatsapp_business_account", "entry": [ { "id": "WHATSAPP-BUSINESS-ACCOUNT-ID", "time": TIMESTAMP, "changes": [ { "value": { "event": "ACCOUNT_VIOLATION", "violation_info": { "violation_type": "VIOLATION_TYPE" } }, "field": "account_update" } ] } ] }
{ "object": "whatsapp_business_account", "entry": [ { "id": "WHATSAPP-BUSINESS-ACCOUNT-ID", "time": TIMESTAMP, "changes": [ { "value": { "event": "ACCOUNT_RESTRICTION", "restriction_info": [ {"restriction_type": "RESTRICTED_BIZ_INITIATED_MESSAGING" | "RESTRICTION_ON_ADD_PHONE_NUMBER_ACTION" | "RESTRICTED_CUSTOMER_INITIATED_MESSAGING", "expiration": TIMESTAMP} ] } }, "field": "account_update" } ] } ] }
{ "object": "whatsapp_business_account", "entry": [ { "id": "WHATSAPP-BUSINESS-ACCOUNT-ID", "time": TIMESTAMP, "changes": [ { "value": { "event": "DISABLED_UPDATE", "ban_info": { "waba_ban_state": "SCHEDULE_FOR_DISABLE" | "DISABLE" | "REINSTATE", "waba_ban_date": TIMESTAMP } }, "field": "account_update" } ] } ] }
{ "object": "whatsapp_business_account", "entry": [ { "id": "WHATSAPP-BUSINESS-ACCOUNT-ID", "time": TIMESTAMP, "changes": [ { "field": "account_review_update", "value": { "decision": "APPROVED" } } ] } ] }
{ "field": "account_update", "value": { "phone_number": "PHONE_NUMBER", "event": "ACCOUNT_RESTRICTION", "restriction_info": [ { "restriction_type": "RESTRICTION_ADD_PHONE_NUMBER_ACTION", "expiration": TIMESTAMP }, { "restriction_type": "RESTRICTED_BIZ_INITIATED_MESSAGING", "expiration": TIMESTAMP }, { "restriction_type": "RESTRICTED_CUSTOMER_INITIATED_MESSAGING", "expiration": TIMESTAMP } ] } }
{ "object": "whatsapp_business_account", "entry": [ { "id": "WHATSAPP-BUSINESS-ACCOUNT-ID", "time": TIMESTAMP, "changes": [ { "value": { "phone_number": "15551...", "event": "ACCOUNT_DELETED", }, "field": "account_update" } ] } ] }
{ "object": "whatsapp_business_account", "entry": [ { "id": "WHATSAPP-BUSINESS-ACCOUNT-ID", "time": TIMESTAMP, "changes": [ { "value": { "phone_number": "15551...", "event": "PARTNER_REMOVED", }, "field": "account_update" } ] } ] }
{ "object": "whatsapp_business_account", "entry": [ { "id": "WHATSAPP-BUSINESS-ACCOUNT-ID", "time": TIMESTAMP, "changes": [ { "field": "business_capability_update", "value": { "max_daily_conversation_per_phone": NUMBER, "max_phone_numbers_per_business": NUMBER } } ] } ] }
{ "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>", "time": <UNIX_TIMESTAMP>, "changes": [ { "value": { "entity_type": "BUSINESS", "entity_id": "<BUSINESS_ID>", "alert_severity": "CRITICAL", "alert_status": "ACTIVE", "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_FAILED", "alert_description": "Based on your activity, limits cannot be increased for your business <BUSINES_NAME>. Contact support for more information." }, "field": "account_alerts" } ] } ], "object": "whatsapp_business_account" }
{ "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>", "time": <UNIX_TIMESTAMP>, "changes": [ { "value": { "entity_type": "BUSINESS", "entity_id": "<BUSINESS_ID>", "alert_severity": "WARNING", "alert_status": "ACTIVE", "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_DEFERRED", "alert_description": "Limits cannot be increased for your business <BUSINES_NAME>. Use WhatsApp Business platform actively for several days and follow our messaging policies." }, "field": "account_alerts" } ] } ], "object": "whatsapp_business_account" }
{ "entry": [ { "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>", "time": <UNIX_TIMESTAMP>, "changes": [ { "value": { "entity_type": "BUSINESS", "entity_id": "<BUSINESS_ID>", "alert_severity": "WARNING", "alert_status": "ACTIVE", "alert_type": "INCREASED_CAPABILITIES_ELIGIBILITY_NEED_MORE_INFO", "alert_description": "Additional verification is required for your business <BUSINESS_NAME>. Go to Security Center in Meta for Business to complete identity verification. To continue without completing additional verification, your business can use WhatsApp Business platform actively for several days and follow our messaging policies." }, "field": "account_alerts" } ] } ], "object": "whatsapp_business_account" }