This API endpoint enables partners to subscribe to WhatsApp events (webhooks) for their partner application. When subscribed, WhatsApp will send real-time event notifications to the specified webhook URL for various event types like incoming messages, message status updates, user interactions, and more. This is essential for building interactive WhatsApp Business applications.
Subscriptions can now be set for sandbox apps as well. Once the app goes live, the current subscription will be retained.
Request Parameters
Key | Description | Mandatory/Optional | Constraint |
|---|---|---|---|
PARTNER_APP_TOKE N | Access Token for the application | Should be a valid Partner App Access Token | |
Stages in subscription processing | Mandatory | Should be one of the following : NONE, READ, DELIVERED, SENT, DELETED, FLOWS_MESSAGE,PAYMENTS, ALL, OTHERS for version 3: TEMPLATE, ACCOUNT, COPY are not supported | |
tag | Name tag for URL | Mandatory | Must be unique and mandatory for each app |
url | Callback URL | Mandatory | Should be a valid URL |
version | Version | Mandatory | Should be one of the following : 0,1,2,3 |
showOnUI | Used internally | Optional | Default value is false |
meta | meta json string (meta json key and value will be passed to the subscription URL as headers , users can set custom headers for the URL which can be used for authentication) | Optional |
Sample Request
curl --location 'https://partner.gupshup.io/partner/app/:appId/subscription' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: {{PARTNER_APP_TOKEN}}' \
--data-urlencode 'modes={{modes}}' \
--data-urlencode 'tag={{tagName}}' \
--data-urlencode 'showOnUI={{true/false}}' \
--data-urlencode 'version={{versionNumber}}' \
--data-urlencode 'url={{url}}'
--data-urlencode 'meta={{meta}}'Sample Response
{
"status": "success",
"subscription":
{
"active": true,
"appId": "bf9ee64c-xxxxxxxx-xxxx-xxxx577007c4",
"createdOn": 1705574838954,
"id": "8166",
"mode": 2047,
"meta": "{\"headers\":
{
\"Authorisation\":\"Bearer eyJhbGciOiJIxxxxxxxxxxxxxxxxxxxxxxxxxx6biZ7Sbhl0N0u_aI\"}
}"
"modifiedOn": 1705574838954,
"showOnUI": false,
"tag": "V3 Subscription",
"url":"https://webhook.site/0b092322-b55b-419e-9c74-eb92f2b38553",
"version": 3
}
}Status Codes
Status Code | Response | Comments |
|---|---|---|
Success | ||
200 | { "status": "success", "subscription": { "active": true, "appId": "bf9ee64c-xxxxxxxx-xxxx-xxxx577007c4", "createdOn": 1705574838954, "id": "8166", "mode": 2047, "meta": "{\"headers\": { \"Authorisation\":\"Bearer eyJhbGciOiJIxxxxxxxxxxxxxxxxxxxxxxxxxx6biZ7Sbhl0N0u_aI\"} }" "modifiedOn": 1705574838954, "showOnUI": false, "tag": "V3 Subscription", "url":"https://webhook.site/0b092322-b55b-419e-9c74-eb92f2b38553", "version": 3 } } | |
Error | ||
400 | { | The URL is not valid |
401 | { | When authentication fails |
429 | { | When the rate limit is exceeded |
500 | { | When error occurred while creating the subscription |
Modes
- TEMPLATE: The template events get forwarded to subscriptions if TEMPLATE mode is subscribed.
- ACCOUNT: The account events get forwarded to subscriptions if ACCOUNT mode is subscribed.
- PAYMENTS: Incoming Whatsapp pay events get forwarded to subscriptions if PAYMENTS mode is subscribed. [Only for v3].
- FLOWS_MESSAGE: Incoming flow messages get forwarded to subscriptions if FLOWS_MESSAGE mode is subscribed. [Only for v3].
- MESSAGE: All incoming messages (not events) except flow messages get forwarded to subscriptions if MESSAGE mode is subscribed.
- OTHERS: All incoming new events whose exclusive mode is not present (eg read, delivered, sent, payments) get forwarded to subscriptions if OTHERS mode is subscribed [Only for v3].
- ALL: All incoming messages (not events) get forwarded to subscriptions if ALL mode is subscribed [Only for v3].
- BILLING: Billing events get forwarded to subscriptions if billing mode is subscribed.
- FAILED: The failed events get forwarded to subscriptions if failed mode is subscribed.
- SENT: Sent events get forwarded to subscriptions if sent mode is subscribed.
- DELIVERED: Delivered events get forwarded to subscriptions if delivered mode is subscribed.
- READ: Read events get forwarded to subscriptions if read mode is subscribed.
- ENQUEUED Enqueued events get forwarded to subscriptions if enqueued mode is subscribed.