--- updatedAt: 2026-05-14T05:55:45.000Z agentTools: projectIndex: https://partner-docs.gupshup.io/llms.txt --- # System events These are generated by our platform when some event occurs. You can choose to receive these events on your callback URL from the settings in app dashboard. For example, system events are received when; * A system event of type `template` is received when the status of template is updated. For example, a submitted template has been approved or rejected. * A system event of type `account` is received. For example, when the status of the submitted Phone Number or Display Name for a WABA is updated. ## The types of system-events * Template events * [Account events](https://partner-docs.gupshup.io/docs/system-events#account-events#) ## Template events The following `template-event` is sent notifying of the template's status update. ```json template-event { "app":"jeet20", "timestamp":1636986446609, "version":2, "type":"template-event", "payload":{ "id":"4dacef15-6c04-12db-b393-6190ac567eff", "status":"rejected/approved/deleted/disabled/in_appeal", "elementName":"abcd", "languageCode":"en_US", "rejectedReason":"INVALID_FORMAT" } } ``` The following `template-event` is sent notifying of the template's paused status ```json template-event { "app": "jeet20", "timestamp": 1636986446609, "version": 2, "type": "template-event", "payload": { "type": "status-update", "id": "4dacef15-6c04-12db-b393-6190ac567eff", "status": "paused", "elementName": "abcd", "languageCode": "en_US", "description": "Your WhatsApp message template has been paused for 3 hours until Apr 25 at 8:07 AM UTC because it had issues." } } ``` > 📘 **Template Category Migration Update** > To line up with the template category change from WhatsApp, starting from **29th March 2023**, the template event payload will further be categorized into two types - *status-update* and *category-update* events. > > As Meta migrates your WhatsApp Business API templates to new categories, Gupshup too will synchronously migrate your templates to the new categories. If subscribed to the system events for your app, the *category-update* event will be sent on your app's callback URL notifying you of the old category and the new category. ### Possible status of quality-update event | Status | Quality | Color Code | | :----- | :-------------- | :------------------------ | | Active | Quality Pending | Highlighted in **Green** | | Active | High Quality | Highlighted in **Green** | | Active | Medium Quality | Highlighted in **Yellow** | | Active | Low Quality | Highlighted in **Red** | If you do not receive a template quality event from Meta then it will be shown as **NA** in the UI. ### The types of template events (applicable from 29th March 2023) ```json status-update { "app":"jeet20", "timestamp":1636986446609, "version":2, "type":"template-event", "payload": { "type":"status-update", "id":"4dacef15-6c04-12db-b393-6190ac567eff", "status":"rejected/approved/paused/deleted/disabled/in_appeal", "elementName":"abcd", "languageCode":"en_US", "rejectedReason":"INVALID_FORMAT" } } ``` ```json category-update { "app": "jeet20", "timestamp": 1636986446609, "version": 2, "type": "template-event", "payload": { "type": "category-update", "id": "4dacef15-6c04-12db-b393-6190ac567eff", "elementName": "abcd", "languageCode": "en_US", "category": { "old": "OTP", "new": "AUTHENTICATION/MARKETING/UTILITY" } } } ``` ```json quality-update { "app": "testApp", "timestamp": 1724265081729, "version": 2, "type": "template-event", "payload": { "id": "5xxxxxxxx-xxxxxx-xxxxxx-xxxx14", "elementName": "test_template", "languageCode": "en", "type": "quality-update", "quality": "GREEN | Yellow | RED" } } ``` ## Automatic template category updates Starting June 1, 2024, to ensure that all templates are correctly categorized, Meta has implemented a recurring process that automatically identifies and updates the category of any marketing or utility templates that have been miscategorized, according to their guidelines. In this process, Gupshup will send two webhook events for template\_category\_update. The first one is the alert event which will inform about the template’s current category and the correct category it belongs to. ### First payload ```Text category-update (correct-category-alert) { "app": "jeet20", "timestamp": 1717249875000, "version": 2, "type": "template-event", "payload": { "type": "category-update", "id": "4dacef15-6c04-12db-b393-6190ac567eff", "elementName": "abcd", "languageCode": "en_US", "category": { "current": "MARKETING", "correct": "UTILITY" } } } ``` ### The second payload The second event (sent in beginning of the next month after the alert event) will be the actual category update event informing that the template’s category has been now updated. ```Text category-update { "app": "jeet20", "timestamp": 1719815415000, "version": 2, "type": "template-event", "payload": { "type": "category-update", "id": "4dacef15-6c04-12db-b393-6190ac567eff", "elementName": "abcd", "languageCode": "en_US", "category": { "old": "MARKETING", "new": "UTILITY" } } } ``` ### The payload object description | Key | Description | Example | | :--------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------- | | `type` | The type of template event. Possible values are: `status-update`, and `category-update` | `category-update` | | `id` | It is the unique identifier for a template on the Gupshup platform. You can find the template ID using the API Get template list | `4dacef15-6c04-12db-b393-6190ac567eff` | | `status` | The updated status of a template. Possible values are: `REJECTED`, `APPROVED`, `DELETED`, `DISABLED`. | `REJ ECTED` | | `elementName` | The unique name for a template set during template creation. The `elementName` of a template is unique within a WABA's namespace. | `order_update` | | `languageCode` | The language of the template. You can refer to the language code and the associated language [here](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates#language-policy-options). | `en_US` | | `rejectedReason` | The reason for template rejection. | ` INVALID_FORMAT` | | `category` | This parameter informs of the category alert and category change (both before and after the actual event)`category.current`is the template’s current category,`category.correct `is the template’s correct category to which it belongs and will be updated by Meta and Gupshup at the beginning of next month,\`\`category.old`is the old template category, and`category.new`is the new template category after the change has been done at WABA. Possible values for`category.current`,` category.correct,category.old, and category.new\` are **Authentication**, **Marketing**, and **Utility**. | `Utility` | ## Account events Account events are received when an event occurs in a specific WABA. For example, when a WhatsApp business policy is violated by a WABA, or if the messaging tier limit of a WABA is updated. ### The types of account-events ```json review-event { "app": "jeet20", "timestamp": 1636986446609, "version": 2, "type": "account-event", "payload": { "type": "review-event", "payload": { "status": "approved", "actionDate": "January 31,2021" } } } ``` ```json status-event (account violation) { "app": "jeet20", "timestamp": 1636986446609, "version": 2, "type": "account-event", "payload": { "type": "status-event", "payload": { "status": "ACCOUNT_VIOLATION", "violation_type": "GAMBLING" } } } ``` ```json status-event (account disable) { "app": "", "appId": "", "timestamp": 1713531530035, "version": 2, "type": "account-event", "payload": { "type": "status-event", "payload": { "status": "DISABLE", "actionDate": "February28,2024" } } } ``` ```json status-event (account restriction) { "app":"appname", "timestamp":1636986446609, "version":2, "type":"account-event", "phone":"9180xxxxxxxx", "payload":{ "type":"status-event", "payload":{ "status":"ACCOUNT_RESTRICTED", "restrictionInfo":[ { "restrictionType":"RESTRICTION_ADD_PHONE_NUMBER_ACTION", "expiration":1636986446609 }, { "restrictionType":"RESTRICTED_BIZ_INITIATED_MESSAGING", "expiration":1636986446609 }, { "restrictionType":"RESTRICTED_CUSTOMER_INITIATED_MESSAGING", "expiration":1636986446609 } ] } } } ``` ```json status-event (reinstate) { "app": "ShipxxxxxxxxxxxxxxxxxxWapp", "appId": "e4c9dbe0-b1ef-4add-97a2-a8fdba0666ad", "phone": "918xxxxxxxxx2", "timestamp": 1717061550941, "version": 2, "type": "account-event", "payload": { "type": "status-event", "payload": { "status": "REINSTATE", "actionDate": "30 May 2024" } } } ``` ```json pndn-event { "app": "jeet20", "timestamp": 1636986446609, "version": 2, "type": "account-event", "payload": { "type": "pndn-event", "payload": { "status": "approved/rejected", "rejectedReason": "INVALID_FORMAT" } } } ``` ```json tier-event { "app": "jeet20", "timestamp": 1636986446609, "version": 2, "type": "account-event", "payload": { "type": "tier-event", "payload": { "event": "onboarding/ upgrade/ downgrade /unflagged/ flagged", "oldLimit": "TIER_10K", "currentLimit": "TIER_100K" } } } ``` ```json capability-event { "app":"appname", "timestamp":1636986446609, "version":2, "type":"account-event", "payload":{ "type":"capability-event", "payload":{ "maxDailyConversationPerPhone":100, "maxPhoneNumbersPerBusiness":100 } } } ``` ### The payload object description
Type Description
`review-event` This event is received when the submitted WABA is approved or rejected. Possible values: `APPROVED`, `REJECTED`.
`status-event` This event is received when the status of the WABA has changed. Possible values: `ACCOUNT_VIOLATION`: The WABA has been flagged due to policy violation, additionally, the reason for the violation is also received. `ACCOUNT_DISABLE`: The WABA has been flagged due to the account being disabled. `ACCOUNT_VERIFIED`: When an app of type of Embed is updated from Sandbox to Live. `ACCOUNT_RESTRICTED`: The WABA has been restricted for its business capabilities due to WhatsApp's policy violations. One or more of the following restriction types may be imposed on your WABA: * `RESTRICTION_ADD_PHONE_NUMBER_ACTION` - Restriction on adding phone numbers to WABA. * `RESTRICTED_BIZ_INITIATED_MESSAGING` - Restriction on sending business-initiated messages. * `RESTRICTED_CUSTOMER_INITIATED_MESSAGING` - Restriction on the ability to respond to customer-initiated messages.Along with the `type`, you will also receive the expiry for the restriction.Learn more about [policy violations](https://faq.whatsapp.com/general/whatsapp-business-api/how-to-comply-with-the-whatsapp-business-and-commerce-policies). Learn more about [WABA restrictions](https://developers.facebook.com/docs/whatsapp/overview/track-waba-policy-violations).An email will be sent informing you of violations and restrictions received for your WABA.
`pndn-event` This event is received when the status of the submitted Phone number/Display Name is updated. Possible values: `INVALID_FORMAT`, `NAME_END_CLIENT_VIOLATION`, `NAME_FORMAT_UNACCEPTABLE`, `NAME_NOT_CONSISTENT`, `NAME_INDIVIDUAL_ISSUE`, and `NAME_ENDCLIENT_NOTRELATED`.
`tier-event` This events notifies you when the quality-related status of a phone number has an update. Possible values for events: `ONBOARDING`, `UPGRADE`, `DOWNGRADE`, `UNFLAGGED`, and `FLAGGED`. The current tier limit where this account is and the new tier if it has been updated. Possible values are: **TIER_250, TIER_1K, TIER_10K, TIER_100K, and TIER_UNLIMITED**
`capability-event` This event will update you on your WABA's messaging capabilities. It includes: * `maxDailyConversationPerPhone` - the maximum number of unique people a phone number can send messages to. See [Messaging Limits](https://developers.facebook.com/docs/whatsapp/api/rate-limits#messaging) for more information. * `maxPhoneNumbersPerBusiness` - Includes the maximum number of phone numbers that can belong to a business.
If there are multiple phone numbers for the apps in a given WABA **maxDailyConversationPerPhone** will show the minimum value to ensure that businesses are aware of the lowest messaging limit across all their phone numbers. For example, if a business has two phone numbers with different limits (e.g., 1K and 10K), showing the minimum value (1K) will help them understand that they need to be mindful of this lower limit when sending messages from either phone number.
### Go-Live Event Go-Live Event is sent to callback URLs whenever an app completes onboarding. > 📘 Subscribe to ACCOUNT mode using [subscription API](https://partner-docs.gupshup.io/reference/setsubscription-api-v3#/) to receive the Go-Live event on your registered callback #### Go-Live Event payload ```Text Go-Live Event payload { "entry": [ { "changes": [ { "field": "account-event", "value": { "payload": { "status": "ACCOUNT_VERIFIED" }, "type": "status-event" } } ], "id": "731055923430007", "time": 1778737735857 } ], "gs_app_id": "4b886e79-6bc4-4fd6-8612-81e4db0a1a94", "object": "whatsapp_business_account" } ``` #### The payload key description | Key | Description | Example | | :---------- | :--------------------------------------------------------------------------------------------------- | :----------------------------------- | | gs\_app\_id | App Id for which partner will receive the go-live event. The Id should be a valid app Id of Gupshup | 4b886e79-6bc4-4fd6-8612-81e4db0a1a94 | | time | Timestamp of the event received | 1778737735857 | | type | Type of the event | status-event | | status | Status of the event | ACCOUNT\_VERIFIED | ### MM LITE Webhook Event V2 & V3 Upon successful completion of the MM Lite onboarding flow and all associated backend processes, a new **account\_update** webhook will be triggered for each WhatsApp Business Account (WABA) linked to the Business Manager ID (BMID), signifying successful onboarding. #### V3 Webhook Event ```Text V3 Webhook Event { "entry": [ { "changes": [ { "field": "account_update", "value": { "event": "AD_ACCOUNT_LINKED", "waba_info": { "ad_account_id": "521842584195455", "owner_business_id": "1998042230628192", "waba_id": "216141188246170" } } } ], "id": "216141188246170", "time": 1734607255 } ], "gs_app_id": "bf9ee64c-3d4d-4ac4-8668-732e577007c4", "object": "whatsapp_business_account" } ``` ##### The payload object description | Key | Sample Value | Description | | :------------------ | :----------------------------------- | :------------------------------------------------------------------------------------------------------------------- | | field | account\_update | Category of event | | event | AD\_ACCOUNT\_LINKED | Specific name of event inside category | | ad\_account\_id | 521842584195455 | Once MM lite onboarding is successful an ad account gets generated and a unique ad account id is associated with it. | | owner\_business\_id | 1998042230628192 | Meta generated business id per account | | waba\_id | 216141188246170 | Whatsapp Business Account Id | | id | 216141188246170 | Whatsapp Business Account Id | | time | 1734607255 | Unix time stamp of webhook event | | gs\_app\_id | bf9ee64c-3d4d-4ac4-8668-732e577007c4 | GupShup app id | #### V2 Webhook Event ```Text V2 Webhook Event { "app": "Jan10pass", "appId": "bf9ee64c-3d4d-4ac4-8668-732e577007c4", "timestamp": 1743508047545, "version": 2, "type": "account-event", "payload": { "type": "status-event", "payload": { "status": "AD_ACCOUNT_LINKED", "waba_id": "216141188246170", "owner_business_id": "1998042230628192", "ad_account_id": "521842584195455" } } } ``` ##### The payload object description | Key | Sample Value | Description | | :------------------ | :----------------------------------- | :------------------------------------------------------------------------------------------------------------------- | | app | Jan10pass | App Name | | appId | bf9ee64c-3d4d-4ac4-8668-732e577007c4 | GupShup App Id | | timestamp | 1734607255 | Unix timestamp of webhook event | | type | account-event | Category of event | | status | AD\_ACCOUNT\_LINKED | The specific name of an event inside the category | | waba\_id | 216141188246170 | Whatsapp Business Account Id | | owner\_business\_id | 1998042230628192 | Meta-generated business id per account | | ad\_account\_id | 521842584195455 | Once MM lite onboarding is successful an ad account gets generated and a unique ad account id is associated with it. |