Integrate Gupshup's WhatsApp Business API into the workflow. Send text, media, quick reply buttons, list menus, and approved templates, look up templates and their approval status, and run workflows when a customer messages you or a message is delivered, read, or fails. WhatsApp only delivers free-form session messages within 24 hours of the customer's last message; outside that window, send an approved template. Requires a Gupshup API key, app name, and the app's WhatsApp number.
Send a free-form WhatsApp text message to a customer through Gupshup. WhatsApp only delivers session messages within 24 hours of the customer's last message to you. Outside that window the send fails (error 470), and only an approved template can be sent.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Gupshup account API key, shown on the Gupshup dashboard. Sent as the apikey header. |
appName | string | Yes | Name of the Gupshup app that owns the source number (sent as src.name) |
source | string | Yes | Your WhatsApp Business number registered on the app, with country code, e.g. 919876543210 |
destination | string | Yes | Customer WhatsApp number with country code, e.g. 919876543210 (a leading + is removed) |
text | string | Yes | Message text. WhatsApp formatting like bold works. |
previewUrl | boolean | No | Show a link preview when the text contains a URL |
replyToMessageId | string | No | Message ID to reply to, shown as a quoted reply in WhatsApp. Must be less than 30 days old. |
| Parameter | Type | Description |
|---|
messageId | string | Gupshup message ID. Message events (sent, delivered, read, failed) report it as gsId. |
status | string | submitted (or success) means Gupshup accepted the request. Delivery is reported later as a message event. |
Send an image, video, audio file, document, or sticker on WhatsApp through Gupshup, from a public URL or an uploaded media ID. WhatsApp only delivers session messages within 24 hours of the customer's last message to you. Outside that window the send fails (error 470), and only an approved template can be sent.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Gupshup account API key, shown on the Gupshup dashboard. Sent as the apikey header. |
appName | string | Yes | Name of the Gupshup app that owns the source number (sent as src.name) |
source | string | Yes | Your WhatsApp Business number registered on the app, with country code, e.g. 919876543210 |
destination | string | Yes | Customer WhatsApp number with country code, e.g. 919876543210 (a leading + is removed) |
mediaType | string | Yes | image, video, audio, document, or sticker |
mediaUrl | string | No | Public HTTPS URL of the file. Provide this or Media ID. |
mediaId | string | No | ID of media already uploaded to Gupshup. Used instead of Media URL. |
caption | string | No | Caption shown under an image, video, or document |
filename | string | No | File name shown for a document, e.g. invoice-4821.pdf |
replyToMessageId | string | No | Message ID to reply to, shown as a quoted reply in WhatsApp. Must be less than 30 days old. |
| Parameter | Type | Description |
|---|
messageId | string | Gupshup message ID. Message events (sent, delivered, read, failed) report it as gsId. |
status | string | submitted (or success) means Gupshup accepted the request. Delivery is reported later as a message event. |
Send a WhatsApp message with up to 3 quick reply buttons, or a list menu of up to 10 options, through Gupshup. The customer's choice arrives on the Gupshup Inbound Message trigger as a quick_reply or list_reply. WhatsApp only delivers session messages within 24 hours of the customer's last message to you. Outside that window the send fails (error 470), and only an approved template can be sent.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Gupshup account API key, shown on the Gupshup dashboard. Sent as the apikey header. |
appName | string | Yes | Name of the Gupshup app that owns the source number (sent as src.name) |
source | string | Yes | Your WhatsApp Business number registered on the app, with country code, e.g. 919876543210 |
destination | string | Yes | Customer WhatsApp number with country code, e.g. 919876543210 (a leading + is removed) |
interactiveType | string | Yes | quick_reply (up to 3 buttons) or list (a menu of up to 10 rows) |
body | string | Yes | Main message text |
header | string | No | Header text. Required for a list, where it is the list title. |
footer | string | No | Footer text shown in small grey type |
buttons | json | No | Quick reply buttons: up to 3 titles, comma-separated or a JSON array, e.g. ["Yes","No"] or [{"title":"Yes","postbackText":"confirm"}] |
listButtonTitle | string | No | For a list: the label of the button that opens the menu, max 20 characters |
sections | json | No | For a list: rows as titles (comma-separated or a JSON array), or sections as [{"title":"Plans","options":[{"title":"Basic","description":"Rs 499/month","postbackText":"plan_basic"}]}]. Max 10 rows in total. |
trackingId | string | No | Your ID for this message (msgid), returned as id in the reply payload so you can tell which menu was answered |
replyToMessageId | string | No | Message ID to reply to, shown as a quoted reply in WhatsApp. Must be less than 30 days old. |
| Parameter | Type | Description |
|---|
messageId | string | Gupshup message ID. Message events (sent, delivered, read, failed) report it as gsId. |
status | string | submitted (or success) means Gupshup accepted the request. Delivery is reported later as a message event. |
Send an approved WhatsApp template message through Gupshup, filling its {{1}}, {{2}}... placeholders in order. Templates are the only messages WhatsApp delivers outside the 24-hour customer service window, so use one for the first message to a lead, reminders, and any follow-up after the customer has been quiet for 24 hours. The template must be APPROVED; check with List Templates.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Gupshup account API key, shown on the Gupshup dashboard. Sent as the apikey header. |
appName | string | Yes | Name of the Gupshup app that owns the source number (sent as src.name) |
source | string | Yes | Your WhatsApp Business number registered on the app, with country code, e.g. 919876543210 |
destination | string | Yes | Customer WhatsApp number with country code, e.g. 919876543210 (a leading + is removed) |
templateId | string | Yes | Gupshup template ID (the id from List Templates, not the template name) |
templateParams | json | No | Values for the template placeholders in order, as a JSON array or comma-separated list, e.g. ["Asha","15 Jan","10:30"] |
headerMediaType | string | No | For a media-header template: image, video, or document |
headerMediaUrl | string | No | Public URL of the header image, video, or PDF |
headerMediaId | string | No | Uploaded media ID for the header, used instead of the URL |
postbackTexts | json | No | Postback text for quick reply buttons, as [{"index":0,"text":"confirm"}] with a 0-based button index |
| Parameter | Type | Description |
|---|
messageId | string | Gupshup message ID. Message events (sent, delivered, read, failed) report it as gsId. |
status | string | submitted (or success) means Gupshup accepted the request. Delivery is reported later as a message event. |
List the WhatsApp templates on a Gupshup app with their approval status, category, language, and body. Use it to find the template ID to send and to confirm a template is APPROVED, since only approved templates can be sent outside the 24-hour customer service window.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Gupshup account API key, shown on the Gupshup dashboard. Sent as the apikey header. |
appId | string | Yes | Gupshup app ID (a UUID shown on the app dashboard, not the app name) |
templateStatus | string | No | Only templates with this status, e.g. APPROVED |
templateCategory | string | No | Only templates in this category: MARKETING, UTILITY, or AUTHENTICATION |
languageCode | string | No | Only templates in this language, e.g. en |
pageNo | number | No | Page number, starting at 0 (default 0) |
pageSize | number | No | Templates per page (default 100) |
| Parameter | Type | Description |
|---|
templates | array | Templates on the app, with their approval status |
↳ id | string | Gupshup template ID, used to send the template |
↳ elementName | string | Template name |
↳ status | string | Approval status, e.g. APPROVED, PENDING, REJECTED, PAUSED, or FAILED. Only APPROVED templates can be sent. |
↳ category | string | MARKETING, UTILITY, or AUTHENTICATION |
↳ templateType | string | TEXT, IMAGE, VIDEO, DOCUMENT, or LOCATION |
↳ languageCode | string | Language code, e.g. en |
↳ data | string | Template body with {{n}} placeholders |
↳ quality | string | Quality rating, e.g. GREEN |
↳ externalId | string | Meta template ID |
↳ buttonSupported | string | Button types on the template |
↳ createdOn | number | Creation time (epoch ms) |
↳ modifiedOn | number | Last change time (epoch ms) |
count | number | Number of templates returned on this page |
Get one WhatsApp template on a Gupshup app by its template ID, including its approval status, category, and body. Check that the status is APPROVED before sending it.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Gupshup account API key, shown on the Gupshup dashboard. Sent as the apikey header. |
appId | string | Yes | Gupshup app ID (a UUID shown on the app dashboard, not the app name) |
templateId | string | Yes | Gupshup template ID |
| Parameter | Type | Description |
|---|
messageId | string | Gupshup message ID of a sent message (gsId on status events) |
status | string | Send result (submitted or success), or template approval status (Get Template) |
templates | json | Templates from List Templates (id, elementName, status, category, templateType, languageCode, data, quality, externalId, buttonSupported, createdOn, modifiedOn) |
count | number | Number of templates returned |
id | string | Template ID (Get Template) |
elementName | string | Template name |
category | string | Template category |
templateType | string | Template type, e.g. TEXT or IMAGE |
languageCode | string | Template language code |
data | string | Template body with placeholders |
quality | string | Template quality rating |
externalId | string | Meta template ID |
buttonSupported | string | Button types on the template |
createdOn | number | Template creation time (epoch ms) |
modifiedOn | number | Template last change time (epoch ms) |