Set subscription for an app

📘
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

modes	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	{ "status": "error", "message": "Invalid URL Passed" }	The URL is not valid
401	{ "status": "error", "message": "Authentication Failed" }	When authentication fails
429	{ "status": "error", "message": "Too Many Requests" }	When the rate limit is exceeded
500	{ "status": "error", "message": "Unable To Create Subscription" }	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.