Enterprise Messaging APIs for WhatsApp

Business
© 2023 Gupshup

All rights reserved. No parts of this work may be reproduced in any form or by any means -graphic, electronic, or
mechanical, including photocopying, recording, taping, or information storage and retrieval systems -without the written
permission of the publisher. Products that are referred to in this document may be either trademarks and / or registered
trademarks of the respective owners. The publisher and the author make no claim to these trademarks. While every
precaution has been taken in the preparation of this document, the publisher and the author assume no responsibility for
errors or omissions, or for damages resulting from the use of information contained in this document or from the use of
programs and source code that may accompany it. In no event shall the publisher and the author be liable for any loss of
profit or any other commercial damage caused or alleged to have been caused directly or indirectly by this document.

Published: October 2023

2
Table of Contents
Introduction 6
About WhatsApp Business 6
Business Account Approval 6
Business Phone Number 6
Discovery 7
Sending Notifications on WhatsApp 8
WhatsApp Template: Concepts & Guidelines 8
Opt-in Requirements 10
Customer Care Window 11
Button Message Templates 11
Header and Footer 12
List Messages – Interactive Messaging 12
Dynamic Reply Buttons – Interactive Messaging 13
Single and Multi-Product Messages- Interactive Messaging 14
Quality Rating 16
Significance of Quality Rating 16
How to Maintain (or Improve) Quality Rating 16
Messaging Limits 17
Official Business Account 18
Gupshup Messaging API Reference 20
Concepts 20
API Endpoint 20
User Authentication Scheme 20
HTTPS/SSL Support 20
Data Encryption 20
Pre-Requisites 21
API Collection: 21
Opt-in a User 21
API Endpoint 22
Request Headers 22
Request Body 22
Sample Requests 23
API Response 24
API Errors 24
Opt-out a User 25
API Endpoint 25

3
 Request Headers 25
Request Body 25
Sample Requests 26
API Response 26
API Errors (for OPTIN & OPTOUT APIs) 27
Send a Notification Message 29
Send a Text Template Notification 29
Send a Media Template Notification 37
URL Encoding 55
Formatting Options 55
API Response 56
API Errors (SendMessage & SendMediaMessage APIs) 56
Receive an Inbound Message 57
Webhooks 57
Sample Events 64
Download Inbound Media Attachments 73
Send a Customer Support Reply 74
Send a Text Message 74
Send a Media Message 77
Send a Location Message 81
Send a Contact Card 84
Send a List Message 90
Send a Dynamic Quick Reply Buttons: 98
Sending Single and Multi-Product Messages 107
Sending a Sticker Message 115
Formatting Options 117
WhatsApp Delivery Reports 118
Real time Delivery Reports 118
Downloadable Delivery Reports 120
APPENDIX A 123

4
Introduction

This guide provides specifications of the Gupshup Messaging API for WhatsApp Business for the purpose of
sending and receiving messages on WhatsApp via a simple REST API through HTTP/HTTPS modes. This guide is
intended for the developers and IT personnel of enterprises who plan to integrate their systems with the
Gupshup Messaging API.

About WhatsApp Business

Today, more than 2 billion people in over 180 countries use WhatsApp to stay in touch with friends and
family—anytime and anywhere. Businesses all over the world have already been using WhatsApp informally to
communicate with customers, whether about product enquiries or transactional updates. WhatsApp Business
is a new way for businesses to better manage such conversations with their customers and also reach new
customers who will also value the fast, convenient and private messaging experience.

This guide will help businesses get started on building an official brand presence on WhatsApp and creating
engaging conversational messaging experiences using the Gupshup Messaging API.

Business Account Approval

Every business seeking to get access to the WhatsApp Business API must apply to WhatsApp for approval. As an
authorized service provider for WhatsApp Business, Gupshup will facilitate the approval process on behalf of
the business. To apply for a WhatsApp Business Account (WABA), you must fill up the Early Access Request
form and share

Final approval decision completely lies with WhatsApp. You will typically get a decision on WABA application
status within 2-3 working days.

Business Phone Number

Your business will be identified by a phone number on WhatsApp, known as the Business Phone number. This
number will be registered in your WhatsApp Business account (WABA) and customers will be able to interact
with your business on WhatsApp on this registered number.

​Ideally, this number should not have been previously registered on WhatsApp or on the WhatsApp Business
app.
​If you are already on the WhatsApp Business Messaging API platform with another BSP, it is possible to retain
the same WABA number and migrate to the Gupshup Messaging Platform
​If you are already using a number on WhatsApp for your business and wish to use the same number, then you

5
 must first deregister the number on WhatsApp by deleting that account. Learn more

​ This number can be a mobile number (SIM or virtual) or a landline phone number, which has SMS and/or Voice
calling facility enabled. During the “Verify Number” step in “Go-live” process, WhatsApp will send a One-Time
Password (OTP) for two factor authentication via SMS or Voice.
​ Once the number is verified here, please do not register the number on WhatsApp or the WhatsApp Business
app on a mobile phone. This will result in the number being de-registered from the WhatsApp Business API
service provided by Gupshup.

Discovery
Once your WABA Approval is in place and your Business Phone Number has been verified, you can help
customers discover your business and grow your brand presence on WhatsApp. Discovery that leads to
customers initiating a conversation with your business on your WhatsApp Business Phone Number, can be
accomplished with the following tools:

​ Click-to-Chat web links

o Publish these web links on your website or in your direct-to-customer communication
channels like SMS, email, etc. and automatically redirect customers into a conversation
with your business on WhatsApp Web.
o The web link format is:
https://wa.me/<BusinessPhoneNumberinE.164Format>?text=<urlencodedtext>
o For example, if your Business Phone Number is +91 7834811114, your deep link can be
https://wa.me/917834811114?text=Hi%20there

​ Click-to-Chat deep links

o Embed these deep links in your mobile app or mobile ads to automatically redirect
customers into a conversation with your business on WhatsApp.
o The deep link format is:
whatsapp://send?phone=<BusinessPhoneNumberinE.164Format>&text=<urlenco dedtext>
o For example, if your Business Phone Number is +91 7834811114, your deep link can be
whatsapp://send?phone=917834811114&text=Hi%20there

​ Facebook Ads that Click-to-WhatsApp (CTWA)

o Facebook and Instagram Ads that Click-to-WhatsApp are an effective way for businesses
to get discovered and for customers to chat with them on WhatsApp.
o This feature allows people to easily start a message thread in WhatsApp directly from
Facebook or Instagram. When a person taps on an ad that clicks-to-WhatsApp, they will
be transferred to a pre-filled WhatsApp chat where they can message your business
quickly. Learn how to get started with this feature here .

6
 o We recommend that you register the same Facebook Business Manager ID (through
which you run your Facebook/Instagram ads) during the WABA application process. This
feature will then become available to you.

Sending Notifications on WhatsApp

To send a notification to a customer on WhatsApp, you must have:

● An explicit opt-in from that customer indicating his consent to receive messages from your business
on WhatsApp (Read more about WhatsApp’s opt-in requirements below)
● The notification message must be in the form of a message template that has been pre- approved
by WhatsApp.
o Good examples of Message Templates are: credit card payment reminders, e- commerce
order delivery status updates, loan approval status changes, policy change notice,
relevant sales & promotions etc.
o WhatsApp now permits message templates that have promotional or remarketing
content, such as cross-selling or up-selling products.
o Currently WhatsApp supports text, rich media (image, document, and video) and
Interactive message templates.

WhatsApp Template: Concepts & Guidelines

>> Template Category:

WhatsApp Business Messaging has categorized the messaging templates into 3 broad categories:

● Utility
● Marketing
● Authentication

All previous templates have been migrated by Meta to the updated categories and newer templates will only
support the above three categories.
Businesses can initiate a conversation using a template message. The category of the template message that is
used, will define the conversation category.

MARKETING
Marketing templates are flexible and do not relate to a specific, agreed-upon transaction. They may include the
below definitions:
promotions or offers, welcoming/closing messages, updates, invitations or recommendations, or requests to
respond to or complete a new transaction.
These are as good as the present Marketing category, with no changes in the implementation

UTILITY

7
Utility templates relate to a specific, agreed-upon transaction and accomplish one of the following: confirm,
suspend, or change a transaction or subscription.
These are as good as the present Transactional category, with no changes in the implementation

AUTHENTICATION
Authentication templates can be used by businesses to authenticate users with one-time passcodes (usually 4-8
digit alphanumeric codes) for account verification, account recovery, etc. usually via a mobile app where users
have the option to receive one-time passwords or verification codes via the WhatsApp app. This is only
available for International-based businesses.

The Authentication templates can be created using Gupshup’s Unify panel. As a Meta implementation, this type
of template must include either a copy code or a one-tap autofill button. Buttons behave differently when
tapped by a user:
● A copy code button copies the one-time password or code to the user's clipboard. The user can then
manually switch to your app and paste the password or code into your app's interface.
● A one-tap autofill button automatically loads and passes your app the one-time password or code. This
feature will only be supported for recipients with an Android mobile device.
For now, the supported language for Authentication templates is English and only Text type is supported.

>> Template Pausing:

WhatsApp Business has introduced ‘Template pausing’ which is a mechanism to give feedback to Businesses
if a template is not being received well by their end users. The decision on a template’s Quality rating is
implemented by WhatsApp via an algorithm that has a spectrum to measure template ratings.
Pausing durations are as follows:
▪ 1st Instance: Paused for 3 hours
▪ 2nd Instance: Paused for 6 hours
▪ 3rd Instance: Disabled

>> Editing Templates:

In order to promote WhatsApp Quality based Messaging that make messaging more relevant to the
Business's end users; WhatsApp is now providing template-level quality feedback, which can be used to
modify the template. The Scope for editing is as follows:

▪ Name, Category, and template name cannot be edited

▪ A template in the Enabled, Rejected, or Paused can be edited from

▪ Text to media and vice versa

▪ Interactive to non-interactive and vice versa

▪ to include message components like headers & Footers and also remove message components like
headers & Footers

>> Shorter TAT for Template review:

The Turn-around-time for the WhatsApp team to review a template has moved from 24 hours to a few
minutes. Now the templates will be approved or rejected instantaneously.

8
 Guidelines
● Always adhere to the WhatsApp Business Messaging policy.
● The template verbiage must be such that the variable values can be easily determined such as,
“Dear {{1}} This is to inform you that, your Insurance policy with policy number {{2}} has a premium
amount {{3}} which is due for payment on date {{4}} “
● Media Templates must have a clear caption part that speaks for the’ media’ attachment. WhatsApp
must be able to understand what would be the contents of the media from the message / caption.
● If you need to write a message template to reopen the 24-hour window, it is suggested that the
templates starts with some reference to the previous conversation.
● In case dispute needs to be raised with WhatsApp, the business use case of the template along with
sample values must be shared.
● Avoid floating variable {{1}} {{2}} i.e. consecutive variables specified immediately as these do not
give WhatsApp clarity on the possible values.
● Make it a point to always stick to the content languages as per specified in the ‘language’ while
creating a template.
● CTA Button templates must have genuine website links (static part) that must be accessible for
verification by WhatsApp as a part of the template approval.
● WhatsApp has made it mandatory to add sample values for variables within a template.

Opt-in Requirements
A user must first consent to receive messages in WhatsApp by opting into them via a third-party channel.
This can be any channel your business uses to communicate with people today such as — your website,
mobile app, missed call, IVR, email, SMS, retail location, contact center and WhatsApp session based
messages.

● The opt-in must be an explicit i.e. triggered by a user action, such as entering a phone number or
ticking a checkbox to indicate consent.
● Clear opt-in messaging so that a user knows what types of messaging the person is signing up for.
● Opt-ins must be maintained by the business, and should be produced in the event that WhatsApp
requests for this information.
● Session based OPTINs are permitted. i.e. during the session message, the customer can express
explicit consent to receive notifications from a brand.

Customer Support on WhatsApp

To respond back to customer queries sent on WhatsApp, the business can use the API to send messages but
only during the Customer Care Window (see below).
● User need not have opted in to receive these customer support replies.
● Such customer support replies can be free text and are non-templated.
● Such customer support replies must only include customer solicited information. These messages
9
 could be of the below nature, provided it is relevant to the customer.
o recommendations of other similar products (that would be cross-sell)
o Re-engagement with offers or promotional codes on products and services.

Customer Care Window

The business can reply back to a customer’s query on WhatsApp only within 24 hours from the customer’s
last message on WhatsApp (“Customer Care Window”). If the business attempts to send a message after
the Customer Care Window has elapsed, the message will fail unless the message is a notification message
i.e. is a pre-approved template and that customer has opted in to receive notifications from the business.

Button Message Templates

The Interactive Message Templates feature in WhatsApp Business API allows you to add buttons in message
templates that can be used with customized call to action buttons and quick replies. Buttons will give
businesses the ability to develop interactive experiences with pre-set options for users. There are two types
of buttons:

Call-to-Action buttons: You can add two call-to-action buttons to media message or text-based message
templates, and customize the text of the button. These features will help increase your overall engagement
rate with notifications. We have the following types of call-to-action buttons available:

● Visit website objective – can be a static or dynamic website URL or deep link
● Call phone number objective – must be a static phone number

At most, 1 button of each type can be added to a text or media message template. The Display Text for
the Call-to-Action Buttons is defined in the template at the time of template creation and cannot be
customized on the fly. The Display text cannot exceed 30 characters and may include emojis.

Quick Reply buttons:

You can add three quick reply buttons to message templates. These quick reply buttons will help you
improve the quality of conversations with users by prompting responses that can reduce spelling errors and
improve an automated experience. These buttons can be attached to text messages or media messages.
Once these templates have been created and approved, you can use them in notification messages as well
as customer service/care messages

The Display Text for the Quick Reply Buttons is defined in the template at the time of template creation and
cannot be customized on the fly. The Display text cannot exceed 30 characters and may include emojis.
Once a user clicks on a Quick Reply button in a text or media message template, it is greyed out and cannot
be clicked again. Each click on the Quick Reply will be an incoming message to the Business. It is also

10
possible to define a custom payload against each Quick reply button while placing the message requests; in
order to identify the Button details in the incoming message.

Header and Footer

● WhatsApp for Business has enhanced message templates and has made it more structured with the
introduction of the Header and Footer component.
Header:
● A WhatsApp Message; text or media will contain an optional parameter called the Header.
● A text message can have additional text as the Header whereas in a Media message, the Header is
already specified as the media file (image, document, video or location).
● In a Text message, a header usually refers to the ‘Title’ of the message whereas in a Media message,
the Header component specifies the ‘type of media’ that will be used in the template.
● The character length of a header is 60 characters and can contain variables. (Total value of the
header with variables has to be 60 characters)
● Headers can also be sent for List Messages and text messages with Dynamic Reply Buttons in
Interactive messaging within the 24 hour window.

Footer:
● A WhatsApp Message; text or Media will contain an optional Parameter called the Footer.
● The Footer is a usually a short line of text to the bottom of the message template.
● The total character length of the Footer can be a maximum of 60 characters and cannot contain
variables.
● Footers can be sent for List Messages and Text and Media messages with Dynamic Reply Buttons in
Interactive messaging within the 24 hour window

List Messages – Interactive Messaging

List messages provide a simpler and more consistent format than text-based lists for people to find and
select what they want from a business.

● Lists are applicable to only 2-way messaging; List messages are a way to allow users to easily choose
from up to 10 options
● They can be populated dynamically, based on a customer’s responses, so can be used for
personalized bot use cases.
● Lists messages do not require a template or pre-approval and are currently made available for Text
messages (media and location not supported )
● List Messages are best for presenting several options, such as:

1. A customer care or FAQ menu

2. A take-out menu

11
 3. Selection of nearby stores or locations
4. Available reservation times
5. Choosing a recent order to repeat etc.

Dynamic Reply Buttons – Interactive Messaging

Similar to templates with quick-reply buttons, reply buttons allow users to make a quick selection from up
to three options when talking to a business in the 24-hour response window. Reply buttons do not require a
pre-approved template.

● A message cannot contain more than three reply buttons.

● Reply buttons do not offer additional context for each option.
● Users can only select one button from the menu at a time, although they can go back and reuse a
previous menu.
● Reply buttons are supported for message types: text, image, video & document.

12
Single and Multi-Product Messages- Interactive Messaging

Businesses on WhatsApp for Business API can now showcase a complete range of products in real-time,
with up to 30 items with Multi-Product Messages or just one item with Single Product Messages. This
empowers Businesses to send out rich product messages that help build commerce journeys on WhatsApp.

With the dawn of commerce on WhatsApp, end-users can add items to their cart right from their WhatsApp
app, then send them to the business for the next steps such as making payments, enquiring about the
product, etc.

· Multi-Product Messages: Messages containing a selection of up to 30 items from a business’

inventory.

· Single Product Messages: Messages with a single product item from the business’ inventory. The
product is displayed in a Product Detail Page (PDP) format.

Pre-requisites

To get started with commerce on WhatsApp, an enterprise must:

1. Create a catalog using Facebook’s Catalog Manager. A maximum of one catalog can be active for a
WhatsApp Business Account. Click here for information
2. Add items to your catalog. Business can add multiple items but only a maximum of 30 catalog items
can be shared in a single message request. Click here for information
3. Share the catalog ID with Gupshup so that we can connect your catalog to your WABA
4. Share below details with Gupshup to register your WABA for this feature
5. Fill in the Business compliance details via the ‘Business compliance’ tab on the WhatsApp Analytics
Panel. Business compliance details involve Entity/Business Details, Grievance Office Information and
Customer care details

13
** Note: For more info refer here i.e. How to comply with the laws for selling online in India using
WhatsApp Business API.

End-user device compatibility:

Currently, commerce messages can be received in the following platforms:
● iOS: 2.21.100 (Multi-Product Messages) and 2.21.210 (Single Product Messages).
● Android: 2.21.9.15 (Multi-Product Messages) and 2.21.19 (Single Product Messages).
● Web: The web client that supports these features has been launched.

Since both Multi-Product Messages and Single Product Messages are types of interactive messages, users
can perform 3 main actions:

1. View Products

2. Add products to cart: The cart persists in the chat thread until it is sent to the business. Once sent,
the cart is cleared. Customers can add up to 99 units of each single catalog item to a shopping cart,
but there is no limit on the number of distinct items that can be added to a cart.

3. Send a shopping cart to the business for proceeding next steps such as payment, delivery info, etc.:
Once a cart has been sent, no edits can be made. Customers can send a new cart if they need new
items or they would like to change their order.

14
Quality Rating

The Quality Rating status of a WABA number can either be:

High (GREEN), Medium (YELLOW) or Low (RED)

Significance of Quality Rating

The Quality Rating assigned to the number indicates the way the end users have reacted to / received the
message sent by the Brand. Quality Rating is assigned by WhatsApp; wherein particular user events such as
‘block the account’ or ‘reports an account' by the end-user is captured and an Algorithm is used to
determine user and consumer behavior and basis this pattern, a particular value, (High (GREEN), Low (RED),
Medium (YELLOW)) is assigned in the Quality Rating spectrum.

A lower Quality Rating only affects notification messages. The Brand can still continue to respond to user
initiated messages.
A lower Quality Rating does effect messaging limits, i.e. over a consecutive 7 day period if the Quality
Ratings do not improve, the WABA number has a higher chance of getting moved to a lower messaging limit
i.e. one tier lower than the current Messaging limit tier.
The different types of status and their relevance are as follows:

● ‘High’ Status indicates the messages are relevant alerts/notifications/response messages and of 1:1
nature.
● A ‘Medium’ or a ‘Low’ status indicates the alert/notification/response messages that were sent to
the users may not be exclusive and was 1:100 in nature.

The reason for a particular Quality Rating is based on what is collected as a feedback by WhatsApp when
the user hits ‘Block account’ in the profile section of the Business Account.

How to Maintain (or Improve) Quality Rating

1) Always share user relevant messages i.e. the nature of the message sent to the users must be
the ones they signed up / opted-in for.
For example: If a customer has opted for financial updates on WhatsApp while registering over the
bank app. Now, if the customer has initiated a conversation for a query, the 24 hour window for
conversations must not be used to upsell and cross sell bank offerings and products.

2) Implement a human escalation matrix which provides the end-user a mechanism to get in touch
with the brand via methods such as email or contact center support.

15
 3) Always specify a method for OPT-out i.e. option must be clearly specified on how the end –user
can opt out from receiving messages from the brand over WhatsApp.

4) Alert emails for change in the Quality Rating status are sent to the concerned POC for the Brand
/Account. It is suggested to closely monitor the status and make changes to any recently sent
templates which have a lower template Quality Rating status or response message sent to
user-initiated conversations.

5) Follow the WhatsApp Business Policy.

Messaging Limits

The Messaging limit tier affects how many customers your business can send messages to on a daily basis.
This includes new conversations as well as existing conversations with customers.
It also does NOT apply to messages sent in response to a user-initiated message within a 24-hour period.

The messaging limit is the maximum number of business-initiated conversations you can start in a rolling
24-hour period. If you reach your limit, you can start more conversations as soon as one or more active
conversations end.
A business-initiated conversation starts when the first message is delivered to a customer and ends 24 hours
later.

Tier 1: Allows your phone number to have 1,000 business-initiated conversations (with 1,000 unique
customers) in a rolling 24-hour period.

Tier 2: Allows your phone number to have 10,000 business-initiated conversations (with 10,000 unique
customers) in a rolling 24-hour period.

Tier 3: Allows your phone number to have 100,000 business-initiated conversations (with 100,000 unique
customers) in a rolling 24-hour period.

Unlimited: Allows your phone number to have unlimited business-initiated conversations in a rolling
24-hour period.

For a WhatsApp business number to upgrade to the next immediate tier, the Updated criteria are as below:

1. The WhatsApp Business phone number status is Connected.

2. The Quality Rating of the WhatsApp Business phone number is either Medium or High
3. In the last 7 days, The Business has initiated X or more conversations with unique customers, where
X is the current messaging limit divided by 2

For example, a business with a messaging limit of 1,000 business-initiated conversations gets its limit
increased to 10,000 when it messages a total of 500 unique users within a 7-day period and so on. The

16
business should remain in the current messaging tier for at least 24 hours after reaching 500 unique
customers.
An example is illustrated below:

Official Business Account

There are two types of WhatsApp Business Accounts, which determines how your business appears to
your customers.

Name Description How the Business appears to customers

Business Any account that is using the WhatsApp The name of the business is not visible if the
Account Business API is by default a customer hasn't added the business to their
Business Account. address book; instead the Business Phone
Number will be visible. In addition, if the
business sends a template notification which
contains a link, then links will not be clickable
Once the customer adds the business to their
address book or replies on the WhatsApp cha
the links become clickable.

We recommend that the first notification sent

users instruct them to save the number in the
address book.

17
 Official Busine WhatsApp has verified that an authentic An Official Business Account has a green
Account brand owns this account. checkmark badge in its profile and next to the
header in the chat thread. The name of the
business is visible even if the customer hasn't
Note: added the business to their address book.
The business must apply for an Official
Business Account status and will be However, if the customer has saved the busine
considered only after at least one month of to their address book, then the
go-live with an average Address Book Name takes precedence over th
traffic of at least 1000 messages per Verified Name of the Business.
Day over a 7 day period. WhatsApp decides
whether to grant the Official Business
Account status and the decision cannot be
contested.

Few things to note about the WhatsApp Official Business Account:

● The Official Business Account (verified badge ) is awarded by WhatsApp based on certain criteria
such as mentioned below (but not limited to )
1. Notability
2. Volumes
3. WhatsApp Business Account number Quality rating etc.

● Notability is defined by WhatsApp as: An account that must represent a well-known often searched
brand or entity. WhatsApp reviews accounts that are featured in multiple news sources, and they
don't consider paid or promotional content as sources for review.

● The decision to grant the Official Business Account (verified badge) is at WhatsApp’s discretion.

● Gupshup will raise the request to WhatsApp for an Official Business Account on behalf of the
Business.

● If WhatsApp has decided to not grant the OBA to the Business, the Business can re-apply after a
period of 30 days.

18
Gupshup Messaging API Reference

This guide provides the API specifications to send and receive messages to / from customers on WhatsApp
using the Gupshup Messaging API.

Concepts
Before using the Gupshup Messaging API, a few concepts that you should be familiar with:

​ Number Format: The Gupshup Messaging API supports numbers in E.164 format.

​ Authentication: The Gupshup Messaging API authenticates using your Gupshup account userId and
password.
​ Webhooks: These are user-defined HTTP/HTTPS callbacks that are triggered by specific events such as
an inbound message from a customer and can be forwarded to your application e.g. your CRM or
customer support platform or chat-bot.

API Endpoint
The Gupshup Messaging API resides at this endpoint:

https://media.smsgupshup.com/GatewayAPI/rest

Please use this URL for all API methods.

User Authentication Scheme

Currently, our API supports Plain Authentication Scheme for the user. This authentication scheme requires
only the user ID and password. The connection security is provided through HTTPS protocol and encryption
of parameters using AES-256 bit encryption.

HTTPS/SSL Support
Our API has been designed to allow you to access an SSL Enabled connection for added security i.e. the API
also support Hypertext Transfer Protocol over Secure Socket Layer (HTTPS) protocol.

The API call has syntax identical to the HTTP API call. However in case of an HTTPS call, the HTTP headers
shall be encrypted which provides better security of data. For this, enter the URL beginning with https://
instead of http://

Data Encryption
In addition to SSL, our API has been designed to allow you to securely send sensitive data to the Gupshup
platform by encrypting the data using Advanced Encryption Standard i.e. AES 256-bit encryption. On your
request (please reach out to us at 022 42006799 or email us at enterprise- [email protected] , a 256-bit
symmetric key is generated by Gupshup and set up for your account.

19
You must use this key to encrypt API parameter values when sending the API request. Once the request is
received by Gupshup, the payload is decrypted by Gupshup and sent ahead to WhatsApp.
Pre-Requisites
1. UserId & password. If you don’t have an account, please contact your account manager.
2. URL encoding of your message, password etc.
3. Encryption key in case you have opted for this feature
4. Verified Business Phone Number: To test sending of messages, you must have a Verified Business Phone
Number linked to your account.

For any queries our support is available for you at 022 42006799 or email us at enterprise-
[email protected]

API Collection:

The API collection that can be tested via API testing tool such as Postman is:
This collection contains entire set of working API requests for:

● Collecting/Revoking Consent i.e. Opt-in & Opt-out APIs

● Sending Messages – Text & Media Messages (interactive, button, list messages, Multi-product and
single product messages)
● Delivery event via callback URL
● Inbound web hook events via callback URL

Collection link that can be imported via Postman is as below:

https://api.postman.com/collections/3519024-03e026d7-7e24-4792-9b87-fbaf015991dd?access_key=PMA
T-01H3E8F20WWMKKMJBF0YCV4SKA

Opt-in a User

To send business-initiated messages (Notifications) to a user on WhatsApp, you must first collect the user’s
explicit consent to send such notifications on WhatsApp and then call the Gupshup Messaging API using the
OPT_IN API method to mark the user as ‘Opt-In’.

Please use this method responsibly and do not make an Opt-in API call unless the user has legitimately and
explicitly provided their consent to your business to send notifications on WhatsApp. Please read the Opt-in
Guidelines documentation shared by Gupshup to collect opt-ins from customers. You may be requested to
provide proof that you have collected the users’ consent at a later date.

20
API Endpoint
To mark a user as Opt-in, the API request is made to this endpoint:

https://media.smsgupshup.com/GatewayAPI/rest

Supported methods: GET, POST

Request Headers
Content-Type application/x-www-form-urlencoded

Request Body
Key Description Example
userid The userid of your Gupshup account. The number 2000155005
REQUIRED | string must be in pure numeric format with no special
Characters.
password The password of your Gupshup account for sh1gw4e
REQUIRED | string authentication of the userid
phone_number The phone number of the user who has provided 91989212345
REQUIRED | string explicit consent to the business to receive notifications
on WhatsApp. Number must be in
E.164 format.

method The API method to perform a specific action i.e. OPT_IN

REQUIRED | string mark the phone number as Opt-in user

Must be: OPT_IN

auth_scheme The authentication scheme of the API. plain
REQUIRED | string
Must be: plain
v The API version. 1.1
REQUIRED | string Must be: 1.1

21
 channel The channel for which user has provided WHATSAPP
REQUIRED | string Consent to be contacted by the business

Must be: WHATSAPP

format The API response message format. Default value is json
OPTIONAL | string text, unless otherwise specified.

Must be one of: text, json, xml

Sample Requests

Simple request
Below is a sample GET request to mark a user as Opt-In:

curl --location --request GET

'https://media.smsgupshup.com/GatewayAPI/rest?method=OPT_IN&format=json&u
serid=2000XXXXXX&password=XXXXXX&phone_number=919999999999&v=1.1&auth_sch
eme=plain&channel=WHATSAPP'

Encrypted request
Below is a sample GET request with encrypted data in the payload, to mark a user as Opt-In:

https://media.smsgupshup.com/GatewayAPI/rest?userid=2000XXXXXX&encrdata={{Base64_Encoded_E
ncrypted_ Data}}

where, value of encrdata =

{{method=OPT_IN&format=json&password=XXXXXXXX&phone_number=919777777778&v=1.1&auth_sc
heme=plain&channel=WHATSAPP}}

Please note:

​ The “userid” parameter is mandatory and its value is to be sent in an unencrypted format. All the other
parameters must be sent in encrypted format using AES 256 encryption and base64 encoded with the
Key shared, in the “encrdata” parameter.
​ You must use the key generated for your enterprise account to encrypt API parameter values when
sending the API request. Once the request is received by Gupshup, the payload is decrypted by
Gupshup and sent ahead to WhatsApp.
​ Please read Appendix A for detailed steps and code samples on how to encrypt the payload before
sending an API request.

22
API Response
A successful API request generates an HTTP 200 response. The response to a request where output format
was specified as json, is a JSON array with response status, unique identifier and method as OPT_IN.

{
"response": {
"id": "3795200898494416206",
"phone": "",
"details": "OPT_IN", "status": "success"
},
"data": {
"response_messages": [
{
"id": "3795200898494416206",
"phone": "919777777778",
"details": "OPT_IN", "status": "success"
}
]
}
}

This indicates that the mobile number 919777777778 has been successfully opted in under a Unique
Identifier ‘3795200898494416206’. The identifier string is unique for each recipient number and is auto
generated at the time of opt-in submission.

API Errors
An error response is generated when any of the required parameters is not specified correctly or any other
technical error exists. The error response will indicate an error code along with the actual error message.

Typical error response is:

{
"response": {
"id": "105",
"phone": "",
"details": "The phone number \"666\" is not a valid phone number", "status": "error"
}}

23
Opt-out a User
WhatsApp recommends that the business provide opted-in users with an option to opt-out from receiving
notifications on WhatsApp. One recommended method is to inform users about a STOP keyword on
WhatsApp to opt-out. Without such an option being made available, users have recourse to block the
Business phone number or report it as Spam from the WhatsApp profile, which may negatively affect the
Business’s quality rating and result in quality rating based rate limits being applied and possibly a total
suspension of the Business account if quality rating does not improve over time.

API Endpoint
To mark a user as Opt-out, the API request is made to this endpoint:

https://media.smsgupshup.com/GatewayAPI/rest

Supported methods: GET, POST

Request Headers

Content-Type application/x-www-form-urlencoded

Request Body

Key Description Example

userid The userid of your Gupshup account. The number 2000155005
REQUIRED | string must be in pure numeric format with no special
characters.
password The password of your Gupshup account for sh1gw4e
REQUIRED | string authentication of the userid
phone_number The phone number of the user who has elected to 91989212345
REQUIRED | string opt out from receiving notifications from the business
WhatsApp. Number must be in E.164
format.
method The API method to perform a specific action i.e. OPT_OUT
REQUIRED | string mark the phone number as Opt-in user

Must be: OPT_OUT

auth_scheme The authentication scheme of the API. plain
REQUIRED | string
Must be: plain
v The API version. 1.1
REQUIRED | string
Must be: 1.1

24
 channel The channel for which user has provided his whatsapp
REQUIRED | string consent to be contacted by the business

Must be: whatsapp

format The API response message format. Default value is json
OPTIONAL | string text, unless otherwise specified.

Must be one of: text, json, xml

Sample Requests

Simple request
Below is a sample GET request to mark a user as Opt-Out:

curl --location --request GET

'https://media.smsgupshup.com/GatewayAPI/rest?method=OPT_IN&format=json&userid=2
000XXXXXX&password=XXXXXX&phone_number=919999999999&v=1.1&auth_scheme=plain&chan
nel=WHATSAPP'

Encrypted request
Below is a sample GET request with encrypted data in the payload, to mark a user as Opt-Out:

https://media.smsgupshup.com/GatewayAPI/rest?userid=2000XXXXXX&encrdata={{Base64
_Encoded_Encrypted_ Data}}

where value of encrdata =

{{method=OPT_OUT&format=json&password=XXXXXXXX&phone_number=919777777778&v=1.1&auth
_scheme=plain&channel=WHATSAPP}}

Please note:

​ The “userid” parameter is mandatory and its value is to be sent in an unencrypted format. All the other
parameters must be sent in encrypted format using AES 256 encryption and base64 encoded with the
Key shared, in the “encrdata” parameter.
​ You must use the key generated for your enterprise account to encrypt API parameter values when
sending the API request. Once the request is received by Gupshup, the payload is decrypted by
Gupshup and sent ahead to WhatsApp.
​ Please read Appendix A for detailed steps and code samples on how to encrypt the payload before
sending an API request.

API Response
A successful API request generates an HTTP 200 response. The response to a request where output format

25
was specified as JSON, is a JSON array with response status, unique identifier and method as OPT_OUT.

{
"response": {
"id": "3622162179146741070",
"phone": "", "details": "OPT_OUT", "status": "success"
},
"data": {
"response_messages": [
{
"id": " 3622162179146741070",
"phone": "919777777778",
"details": "OPT_OUT", "status": "success"
}
]
}
}

This indicates that the mobile number 919777777778 has been successfully opted out under a Unique
Identifier-‘3622162179146741070’. The identifier string is unique for each recipient number and is auto
generated at the time of opt-out submission.

API Errors (for OPTIN & OPTOUT APIs)

An error response is generated when any of the required parameters is not specified correctly or any other
technical error exists. The error response will indicate an error code along with the actual error message.

A typical error response is

{
"response": {
"id": "105",
"phone": "",
"details": "The phone number \"666\" is not a valid phone number", "status": "error"
}
}

Below is the list of API failure or errors in case request is badly formed or parameters are missing

Error code (id) Error message (details)

100 An unknown exception has occurred. Please retry the request after some time.
101 The parameter X is required. Please resend request.
102 Authentication failed due to invalid userId or password.
103 Authentication Failed as userid X does not exist.
105 The phone number XXXXX is not a valid phone number.
106 The method is not supported.

26
175 The "INTERNATIONAL_PHONE" service is disabled for you. Kindly get the service
enabled before using this action
322 The phone number has already been marked as Opt-out

27
Send a Notification Message

Use the Gupshup Messaging API to send a business-initiated notification message to a customer on
WhatsApp. Sending notifications on WhatsApp requires adherence to opt-in policies and message
template approval process instituted by WhatsApp.

To send a Notification message to a user on WhatsApp, please ensure:

​ The user is already an “Opt-in” user i.e. you have called the OPT_IN API method previously

​ The message template is already approved by WhatsApp and Gupshup has confirmed this

Supported Message Types for Notifications

Type Supported Content-types

Text English and Unicode characters (max. 1024 characters per message)
Image image/jpeg, image/png
Document application/pdf
Video video/mp4
Note: Only H.264 video codec and AAC audio codec is supported.

Send a Text Template Notification

API Endpoint
To send a Notification message on WhatsApp, the API request is made to this endpoint:

https://media.smsgupshup.com/GatewayAPI/rest

Request Headers
Content-Type application/x-www-form-urlencoded

Request Body
Key Description Example
userid The userid of your Gupshup account. The number 2000155005
REQUIRED | string must be in pure numeric format with no special
characters.
password The password of your Gupshup account for sh1gw4e
REQUIRED | string authentication of the userid
method The API method to perform a specific action i.e. send a SendMessage
REQUIRED | string message on WhatsApp

Must be: SendMessage

28
auth_scheme The authentication scheme of the API. plain
REQUIRED | string Must be: plain

v The API version. 1.1

REQUIRED | string
Must be: 1.1
send_to The phone number of the recipient to whom message 919892123456
REQUIRED | string is being sent. Number must be in E.164
format.
msg The text message to be sent to the customer. It must Hello%20World!
REQUIRED | string be URL encoded.
msg_type The type of message to be sent to the customer. HSM
OPTIONAL | string Depending on ‘type’, the relevant parameters must be
sent as part of the request payload. By default, type is
TEXT unless otherwise specified.

It is recommended to send msg_type=HSM when sendin

Text Notifications on WhatsApp.

Must be one of: HSM, TEXT

isHSM This indicates whether the message is a Message Templa true
OPTIONAL | boolean (HSM) i.e. a pre-approved message template. Here, the A
will run a template check and submit the message as an
HSM to WhatsApp server. By default, unless specified, it
will be ‘false’

Must be one of: true, false

isTemplate This indicates if this is an Interactive Message template false
OPTIONAL | boolean (with CTA or Quick Reply buttons). This must always be
passed as isTemplate=true if it is an Interactive Message
Template

This must always be passed as isTemplate=true if it

is an Interactive Message Template or if it has header
and footer components

Must be one of: true, false

29
buttonUrlParam This is the dynamic suffix of the button URL for a developer/home
OPTIONAL | string Call-to-Action Interactive Button template of type “Visit
Website” where URL=Dynamic. The static prefix of the
button URL must be specified at the time of template
creation, since WhatsApp does not permit a completely
dynamic button URL for “Visit Website” type of
Call-to-Action button.

For example: If static prefix of button URL in

template is “https://www.gupshup.io/” and value of
buttonUrlParam=”developer/home”, then when user clic
on the Call-to-Action button, they are redirected to:
https://www.gupshup.io/developer/home

Note: If this parameter is passed for a Call-to-Action

Interactive Button template where URL=Static, you will g
a Template Mismatch error.
data_encoding The encoding type of the message i.e. plain English text Text
OPTIONAL | string Unicode i.e. message is in another language or contains
special characters / emoji .

Must be one of: text, Unicode_text

format The API response message format. Default value is text, json
OPTIONAL | string unless otherwise specified.

Must be one of: text, json, xml

msg_id A Custom message ID that can be specified by the 134389132153571381

OPTIONAL | string business. This will be attached to Message Status Callbac
and can help you track messages using your internal IDs.
200 characters alphanumeric values are allowed for
msg_id and it must be unique
for every message sent.

extra A Custom parameter that can be used as an identifier fo SUPER100SEGMENT

OPTIONAL | string reporting purposes. You can input any text in this
parameter and the same value will be
forwarded in the Status Callback. 50 alphanumeric
characters are allowed for this parameter.

header In a Text message, a header usually refers to the ‘Title’ o Text message :
OPTIONAL | string the message. “Booking confirmation fo
60 alphanumeric characters (with variable values) are Movie”
allowed for this parameter.

30
 footer A short line of text to the bottom of the message templa “Get yourself
OPTIONAL | string Only 60 alphanumeric characters are allowed for this web-checked-in, to avoid
parameter. queues”

qrPayload_1 Business - defined payload that will be returned when th Identifier1

button is clicked along with the display text on the butto
OPTIONAL | string There will be a maximum of 3 such request parameters
namely : qrPayload_1, qrPayload_2 & qrPayload_3

Maximum Payload length : 128 characters

Permitted characters type: Alphanumeric and special
characters and Unicode text.
linkTrackingEnabled This parameter can be used to specify linktracking for lin True
OPTIONAL | string present in the ‘msg’ request parameter
Must be : True/false

Sample requests:

Simple Text:

Below is a sample POST request for sending a text message on WhatsApp.

curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest' \

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'send_to=919999999999' \
--data-urlencode 'msg_type=Text' \
--data-urlencode 'userid=2000XXXXXX' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'password=XXXXXXX' \
--data-urlencode 'method=SendMessage' \
--data-urlencode 'v=1.1' \
--data-urlencode 'format=json' \
--data-urlencode ‘msg_id= ‘35553’
--data-urlencode 'msg=This is test message

Encrypted request

Below is a sample GET request with encrypted data in the payload, to send a message on WhatsApp:

https://media.smsgupshup.com/GatewayAPI/rest?userid=2000XXXXXX&encrdata={{Base6
4_Encoded_Encrypted_ Data}}

where, value of encrdata =

{{method=SendMessage&format=json&password=XXXXXXXX&send_to=919777777778&v=1.1&auth_sche

31
 me=plain&msg_type=HSM&msg=Welcome%20to%20Gupshup%20API}}

Please note:

​ The “userid” parameter is mandatory and its value is to be sent in an unencrypted format. All the other
parameters must be sent in encrypted format using AES 256 encryption and base64 encoded with the
shared key, in the “encrdata” parameter.
​ You must use the key generated for your enterprise account to encrypt API parameter values when
sending the API request. Once the request is received by Gupshup, the payload is decrypted by
Gupshup and sent ahead to WhatsApp.
​ Please read Appendix A for detailed steps and code samples on how to encrypt the payload before
sending the API request

Unicode Text

Simple request
Below is a sample GET request when sending a Unicode text message on WhatsApp

https://media.smsgupshup.com/GatewayAPI/rest?method=SendMessage&format=json&use
rid=2000XXXXXX&password=XXXXXXXX&send_to=919777777778&v=1.1&auth_scheme=plain&m
sg_type=HSM&data_encoding=Unicode_text&msg=Gupshup%20API%20%E0%A4%AE%E0%A5%87%E
0%A4%82%20%E0%A4%86%E0%A4%AA%E0%A4%95%E0%A4%BE%20%E0%A4%B8%E0%A5%8D%E0%A4%B5%E0
%A4%BE%E0%A4%97%E0%A4%A4%20%E0%A4%B9%E0%A5%88

Encrypted request

Below is a sample GET request with encrypted data in the payload, to send a Unicode message on
WhatsApp:

https://media.smsgupshup.com/GatewayAPI/rest?userid=2000XXXXXX&encrdata={{Base6
4_Encoded_Encrypted_ Data}}

where, value of encrdata =

{{method=SendMessage&format=json&password=XXXXXXXX&send_to=919777777778&v=1.1&auth_sche
me=plain&msg_type=HSM&data_encoding=Unicode_text&msg=Gupshup%20API%20%E0%A4%AE%E0%A5
%87%
E0%A4%82%20%E0%A4%86%E0%A4%AA%E0%A4%95%E0%A4%BE%20%E0%A4%B8%E0%A5%8D%E0%A4
%B5%E0%A4%BE%E0%A4%97%E0%A4%A4%20%E0%A4%B9%E0%A5%88}}

Please note:

32
​ The “userid” parameter is mandatory and its value is to be sent in an unencrypted format. All the other
parameters must be sent in encrypted format using AES 256 encryption and base64 encoded with the
Key shared, in the “encrdata” parameter.
​ You must use the key generated for your enterprise account to encrypt API parameter values when
sending the API request. Once the request is received by Gupshup, the payload is decrypted by
Gupshup and sent ahead to WhatsApp.
​ Please read Appendix A for detailed steps and code samples on how to encrypt the payload before
sending an API request.

Text with Header and Footer

Simple request with Header and Footer

Below is a sample POST request when sending a text message with Header and Footer.

curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest' \

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'send_to=919999999999' \
--data-urlencode 'msg_type=Text' \
--data-urlencode 'userid=2000XXXXXX' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'password=XXXXXXX' \
--data-urlencode 'method=SendMessage' \
--data-urlencode 'v=1.1' \
--data-urlencode 'format=json' \
--data-urlencode 'msg= This is test message' \
--data-urlencode 'header=Header text value' \
--data-urlencode 'footer=Footer text value' \
--data-urlencode 'isTemplate=true'

Text with CTA Buttons

Simple request with static Button URL

Below is a sample POST request when sending a text message with CTA Buttons on WhatsApp.

curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest' \

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'method=SendMessage' \
--data-urlencode 'userid=2000xxxxxx' \
--data-urlencode 'password=XXXXXXX' \
--data-urlencode 'msg= This is a test message.' \
--data-urlencode 'msg_type=TEXT' \

33
--data-urlencode 'format=json' \
--data-urlencode 'v=1.1' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'send_to=919999999999' \
--data-urlencode 'isTemplate=true'

Here, since the Button Template has static Call-to-Action buttons, it is exactly similar to sending a simple
text message except for isTemplate=true parameter. This will ensure that the Call-to-Action button template
is sent on WhatsApp as expected

Simple request with dynamic Button URL

Below is a sample POST request when sending a text message with CTA Buttons on WhatsApp.

curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest' \

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'method=SendMessage' \
--data-urlencode 'userid=2000xxxxxx' \
--data-urlencode 'password=XXXXXXX' \
--data-urlencode 'msg= This is a test message.' \
--data-urlencode 'msg_type=TEXT' \
--data-urlencode 'format=json' \
--data-urlencode 'v=1.1' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'send_to=919999999999' \
--data-urlencode 'isTemplate=true' \
--data-urlencode 'buttonUrlParam=dynamicURLpart'

Encrypted request with dynamic Button URL

Below is a sample GET request with encrypted data in the payload, to send a text message with CTA Buttons
on WhatsApp:

https://media.smsgupshup.com/GatewayAPI/rest?userid=2000XXXXXX&encrdata={{Base64
_Encoded_Encrypted_ Data}}

where, value of encrdata =

{{method=SendMessage&format=json&password=XXXXXXXX&send_to=919777777778&v=1.1&auth_sch
eme=plain&msg_type=HSM&isTemplate=true&buttonUrlParam=bDQ2NTkz&msg=This%20is%20your%20fli
ght%20confirmation%20for%20Mumbai%20(BOM)%20%20Bengaluru%20(BLR)%20on%20May%2022%2C%
202020%20at%2018%3A50%20hours.}}

Please note:
​ The “userid” parameter is mandatory and its value is to be sent in an unencrypted format. All the other
parameters must be sent in encrypted format using AES 256 encryption and base64 encoded with the

34
 Key shared, in the “encrdata” parameter.
​ You must use the key generated for your enterprise account to encrypt API parameter values when
sending the API request. Once the request is received by Gupshup, the payload is decrypted by
Gupshup and sent ahead to WhatsApp.
​ Please read Appendix A for detailed steps and code samples on how to encrypt the payload before
sending an API request
Text with Quick Reply Buttons

Simple request

Below is a sample POST request when sending a text message with Quick Reply Buttons on WhatsApp.

curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest' \

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'method=SendMessage' \
--data-urlencode 'userid=2000xxxxxx' \
--data-urlencode 'password=XXXXXXX' \
--data-urlencode 'msg=This is a test message.' \
--data-urlencode 'msg_type=TEXT' \
--data-urlencode 'format=json' \
--data-urlencode 'v=1.1' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'send_to=919999999999' \
--data-urlencode 'isTemplate=true'

Here, since the Button Template has static Quick Reply buttons, it is exactly similar to sending a simple text
message except for isTemplate=true parameter. This will ensure that the Quick Reply button template is
sent on WhatsApp as expected.

Encrypted request

Below is a sample GET request with encrypted data in the payload, to send a text message with Quick Reply
Buttons on WhatsApp:

https://media.smsgupshup.com/GatewayAPI/rest?userid=2000XXXXXX&encrdata={{Base64
_Encoded_Encrypted_ Data}}

where, value of encrdata =

{{method=SendMessage&format=json&password=XXXXXXXX&send_to=919777777778&v=1.1&auth_sch
eme=plain&msg_type=HSM&isTemplate=true&msg=How%20much%20data%20do%20you%20need%3F%0
A%0AC hoose%20from%20one%20of%20the%20options%20below.}}

35
Text with Quick Reply Buttons with custom Payload

curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest' \

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'method=SendMessage' \
--data-urlencode 'userid=2000xxxxxx' \
--data-urlencode 'password=XXXXXXX' \
--data-urlencode 'msg=This is a test message.' \
--data-urlencode 'msg_type=TEXT' \
--data-urlencode 'format=json' \
--data-urlencode 'v=1.1' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'send_to=919999999999' \
--data-urlencode 'qrPayload_1=PAYLOAD_FOR_BUTTON_1' \
--data-urlencode 'qrPayload_2=PAYLOAD_FOR_BUTTON_2' \
--data-urlencode 'qrPayload_3=PAYLOAD_FOR_BUTTON_3' \
--data-urlencode 'isTemplate=true'

Please note:

​ The “userid” parameter is mandatory and its value is to be sent in an unencrypted format. All the other
parameters must be sent in encrypted format using AES 256 encryption and base64 encoded with the
Key shared, in the “encrdata” parameter.
​ You must use the key generated for your enterprise account to encrypt API parameter values when
sending the API request. Once the request is received by Gupshup, the payload is decrypted by
Gupshup and sent ahead to WhatsApp.

Please read Appendix A for detailed steps and code samples on how to encrypt the payload before
sending an API request.

Send a Media Template Notification

The method for sending a media template message is “SendMediaMessage”. There are two approaches to
sending a media template notification on WhatsApp:
Pass the public media URL as an API parameter using SendMediaMessage API
First use the UploadMedia API to upload the media file. This API returns a media_id, which can then be
passed as an API parameter in SendMediaMessage API. This is a 2-step process.

Media Type Max. Media Upload Size

Image 5 MB
Document 100 MB
Video 16 MB

36
Using Media URL

API Endpoint
To send a media message on WhatsApp using a media_url as a parameter, the API request is made to this
endpoint:

https://media.smsgupshup.com/GatewayAPI/rest

Request Headers
Content-Type application/x-www-form-urlencoded

Request Body
Key Description Example
userid The userid of your Gupshup account. The number must be i 2000155005
REQUIRED | string pure numeric format with no special characters.

Note: Gupshup will provide separate userid and password t

send Customer Support reply messages, it will not be the
same as the userid to send Notifications.

password The password of your Gupshup account for sh1gw4e

REQUIRED | string authentication of the userid
method The API method to perform a specific action i.e. send a SendMediaMessage
REQUIRED | string message on WhatsApp

Must be: SendMediaMessage

auth_scheme The authentication scheme of the API. Plain
REQUIRED | string
Must be: plain
v The API version. 1.1
REQUIRED | string
Must be: 1.1
send_to The phone number of the recipient to whom 919892123456
REQUIRED | string message is being sent. Number must be in E.164 format.

msg_type The type of message to be sent to the customer. IMAGE

REQUIRED | string
Must be one of: IMAGE, DOCUMENT, VIDEO
media_url The Public URL where the media attachment file is https://image.shutterst
REQUIRED | string hosted. k.c om/image-
illustration/movie-ticke
icon-260nw-663331288
g
37
caption The caption text to be sent along with the media attachmen Your ticket is confirmed
REQUIRED | string This must exactly match the media for 20-DEC-2019.
template that is pre-approved by WhatsApp.
This can be a maximum of 1024 characters as per WhatsAp
media template specifications.
isHSM This indicates whether the message is a Message Template True
OPTIONAL | boolean (HSM) i.e. a pre-approved message template. Here, the API
will run a template check and submit the message as an HS
to WhatsApp server. By default, unless specified, it will be
‘false’

Must be one of: true, false

isTemplate This indicates if this is an Interactive Message template (wit false
OPTIONAL | boolean CTA or Quick Reply buttons). This must always be passed as
isTemplate=true if it is an Interactive
Message Template

This must always be passed as isTemplate=true if it is

an Interactive Message Template or if it has header
and footer components

Must be one of: true, false

buttonUrlParam This is the dynamic suffix of the button URL for a developer/home
OPTIONAL | string Call-to-Action Interactive Button template of type
“Visit Website” where URL is of type - Dynamic.
The static prefix of the button URL must be specified
at the time of template creation, since WhatsApp
does not permit a completely dynamic button URL for “Visit
Website” type of Call-to-Action button.

For example: If static prefix of button URL in

template is “https://www.gupshup.io/” and value of
buttonUrlParam=”developer/home”, then when user clicks
the Call-to-Action button, they are
redirected to: https://www.gupshup.io/developer/home

Note: If this parameter is passed for a Call-to-Action

Interactive Button template where URL=Static, you will get
Template Mismatch error.
msg The text message to be sent to the customer via SMS if Your ticket is confirmed
OPTIONAL | string fallback to SMS is configured. for 20-DEC-2019. Click t
view
your ticket
https://gs.im/d/hgsa2g
data_encoding The encoding type of the message i.e. plain English text or text
OPTIONAL | string Unicode i.e. message is in another language or contains
special characters / emoji .

38
 Must be one of: text, Unicode_text
format The API response message format. Default value is text, json
OPTIONAL | string unless otherwise specified.
Must be one of: text, json, xml
filename This is an optional filename that can be passed in case of File1.pdf
OPTIONAL | string msg_type=DOCUMENT.

msg_id A Custom message ID that can be specified by the business. 134389132153571381

OPTIONAL | string This will be attached to Message Status Callbacks and can
help you track messages using your internal IDs. 200
characters alphanumeric values are allowed for msg_id and
must be unique
for every message sent.
extra A Custom parameter that can be used as an identifier for SUPER100SEGMENT
OPTIONAL | string reporting purposes. You can input any text in this paramete
and the same value will be forwarded in the Status
Callback. 50 alphanumeric
Characters are allowed for this parameter.
footer A short line of text to the bottom of the message template “Get yourself
OPTIONAL | string web-checked-in, to avo
queues”

qrPayload_1 Business - defined payload that will be returned when the Identifier1
button is clicked along with the display text on the button.
OPTIONAL | string There will be a maximum of 3 such request parameters
namely : qrPayload_1, qrPayload_2 & qrPayload_3
Maximum Payload length : 128 characters
Permitted characters type: Alphanumeric and special
characters and Unicode text.
linkTrackingEnabled This parameter can be used to specify link tracking for links True
OPTIONAL | string present in the ‘caption’ request parameter
Must be : True/false

Sample Requests

Image
Below is a sample POST request when sending an image in media template on WhatsApp.

curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest'

\
--header 'Content-Type: application/x-www-form-urlencoded' \

39
 --data-urlencode 'send_to=91xxxxxxxxxx' \
--data-urlencode 'msg_type=IMAGE' \
--data-urlencode 'userid=2000xxxxxx' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'password=xxxxxxx' \
--data-urlencode 'method=SendMediaMessage' \
--data-urlencode 'v=1.1' \
--data-urlencode 'format=text' \
--data-urlencode
'media_url=https://homepages.cae.wisc.edu/~ece533/images/airplane.png' \
--data-urlencode 'caption= This is a test message.'

Document
Below is a sample POST request when sending a document / file in media template on WhatsApp.

curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest' \

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'send_to=91XXXXXXXXXXXX' \
--data-urlencode 'msg_type=DOCUMENT' \
--data-urlencode 'userid=2000XXXXXX' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'password=XXXXXX' \
--data-urlencode 'v=1.1' \
--data-urlencode 'format=text' \
--data-urlencode 'caption=This is a test message.' \
--data-urlencode 'isHSM=true' \
--data-urlencode 'method=SendmediaMessage' \
--data-urlencode 'filename=24234' \
--data-urlencode
'media_url=http://enterprise.smsgupshup.com/help/in/EnterpriseAPIDocument.pdf'

Video
Below is a sample POST request when sending a video in media template on WhatsApp.

curl --location --request POST 'http://media.smsgupshup.com/GatewayAPI/rest' \

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'msg_type=VIDEO' \
--data-urlencode 'userid=2000XXXXXX' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'password=XXXXXX' \
--data-urlencode 'v=1.1' \
--data-urlencode 'format=text' \
--data-urlencode 'media_url=http://clips.vorwaerts-gmbh.de/VfE_html5.mp4' \
--data-urlencode 'caption=This is test message' \
--data-urlencode 'isHSM=true' \
--data-urlencode 'method=SendmediaMessage' \

40
--data-urlencode 'send_to=91XXXXXXX'

Encrypted Media
Below is a sample GET request with encrypted data in the payload, to send a document on WhatsApp:

https://media.smsgupshup.com/GatewayAPI/rest?userid=2000XXXXXX&encrdata={{Base64
_Encoded_Encrypted_ Data}}

where, value of encrdata =

{{method=SendMediaMessage&format=json&password=XXXXXXXX&send_to=919777777778&v=1.1&auth
_scheme=plain&isHSM=true&msg_type=DOCUMENT&media_url=http://www.africau.edu/images/default
/samp le.pdf&caption=Account%20Statement}}

Image with Footer:

Below is a sample GET request when sending an image Footer on WhatsApp.

https://media.smsgupshup.com/GatewayAPI/rest?method=SendMediaMessage&format=json
&userid=2000XXXXXX&password=XXXXXXXX&send_to=919777777778&v=1.1&auth_scheme=plai
n&isHSM=true&msg_type=IMAGE&m
edia_url=https://image.shutterstock.com/image-illustration/movie-ticket-icon-260
nw-663331288.jpg&caption=
Your%20ticket%20is%20confirmed%20for%2020-DEC-2019&footer=Please%20use%20the%20Q
R%20scanner%20to%20scan%20at%20the%20Entrance.&isTemplate=true

Image with CTA Buttons (Static)

Below is a sample GET request when sending an image in Interactive CTA Button template on WhatsApp.

https://media.smsgupshup.com/GatewayAPI/rest?method=SendMediaMessage&format=json
&userid=2000XXXXXX&password=XXXXXXXX&send_to=919777777778&v=1.1&auth_scheme=plai
n&isHSM=true&isTemplate=true&ms
g_type=IMAGE&media_url=https://image.shutterstock.com/image-illustration/movie-t
icket-icon-260nw-
663331288.jpg&caption=Your%20ticket%20is%20confirmed%20for%2020-DEC-2019

Here, since the Button Template has static Call-to-Action buttons, it is exactly similar to sending a simple

41
Media Template message except for isTemplate=true parameter. This will ensure that the Call-to-Action
button template is sent on WhatsApp as expected.

Document with CTA Buttons (Dynamic)

Below is a sample GET request when sending a document / file in Interactive CTA Button template on
WhatsApp.

https://media.smsgupshup.com/GatewayAPI/rest?method=SendMediaMessage&format=json
&userid=2000XXXXXX&password=XXXXXXXX&send_to=919777777778&v=1.1&auth_scheme=plai
n&isHSM=true&msg_type=DOCUMENT&media_url=http://www.africau.edu/images/default/sa
mple.pdf&caption=Here%20is%20your%20Account%20Statement&filename=Acct%20Stmt&isT
emplate=true&buttonUrlParam=CcPay/1217311

Video with Quick Reply Buttons

Below is a sample GET request when sending a video in Interactive Quick Reply Button template on
WhatsApp.

https://media.smsgupshup.com/GatewayAPI/rest?method=SendMediaMessage&format=json
&userid=2000XXXXXX&password=XXXXXXXX&send_to=919777777778&v=1.1&auth_scheme=plai
n&isHSM=true&isTemplate=true&msg_type=VIDEO&media_url=http://techslides.com/demos
.mp4&caption=Here%20is%20your%20personalized%20welcome%20video%20kit%20for%20you
r%20 Policy%2012345678

Image with Quick Reply Buttons with custom payload

https://media.smsgupshup.com/GatewayAPI/rest?method=SendMediaMessage&format=json
&userid=2000XXXXXX&password=XXXXXXXX&send_to=919777777778&v=1.1&auth_scheme=plai
n&isHSM=true&isTemplate=true&msg_type=IMAGE&media_url=https://techslides.com/imag
e1.png&caption=Here%20is%20your%20personalized%20welcome%20video%20kit%20for%20y
our%20Policy%2012345678&qrPayload_1=payload1&qrPayload_2=payload2&qrPayload_3=pa
yload3

Here, since the Button Template has static Quick Reply buttons, it is exactly similar to sending a simple
text message except for isTemplate=true parameter. This will ensure that the Quick Reply button template is
sent on WhatsApp as expected.

42
Please note:

​ The “userid” parameter is mandatory and its value is to be sent in an unencrypted format. All the other
parameters must be sent in encrypted format using AES 256 encryption and base64 encoded with the
Key shared, in the “encrdata” parameter.
​ You must use the key generated for your enterprise account to encrypt API parameter values when
sending the API request. Once the request is received by Gupshup, the payload is decrypted by
Gupshup and sent ahead to WhatsApp.
​ Please read Appendix A for detailed steps and code samples on how to encrypt the payload before
sending an API request.
Upload Media

In this approach, first use the UploadMedia API to upload the media file. This API returns a media_id, which
can then be passed as an API parameter in SendMediaMessage API.

Use this approach when you don’t have a publically hosted media file or if you want to send the same media
file to all recipients like a document or an image that is not customized to every individual.

API Endpoint
To upload a media message on WhatsApp, the API request is made to this endpoint:

https://media.smsgupshup.com/GatewayAPI/rest

Request Headers
Content-Type application/x-www-form-urlencoded

Request Body
Key Description Example
userid The userid of your Gupshup account. The number mus 2000155005
REQUIRED | string be in pure numeric format with no special characters.

Note: Gupshup will provide separate userid and

password to send Customer Support reply messages, it
will not be the same as the userid to send Notifications

password The password of your Gupshup account for sh1gw4e

REQUIRED | string authentication of the userid

43
 method The API method to perform a specific action i.e. upload UploadMedia
REQUIRED | string media file.

Must be: UploadMedia

auth_scheme The authentication scheme of the API. Plain
REQUIRED | string
Must be: plain
v The API version. 1.1
REQUIRED | string
Must be: 1.1
send_to The phone number of the recipient to whom message 919892123456
REQUIRED | string being sent. Number must be in E.164
format.
media_type The type of message to be uploaded. IMAGE
REQUIRED | string Must be one of: IMAGE, DOCUMENT, VIDEO
media_file The local filepath of the media file on the server @/media/DATA/sample.pdf
REQUIRED | string from where the API request is being made
format The API response message format. Default value is text Json
OPTIONAL | string unless otherwise specified.

Must be one of: text, json, xml

Sample Requests

curl --location 'https://mediaapi.smsgupshup.com/GatewayAPI/rest' \

--form 'media_type="DOCUMENT"' \
--form 'userid="20001xxxx"' \
--form 'password="xxxxx"' \
--form 'v="1.1"' \
--form 'auth_scheme="plain"' \
--form 'format="json"' \
--form 'media_file=@"T76w-WI_K/API Document for Template Id based API.pdf"' \
--form 'method="UploadMedia"'

Image
Below is a sample POST request when uploading an image in media template on WhatsApp.

API URL https://media.smsgupshup.com/GatewayAPI/rest

Request Headers Content-Type: application/json
Content-Type: multipart/form-data; boundary=----
WebKitFormBoundary7MA4YWxkTrZu0gW

44
 Request Body method=UploadMedia
media_type=image
userid=2000XXXXXX
password=*****
v=1.1
auth_scheme=plain
format=json
media_file=@/media/DATA/sample.jpg

Document
Below is a sample POST request when uploading a document / file in media template on WhatsApp.

API URL https://media.smsgupshup.com/GatewayAPI/rest

Request Headers Content-Type: application/json
Content-Type: multipart/form-data; boundary=----
WebKitFormBoundary7MA4YWxkTrZu0gW
Request Body method=UploadMedia
media_type=document
userid=2000XXXXXX
password=*****
v=1.1
auth_scheme=plain
format=json
media_file=@/media/DATA/sample.pdf

Video
Below is a sample POST request when uploading a video in media template on WhatsApp.

API URL https://media.smsgupshup.com/GatewayAPI/rest

Request Headers Content-Type: application/json
Content-Type: multipart/form-data; boundary=----
WebKitFormBoundary7MA4YWxkTrZu0gW
Request Body method=UploadMedia
media_type=video
userid=2000XXXXXX
password=*****
v=1.1
auth_scheme=plain
format=json
media_file=@/media/DATA/sample.mp4

API Response
A successful API request generates an HTTP 200 response. The response to a request where output format
was specified as json, is a JSON array with response status and unique identifier

45
 {
"response": {
"id":
"3sFftGeO3jT3HOoAvkbfO8Gkt_rQl3DrjwCO7jQF_0WwWCUC6PPpDo9JHBkObP7xBw7eIEcIF797AtWpXl
M",
"phone": "",
"details": "", "status": "success"
}
}
This indicates that the media file has been successfully uploaded under a Unique Media ID
‘3sFftGeO3jT3HOoAvkbfO8Gkt_rQl3DrjwCO7jQF_0WwWCUC6PPpDo9JHBkObP7xBw7eIEcIF797AtWpXl M’.
The identifier string is unique for each media file uploaded and is auto generated at the time of upload
submission. This media ID value is to be used in the SendMediaMessage API in the ‘media_id’ parameter in
order to send a media message on WhatsApp.

API Errors
An error response is generated when any of the required parameters is not specified correctly or any other
technical error exists. The error response will indicate an error code along with the actual error message.
{
"response": {
"id": "328",
"phone": "",
"details": "Invalid Media Content Type", "status": "error"
}}

Using Media ID

API Endpoint
To send a media message on WhatsApp using a media_id (generated by calling the UploadMedia API) as a
parameter, the API request is made to this endpoint:

https://media.smsgupshup.com/GatewayAPI/rest

Request Headers
Content-Type application/x-www-form-urlencoded

46
Request Body

Key Description Example

userid The userid of your Gupshup account. The number mus 2000155005
REQUIRED | string be in pure numeric format with no special characters.

Note: Gupshup will provide separate userid and

password to send Customer Support reply messages, it
will not be the same as the userid to send Notifications

password The password of your Gupshup account for sh1gw4e

REQUIRED | string authentication of the userid
method The API method to perform a specific action i.e. send a SendMediaMessage
REQUIRED | string message on WhatsApp

Must be: SendMediaMessage

auth_scheme The authentication scheme of the API. plain
REQUIRED | string
Must be: plain
v The API version. 1.1
REQUIRED | string
Must be: 1.1
send_to The phone number of the recipient to whom 919892123456
REQUIRED | string message is being sent. Number must be in E.164 forma

msg_type The type of message to be sent to the customer. IMAGE

REQUIRED | string
Must be one of: IMAGE, DOCUMENT
media_id The media ID returned in response to the UploadMedia 3sFftGeO3jT3HOoAvkbfO8G
REQUIRED | string API call. kt_rQl3DrjwCO7jQF_0WwW
CUC6PPpDo9JHBkObP7xBw
7eIEcIF797AtWpXlM
caption The caption text to be sent along with the media Your ticket is confirmed for
REQUIRED | string attachment. This must exactly match the media templa 20-DEC-2019.
that is pre-approved by WhatsApp.

This can be a maximum of 1024 characters as per

WhatsApp media template specifications.
msg The text message to be sent to the customer via SMS if Your ticket is confirmed
OPTIONAL | string fallback to SMS is configured. 20-DEC-2019. Click to vi
your ticket
https://gs.im/d/hgsa2gw

47
isHSM This indicates whether the message is a Message true
OPTIONAL | boolean Template (HSM) i.e. a pre-approved message template
Here, the API will run a template check and submit the
message as an HSM to WhatsApp
server. By default, unless specified, it will be ‘false’

Must be one of: true, false

isTemplate This indicates if this is an Interactive Message template false
OPTIONAL | boolean (with CTA or Quick Reply buttons). This must always be
passed as isTemplate=true if it is an Interactive Messag
Template

This must always be passed as isTemplate=true if it is

Interactive Message Template or if it has footer
components

Must be one of: true, false

buttonUrlParam This is the dynamic suffix of the button URL for a developer/home
OPTIONAL | string Call-to-Action Interactive Button template of type “Visi
Website” where URL=Dynamic. The static prefix of the
button URL must be specified at the time of template
creation, since WhatsApp does not permit a completel
dynamic button URL for “Visit Website” type of
Call-to-Action button.

For example: If static prefix of button URL in

template is “https://www.gupshup.io/” and value of
buttonUrlParam=”developer/home”, then when user
clicks on the Call-to-Action button, they are redirected
to: https://www.gupshup.io/developer/home

Note: If this parameter is passed for a Call-to-Action

Interactive Button template where URL=Static, you will
get a Template Mismatch error.
data_encoding The encoding type of the message i.e. plain English tex Text
OPTIONAL | string or Unicode i.e. message is in another language or
contains special characters / emoji .

Must be one of: text, Unicode_text

format The API response message format. Default value is text json
OPTIONAL | string unless otherwise specified.

Must be one of: text, json, xml

48
filename This is an optional filename that can be passed in json
OPTIONAL | string case of msg_type =DOCUMENT.

msg_id A Custom message ID that can be specified by the 134389132153571381

OPTIONAL | string business. This will be attached to Message Status
Callbacks and can help you track messages using your
internal IDs. 200 characters alphanumeric values are
allowed for msg_id and it must be unique for every
message sent.
extra A Custom parameter that can be used as an SUPER100SEGMENT
OPTIONAL | string identifier for reporting purposes. You can input any tex
in this parameter and the same value will be forwarded
in the Status Callback. 50 alphanumeric Characters are
allowed for this parameter.
footer A short line of text to the bottom of the message “Get yourself web-checked-
OPTIONAL | string template. to avoid queues”
60 alphanumeric characters are allowed for this
parameter.

qrPayload_1 Business - defined payload that will be returned when Identifier1

the button is clicked along with the display text on the
OPTIONAL | string button.
There will be a maximum of 3 such request paramete
namely : qrPayload_1, qrPayload_2 & qrPayload_3
Maximum Payload length : 128 characters
Permitted characters type: Alphanumeric and special
characters and Unicode text.
linkTrackingEnabled This parameter can be used to specify link tracking for True
OPTIONAL | string links present in the ‘caption’ request parameter
Must be : True/false

49
Sample Requests

Image
Below is a sample POST request when sending an image in media template on WhatsApp.

curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest' \

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'send_to=9999999999' \
--data-urlencode 'msg_type=IMAGE' \
--data-urlencode 'userid=2000xxxxxx' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'password=xxxxxxx' \
--data-urlencode 'method=SendMediaMessage' \
--data-urlencode 'v=1.1' \
--data-urlencode 'format=text' \
--data-urlencode 'media_id=3sFftGeO3jT3HOoAvkbfO8Gkt_rQl3DrjwCO7jQF_0WwW
CUC6PPpDo9JHBkObP7xBw7eIEcIF797AtWpXlM' \
--data-urlencode 'caption=This is a test message.'

Document
Below is a sample POST request when sending a document / file in media template on WhatsApp.

curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest'

\
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'send_to=91XXXXXXXXXXXX' \
--data-urlencode 'msg_type=DOCUMENT' \
--data-urlencode 'userid=2000XXXXXX' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'password=XXXXXX' \
--data-urlencode 'v=1.1' \
--data-urlencode 'format=text' \
--data-urlencode 'caption=This is a test message.' \
--data-urlencode 'isHSM=true' \
--data-urlencode 'method=SendmediaMessage' \
--data-urlencode 'filename=24234.pdf' \
--data-urlencode 'media_id=3sFftGeO3jT3HOoAvkbfO8Gkt_rQl3DrjwCO7jQF_0WwW
CUC6PPpDo9JHBkObP7xBw7eIEcIF797AtWpXlM'

Video
Below is a sample POST request when sending a video in media template on WhatsApp

curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest' \

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'msg_type=VIDEO' \
--data-urlencode 'userid=2000XXXXXX' \

50
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'password=XXXXXX' \
--data-urlencode 'v=1.1' \
--data-urlencode 'format=text' \
--data-urlencode 'media_id=3sFftGeO3jT3HOoAvkbfO8Gkt_rQl3DrjwCO7jQF_0WwW
CUC6PPpDo9JHBkObP7xBw7eIEcIF797AtWpXlM ' \
--data-urlencode 'caption=This is test message' \
--data-urlencode 'isHSM=true' \
--data-urlencode 'method=SendmediaMessage' \
--data-urlencode 'send_to=91XXXXXXX'

Encrypted Media
Below is a sample POST request with encrypted data in the payload, to send a document on WhatsApp:

https://media.smsgupshup.com/GatewayAPI/rest?userid=2000XXXXXX&encrdata={{Base64
_Encoded_Encrypted_ Data}}

where, value of encrdata =

{{method=SendMediaMessage&format=json&password=XXXXXXXX&send_to=919777777778&v=1.1&auth_
scheme=plain&isHSM=true&msg_type=DOCUMENT&media_id=3sFftGeO3jT3HOoAvkbfO8Gkt_rQl3DrjwCO
7jQ F_0WwWCUC6PPpDo9JHBkObP7xBw7eIEcIF797AtWpXlM&caption=Account%20Statement}}

Please note:

● The “userid” parameter is mandatory and its value is to be sent in an unencrypted format. All the
other parameters must be sent in encrypted format using AES 256 encryption and base64 encoded
with the Key shared, in the “encrdata” parameter.
● You must use the key generated for your enterprise account to encrypt API parameter values when
sending the API request. Once the request is received by Gupshup, the payload is decrypted by
Gupshup and sent ahead to WhatsApp.

● Please read Appendix A for detailed steps and code samples on how to encrypt the payload before
sending an API request.

Image with CTA Buttons (Static)

Below is a sample GET request when sending an image in Interactive CTA Button template on WhatsApp.

curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest' \

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'method=SendMediaMessage' \
--data-urlencode 'userid=2000xxxxxx' \
--data-urlencode 'password=XXXXXXX' \
--data-urlencode 'caption=This is a test message.' \
--data-urlencode 'msg_type=IMAGE' \
--data-urlencode 'format=json' \
--data-urlencode 'v=1.1' \

51
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'send_to=919999999999' \
--data-urlencode 'isTemplate=true' \
--data-urlencode 'media_id=3sFftGeO3jT3HOoAvkbfO8Gkt_rQl3DrjwCO7jQF_0WwW
CUC6PPpDo9JHBkObP7xBw7eIEcIF797AtWpXlM'

Here, since the Button Template has static Call-to-Action buttons, it is exactly similar to sending a simple
Media Template message except for isTemplate=true parameter. This will ensure that the Call-to-Action
button template is sent on WhatsApp as expected.

Image with CTA Buttons (Static) and Footer

Below is a sample POST request when sending a Image along with static Interactive CTA Button template on
WhatsApp.

curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest' \

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'method=SendMediaMessage' \
--data-urlencode 'userid=2000xxxxxx' \
--data-urlencode 'password=XXXXXXX' \
--data-urlencode 'caption=This is a test message.' \
--data-urlencode 'msg_type=IMAGE' \
--data-urlencode 'format=json' \
--data-urlencode 'v=1.1' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'send_to=919999999999' \
--data-urlencode 'isTemplate=true' \
--data-urlencode 'media_id=3sFftGeO3jT3HOoAvkbfO8Gkt_rQl3DrjwCO7jQF_0WwW
CUC6PPpDo9JHBkObP7xBw7eIEcIF797AtWpXlM' \
--data-urlencode 'footer=Always at your service'
Document with CTA Buttons (Dynamic)
Below is a sample POST request when sending a document / file in Interactive CTA Button template on
WhatsApp.

curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest'

\
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'method=SendMediaMessage' \
--data-urlencode 'userid=2000xxxxxx' \
--data-urlencode 'password=XXXXXXX' \
--data-urlencode 'caption=This is a test message.' \
--data-urlencode 'msg_type=DOCUMENT' \
--data-urlencode 'format=json' \
--data-urlencode 'v=1.1' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'send_to=919999999999' \
--data-urlencode 'isTemplate=true' \
--data-urlencode 'buttonUrlParam=dynamicURLpart' \
--data-urlencode 'media_id=3sFftGeO3jT3HOoAvkbfO8Gkt_rQl3DrjwCO7jQF_0WwW
CUC6PPpDo9JHBkObP7xBw7eIEcIF797AtWpXlM'

52
Video with Quick Reply Buttons

Below is a sample POST request when sending a video in Interactive Quick Reply Button template on
WhatsApp.

curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest' \

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'method=SendMediaMessage' \
--data-urlencode 'userid=2000xxxxxx' \
--data-urlencode 'password=XXXXXXX' \
--data-urlencode 'caption=This is a test message.' \
--data-urlencode 'msg_type=VIDEO' \
--data-urlencode 'format=json' \
--data-urlencode 'v=1.1' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'send_to=919999999999' \
--data-urlencode 'isTemplate=true' \
--data-urlencode 'media_id=3sFftGeO3jT3HOoAvkbfO8Gkt_rQl3DrjwCO7jQF_0WwW
CUC6PPpDo9JHBkObP7xBw7eIEcIF797AtWpXlM'

Here, since the Button Template has static Quick Reply buttons, it is exactly similar to sending a simple
Media Template message except for the isTemplate=true parameter. WhatsApp will recognize it as a Quick
Reply Button Template and will display it accordingly.

Video with Quick Reply Buttons with Payload

curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest' \

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'method=SendMediaMessage' \
--data-urlencode 'userid=2000xxxxxx' \
--data-urlencode 'password=XXXXXXX' \
--data-urlencode 'caption=This is a test message.' \
--data-urlencode 'msg_type=VIDEO' \
--data-urlencode 'format=json' \
--data-urlencode 'v=1.1' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'send_to=919999999999' \
--data-urlencode 'isTemplate=true' \
--data-urlencode 'media_id=3sFftGeO3jT3HOoAvkbfO8Gkt_rQl3DrjwCO7jQF_0WwW
CUC6PPpDo9JHBkObP7xBw7eIEcIF797AtWpXlM' \
--data-urlencode 'qrPayload_1=PAYLOAD_FOR_BUTTON_1' \
--data-urlencode 'qrPayload_2=PAYLOAD_FOR_BUTTON_2' \
--data-urlencode 'qrPayload_2=PAYLOAD_FOR_BUTTON_3'

URL Encoding

53
The message text should be UrlEncoded. The message should be UrlEncoded (also known as percent
encoding) string of UTF-8 characters.

For more information on URL encoding, please see this: https://en.wikipedia.org/wiki/Percent-encoding

Click here to encode message

Original text:
Hi John!
Mery Christmas to you Regards,
[email protected]

Encoded text:
Hi%20John%21%0AHappy%20Christmas%20to%20you%0ARegards%2C%0Ank%40w.com

Formatting Options
WhatsApp supports some formatting in messages. To format all or part of a message, use these formatting
symbols:

Formatting Symbol Example How message displays on WhatsA

Bold Asterisk (*) Your total is *$10.50*. Your total is $10.50.
Italics Underscore (_) Welcome to _WhatsApp_! Welcome to WhatsApp!
Strike-through Tilde (~) This is ~better~ best! This is better best!
Code Three backticks (```) ```print 'Hello World';``` print 'Hello World';

Emoji are also supported. List of supported emoji are at https://emojipedia.org/whatsapp/ . Copy the emoji
symbol in the message before URL encoding the message and sending through API. Use
data_encoding=Unicode_text when sending a message containing emoji and be mindful of the 1024-
character limit for a Unicode message.

API Response

54
A successful API request generates an HTTP 200 response. The response to a request where output format
was specified as json, is a JSON array with response status and unique identifier.

{
"response": {
"id": "3914460380512464906-350465300787800379",
"phone": "919777777778",
"details": "", "status": "success"
}
}

This indicates that the message has been successfully sent to mobile number 919777777778 under a
Unique Identifier ‘3914460380512464906-350465300787800379’. The identifier string is unique for each
recipient number and is auto generated at the time of message submission. First number is the transaction
ID and second one is message ID. If a custom msg_id is passed in the API request (say,
msg_id=1343891), it would be set as the message ID and returned back in the API response message as the
second half of the unique identifier. For instance, the ‘id’ parameter would be
‘3914460380512464906-1343891’.

API Errors (SendMessage & SendMediaMessage APIs)

An error response is generated when any of the required parameters is not specified correctly or any other
technical error exists. The error response will indicate an error code along with the actual error message.

A typical error response is

{
"response": {
"id": "318",
"phone": "",
"details": " Message does not match WhatsApp HSM template.", "status": "error"
}

Below is the list of Synchronous API failure (errors) in case request is badly formed or parameters are
missing

Error code (id) Error message (details)

100 An unknown exception has occurred. Please retry the request after some time.
101 The parameter X is required. Please resend request.
102 Authentication failed due to invalid userId or password.

55
 103 Authentication Failed as userid X does not exist.
104 This user with number is currently disabled. Please contact support for further details.
105 The phone number is not a valid phone number.
106 The method X is not supported.
112 The phone number field cannot be null.
123 Your account does not have sufficient credits to post this message.
124 Validity of your WhatsApp pack has expired on. You are not allowed to send messages
now.
171 You are not allowed to perform this action.
175 The "INTERNATIONAL_PHONE" service is disabled for you. Kindly get the service
enabled before using this action
315 The phone number XXX is not opted in
318 Message does not match WhatsApp HSM template.
328 Invalid Media Content Type
329 HSM not supported for this msg_type
332 Interactive button template not supported for non HSM requests
333 Interactive button template mismatch
334 Message length exceeded.
249 You are not allowed to perform this action temporarily due to NCPR regulations( The
Enterprise WhatsApp account has not been Verified by the POC)
321 Media upload Error
330 Media Id (X) not found or has expired (MediaID has to be regenerated)
327 Unable to decrypt
361 Request Parameter specification mismatch (example: Length exceeded)
Receive an Inbound Message

Inbound messages sent by customers to your WhatsApp Business Phone Number will be sent to your
webhook endpoint via HTTP/HTTPS.
Gupshup doesnot store incoming messages; it is simply sent to the webhook endpoint which can either be
a customer engagement tool, bot application or any other application as desired, provided the application
can accept the webhook events in the formats mentioned below

Webhooks

Webhooks are user-defined HTTP callbacks that are triggered by specific events such as an inbound
message from a customer i.e. customer sends a text message or media attachment on WhatsApp.
Whenever that trigger event occurs, the Gupshup Messaging API registers the event and immediately sends
a notification (HTTP GET/POST request) to the Callback URL specified in your account settings indicating
when you receive a message.

Please reach out to your account manager to set the Callback URL for your account in order to receive
inbound message webhook events. Only one callback URL can be specified per account.

56
Request Header
Content-Type application/json

Request Body

Key Description Example

waNumber The WhatsApp Business number on which the custome 917834811114
REQUIRED | string has sent a message. Number is in E.164
format
mobile The phone number of the customer who has sent 919777777778
REQUIRED | string the message. Number is in E.164 format
replyId The unique system identifier for the original message 3914460380512464906
OPTIONAL | object sent by the business to the customer, on which the
customer has replied (swipe right action on WhatsApp
reply to a specific message). This is the
transaction ID of the original message.
messageId The unique identifier for the original message sent by t 350465300787800379
OPTIONAL | string business to the customer, on which the customer has
replied (swipe right action on WhatsApp to reply to a
specific message). This is the message ID that can be a
custom value specified in the Send
Message API request of the original message.
timestamp The time in unix timestamp in milliseconds when the 1564472864000
REQUIRED | string message sent by the customer was received by
Gupshup
name The profile name set by the customer in WhatsApp John Smith
REQUIRED | string

type The type of message sent by the customer on WhatsAp text

REQUIRED | string
Must be one of: text, image, document, voice, audio, video,
location, contacts, interactive, order, context

text The text message sent by the user When will my order be
OPTIONAL | string delivered
image The JSON object containing details of the image sent See media Object
OPTIONAL | string by the user documentation below
document The JSON object containing details of the document See media Object
OPTIONAL | object sent by the user documentation below
voice The JSON object containing details of the voice See media Object
OPTIONAL | string message sent by the user documentation below
audio The JSON object containing details of the audio sent See media Object
OPTIONAL | string by the user documentation below

57
 video The JSON object containing details of the video sent See media Object
OPTIONAL | object by the user documentation below
location The JSON object containing details of the geo- See location Object
OPTIONAL | string location sent by the user documentation below
contacts The JSON object containing details of the contact See contacts Object
OPTIONAL | object card sent by the user documentation below
interactive The JSON object containing details of the list See contacts Object
OPTIONAL | object / dynamic reply button selected by the user documentation below

context The JSON object containing details of the See Single and Multi-Product
OPTIONAL | object catalog item, the user has asked information about. messages: Asking for
Information documentation
below

order The JSON object containing details of catalog See Single and Multi-Product
OPTIONAL | object items that are a part of the user’s order. messages: Placing an order
documentation below

Sticker The JSON object containing details of the sticker sent See sticker Object
OPTIONAL | object by the user documentation below

The media object

Key Description Example

mime_type The IANA standard media type of the media file (image image/jpeg
REQUIRED | string document / audio / voice / video) sent by
the customer on WhatsApp
signature The unique signature that is required to download the c4f82d0d148dbc31d4e0b10
REQUIRED | string media file securely from the Gupshup platform. 7e4057053348e7803a0d6ef
b168d0ec656f233a5d

58
 url The public URL where the media attachment sent by th https://gs-datareceiver-
REQUIRED | string customer is hosted. You can download the media by whatsapp.s3.ap-south-
appending the signature value to the URL. 1.amazonaws.com/49da5a9
6-9372-4445-beb5-
Note: The media file will only be available for 48 hours 49be43c787b3?X-Amz-
before it is deleted. Please download as soon as possib Algorithm=AWS4-HMAC-
SHA256&X-Amz-
Date=20190730T070452Z&X
-Amz- SignedHeaders=host&X-
Amz-Expires=172799&X- Amz-
Credential=AKIAJU3SPMQCT
HBIWILA%2F20190730%2Fa
p-south-
1%2Fs3%2Faws4_request&X
-Amz-Signature=

caption The caption text sent for an inbound message of This is a caption message
OPTIONAL | string type = image/ document/ audio

The Sticker object

Key Description Example

mime_type The IANA standard media type of the media file
image/wepb
REQUIRED | string sticker)) sent by the customer on WhatsApp
signature The unique signature that is required to download c4f82d0d148dbc31d4e0b10
REQUIRED | string the media file securely from the Gupshup platform. 7e4057053348e7803a0d6ef
b168d0ec656f233a5d
url The public URL where the media attachment sent
https://gs-datareceiver-whatsa
REQUIRED | string by the customer is hosted.
p.s3.ap-south-1.amazonaws.co
You can download the media by appending the signatu
/4930975292786643603_1303
value to the URL.
af0-d579-4005-9abe-c3817d9c
235?X-Amz-Algorithm=AWS4-H
Note: The media file will only be available for 48
MAC-SHA256&X-Amz-Date=20
hours before it is deleted. Please download as soon as
0621T064129Z&X-Amz-Signed
possible.
aders=host&X-Amz-Expires=17
00&X-Amz-Credential=AKIAV4
FRLFCLI4BR77%2F20230621%2
ap-south-1%2Fs3%2Faws4_req
est&X-Amz-Signature=

The location object

59
 Key Description Example
latitude The latitude of the static location shared by the
19.1454121
string customer. Only present if type=location
longitude The longitude of the static location shared by the
72.8553098
string customer. Only present if type=location

The contacts object

Key Description Example

addresses The JSON object containing a set of full addresses for the [
OPTIONAL | array contact. Each address can contain street, city, state, zip, {
country, country_code, and type fields. "city": "Menlo Park",
"country": "United
States",
"country_code": "us",
"state": "CA",
"street": "1 Hacker
Way", "type": "WORK
"zip": "94025"
}
]
birthday The birthday of the contact in YYYY-MM-DD 1987-09-10
OPTIONAL | string formatted string.
ims The Instant Messaging contact information. Each ims object [
OPTIONAL | array contains service and user_id fields. {
"service": "AIM", "user_i
"kfish"
}
]
org The contact’s organization information. Each org object can {
OPTIONAL | object contain company, department, and title fields. "company": "Gupshup",
"title": "Senior Manager
Marketing"
}
emails The contact’s email address(es). Each emails object can [
OPTIONAL | array contains email and type fields. {
"email": "[email protected]",
"type": "WORK"
}
]

60
 name The full contact name. Each name object can contain {
OPTIONAL | object first_name, middle_name, last_name, formatted_name, "first_name": "Kerry",
name-prefix, and name_suffix fields. "formatted_name": "Kerr
Fisher",
"last_name": "Fisher"
}
phones The contact’s phone number(s). Each phones object can [
OPTIONAL | array contain phone, wa_id, and type fields {
"phone": "+1 (940) 555-
1234",
"type": "CELL"
},
{
"phone": "+1 (650) 555-
1234",
"type": "WORK", "wa_id"
"16505551234"
}
]
urls The contact’s URL(s). Each urls object can contain url [{
OPTIONAL | array and type fields. "url":
"https://www.facebook.c
m ",
"type": "WORK"
}
]

For quick reply buttons without custom payload : The button object

Key Description Example

button The JSON for the button selected specifying the button "{\"text\":\"Pay Now\"}"
name

For quick reply buttons with custom payload: The button object

Key Description Example

61
 button The JSON for the button selected specifying the button "{\"payload\":\"abc\",\"te
name ":\"Kejutan apa tuh?\"}"

For dynamic buttons:

Key Description Example

interactive The JSON for the button selected specifying the button {\"type\":\"button_reply\",\"b
and title ton_reply\":{\"id\":\"unique-p
tback-id-2\",\"title\":\"दस
ू रा
बटन\"

For Lists:

Key Description Example

interactive The JSON for the button selected specifying the row_ID {\"list_reply\":{\"description\"
row_title and row_description selected by the end use 123 North Main
from the List message. %%%%City\",\"id\":\"id1@123
&\",\"title\":\"North City
@@**Store\"},\"type\":\"list_
ply\"}

For Single and Multi-Product messages: The order object

Key Description Example

catalog_id ID for the catalog you want to use for this message. 404818654473184
Retrieve this ID via Commerce Manager.
REQUIRED | string

product_items Array of product objects that end customer want to product_items\":[{\"quantity\

purchase :1,\"product_retailer_id\":\"C
REQUIRED | string Am0101\",\"item_price\":0,\
urrency\":\"INR\"},{\"quantit
\":1,\"product_retailer_id\":\
bkSPr124\",\"item_price\":40
0,\"currency\":\"INR\"},{\"qu
ntity\":2,\"product_retailer_i
\":\"Bucket1234\",\"item_pri

62
 e\":500,\"currency\":\"INR\"}
\"quantity\":3,\"product_reta
er_id\":\"GBSPR12A\",\"item
price\":10000,\"currency\":\"
NR\"}]

product_retailer_i Unique identifier of the product in a catalog. CAm0101

REQUIRED | string This can be retrieved via Commerce Manager.

Quantity No of items 2

REQUIRED | string

item_price Unit price of Item 4000

REQUIRED | string

Currency Price Currency details INR

REQUIRED | string

For Single and Multi-Product messages: Ask for information:

Key Description Example

The actual message sent in by the end-user indicating “Do you have other colors ?”
text the information they are seeking for about the product
REQUIRED | object
(s)

{"referred_product":{"catalog
context Information about the product being mentioned by the id":"404818654473184","pro
REQUIRED | object customer. You can see a product’s unique identifier as uct_retailer_id":"GBSPR12A"}
well as their catalog ID.

Sample Events
The below examples illustrate POST events in JSON format. Other supported callback event formats:
​ GET request with query parameters

​ POST request with Content-type= application/x-www-form-urlencoded

​ Text
Below is a sample payload when a customer sends a text message on WhatsApp to your business number.

63
 Request Headers Content-Type: application/json
Request Body {
"waNumber": "919560222091",
"mobile": "919004371797",
"replyId": "3900363981641897487",
"messageId": "custom Message ID", "text": "Hola Amigo",
"name": "John Smith",
"type": "text",
"timestamp": "1564471290000"
}

Image
Below is a sample payload when a customer sends an image on WhatsApp to your business number. If no
caption is sent, the “caption” key will be missing in the image object, as seen below

Request Headers Content-Type: application/json

Request Body {
"image":
"{\"signature\":\"c4f82d0d148dbc31d4e0b107e4057053348e7803a0d6efb168d0ec
656f233a5d\",\"mime_type\":\"image/jpeg\",\"url\":\"https://gs-datareceiver-
whatsapp.s3.ap-south-1.amazonaws.com/49da5a96-9372-4445-beb5-
49be43c787b3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-
Date=20190730T070452Z&X-Amz-SignedHeaders=host&X-Amz-Expires=172799&X-
Amz-Credential=AKIAJU3SPMQCTHBIWILA%2F20190730%2Fap-south-
1%2Fs3%2Faws4_request&X-Amz-Signature=\"}",
"waNumber": "919560222091",
"mobile": "919004371797",
"replyId": "3900342770242053647",
"messageId": "174087351014158005",
"type": "image",
"name": "John Smith", "timestamp": "1564470288000"}
Document
Below is a sample payload when a customer sends a document along with a caption on WhatsApp to your
business number. If no caption is sent, the “caption” key will be missing in the message object.
Request Headers Content-Type: application/json

64
 Request Body {
"waNumber": "919560222091",
"document":
"{\"signature\":\"9f77d0d187d926f8d6fa4ce8487bd827ae2c4f6f975f157424643159
e356dead\",\"mime_type\":\"application/pdf\",\"caption\":\"2017 Feb
Payslip\",\"url\":\"https://gs-datareceiver-whatsapp.s3.ap-south-
1.amazonaws.com/8fd22186-6cd1-42f2-ad56-ab2f370f5e47?X-Amz-
Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20190730T074011Z&X-Amz-
SignedHeaders=host&X-Amz-Expires=172800&X-Amz-
Credential=AKIAJU3SPMQCTHBIWILA%2F20190730%2Fap-south-
1%2Fs3%2Faws4_request&X-Amz-Signature=\"}", "mobile": "919004371797",
"replyId": "3900363981641897487",
"messageId": "custom Message ID", "type": "document",
"name": "John Smith", "timestamp": "1564472408000"
}

Voice
Below is a sample payload when a customer sends a voice message on WhatsApp to your business number.
WhatsApp does not allow users to send a caption along with voice messages.

Request Headers Content-Type: application/json

Request Body {
"voice":
"{\"signature\":\"c6ce0840e2c1a7f0248a3dd35bbc516c585428b9e58054018477f33
f20b00541\",\"mime_type\":\"audio/ogg; codecs=opus\",\"url\":\"https://gs-
datareceiver-whatsapp.s3.ap-south-1.amazonaws.com/561e4a31-b179-4c3f-ba6a-
da1044ee79c1?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-
Date=20190730T074746Z&X-Amz-SignedHeaders=host&X-Amz-Expires=172800&X-
Amz-Credential=AKIAJU3SPMQCTHBIWILA%2F20190730%2Fap-south-
1%2Fs3%2Faws4_request&X-Amz-Signature=\"}",
"waNumber": "919560222091",
"mobile": "919004371797",
"replyId": "3900363981641897487",
"messageId": "custom Message ID", "type": "voice",
"name": "John Smith", "timestamp": "1564472864000"
}

Audio
Below is a sample payload when a customer sends an audio file on WhatsApp to your business number.
WhatsApp does not allow users to send a caption along with audio file attachments.

65
 Request Headers Content-Type: application/json
Request Body {
"waNumber": "919560222091",
"mobile": "919004371797",
"replyId": "3900363981641897487",
"messageId": "custom Message ID", "audio":
"{\"signature\":\"6ebfaf75460b2b50adaa2f7226698d725f513384f176d233a96328d
1e6d56ddf\",\"mime_type\":\"audio/mpeg\",\"url\":\"https://gs-datareceiver-
whatsapp.s3.ap-south-1.amazonaws.com/f1b476a0-f750-443e-81d1-
cda460307422?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-
Date=20190730T075711Z&X-Amz-SignedHeaders=host&X-Amz-Expires=172800&X-
Amz-Credential=AKIAJU3SPMQCTHBIWILA%2F20190730%2Fap-south-
1%2Fs3%2Faws4_request&X-Amz-Signature=\"}",
"type": "audio",
"name": "John Smith", "timestamp": "1564473428000"
}

Video
Below is a sample payload when a customer sends a video along with a caption on WhatsApp to your
business number. If no caption is sent, the “caption” key will be missing in the messageObj object.

Request Headers Content-Type: application/json

Request Body {
"waNumber": "919560222091",
"mobile": "919004371797",
"replyId": "3900363981641897487",
"messageId": "custom Message Sandy", "video":
"{\"signature\":\"3378b5389001e947d8c2e475de43a3ef0cba37cf848ce755c66228b
bf407661b\",\"mime_type\":\"video/mp4\",\"caption\":\"Morning\",\"url\":\"https
://gs-datareceiver-whatsapp.s3.ap-south-1.amazonaws.com/bc53da72-03a2-4af4-
9c98-d246d901c01a?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-
Date=20190730T080407Z&X-Amz-SignedHeaders=host&X-Amz-Expires=172799&X-
Amz-Credential=AKIAJU3SPMQCTHBIWILA%2F20190730%2Fap-south-
1%2Fs3%2Faws4_request&X-Amz-Signature=\"}",
"type": "video",
"name": "John Smith", "timestamp": "1564473841000"
}

Location
Below is a sample payload when a customer shares their location on WhatsApp to your business number.
Please note that Live Location is not a supported message type on WhatsApp Business at the moment.
66
 Request Headers Content-Type: application/json
Request Body {
"waNumber": "919560222091",
"mobile": "919004371797",
"replyId": "3900363981641897487",
"messageId": "custom Message ID",
"location": "{\"latitude\":19.1453861,\"longitude\":72.8552714}", "type": "location",
"name": "John Smith", "timestamp": "1564473179000"
}

Contact Card
Below is a sample payload when a customer shares a contact on WhatsApp to your business number.

Request Headers Content-Type: application/json

Request Body {
"waNumber": "919560222091",
"mobile": "919004371797",
"replyId": "3900342770242053647",
"messageId": "174087351014158005",
"type": "contacts",
"name": "John Smith",
"contacts": "[{\"addresses\":[{\"country_code\":\"ac\",\"street\":\"415 Jackson Stree
Suite B, San Francisco, CA 94111\",\"type\":\"Work\"}],\"birthday\":\"1978- 10-
11\",\"emails\":[{\"email\":\"[email protected]\"}],\"ims\":[],\"name\":{\"first_na
me\":\"Arun\",\"formatted_name\":\"Arun
Sharma\",\"last_name\":\"Sharma\"},\"org\":{\"company\":\"Gupshup\",\"title\":\"
Senior Manager - Marketing\"},\"phones\":[{\"phone\":\"+1 (855) 982-
8439\",\"type\":\"Mobile\"},{\"phone\":\"+1 (855) 982-
2997\",\"type\":\"Work\"}],\"urls\":[{\"type\":\"OTHER\",\"url\":\"https://www.gu
pshup.io\"}]}]",
"timestamp": "1564470556000"
}

Quick Reply Button Click

Below is a sample payload when customer replies using the Quick reply buttons on WhatsApp to your
business number.

67
Quick reply buttons without custom payload

Request Headers Content-Type: application/json

Request Body {
"button": "{\"text\":\"Shop Now!\"}",
"waNumber": "919898989898",
"mobile": "919797979797",
"replyId": "4688283123785171013",
"name": "Muskan Barnawal",
"messageId": "5814628066882863",
"type": "button",
"timestamp": "1658399398000"
}

Quick reply buttons with custom payload

The custom Paylod refers to the identifier passed in the SendMessage / SendMediaMessage API requests
and the same is made available in the incoming message to be able to identify the Quick Reply button for
which the rely is received.

Request Headers Content-Type: application/json

Request Body {
"button": "{\"payload\":\"abc\",\"text\":\"Kejutan apa tuh?\"}",
"waNumber": "919405318774",
"mobile": "9190909090",
"replyId": "4675968966490706213",
"name": "John Miller",
"messageId": "129157571202837598",
"type": "button",
"timestamp": "1656930583000"
}

Lists:

Request Headers Content-Type: application/json

68
 Request Body {
"waNumber": "919405318774",
"mobile": "9190909090",
"interactive": "{\"list_reply\":{\"description\":\"123 North Main
%%%%City\",\"id\":\"id1@123#!&\",\"title\":\"North City
@@**Store\"},\"type\":\"list_reply\"}",
"replyId": "4402907459323151889",
"name": "Joe Louis",
"messageId": "2476507863298479726",
"type": "interactive",
"timestamp": "1624379159000"
}

Dynamic Reply Buttons:

Request Headers Content-Type: application/json

Request Body {
"waNumber": "919405318774",
"mobile": "919090909090",
"interactive":
"{\"type\":\"button_reply\",\"button_reply\":{\"id\":\"unique-postback-id-2\",\"title\
"दस ू रा बटन\"}}",
"replyId": "1624371663347",
"name": "Joe Louis",
"messageId": "322826132822872112",
"type": "interactive",
"timestamp": "1624371681000"
}

Single and Multi-Product messages- Placing an order:

Request Headers Content-Type: application/json

{ "mobile": "917834811114",
Request Body "name": "John Smith",
"order":
"{\"catalog_id\":\"404818654473184\",\"product_items\":[{\"quantity\":1,\"prod
ct_retailer_id\":\"CAm0101\",\"item_price\":0,\"currency\":\"INR\"},{\"quantity\
1,\"product_retailer_id\":\"bkSPr124\",\"item_price\":4000,\"currency\":\"INR\"}
\"quantity\":2,\"product_retailer_id\":\"Bucket1234\",\"item_price\":500,\"curre
cy\":\"INR\"},{\"quantity\":3,\"product_retailer_id\":\"GBSPR12A\",\"item_price\
10000,\"currency\":\"INR\"}],\"text\":\"All in one package\"}",
"timestamp": "1636615055000",

69
 "type": "order",
"waNumber": "12183094666",
"messageId": "322826132822872112",
"replyId": "1624371663347"

Single and Multi-Product messages: Asking for Information

Request Headers Content-Type: application/json

Request Body {
"mobile": "917518826725",
"timestamp": "1622687285000",
"waNumber": "919220009000",
"replyId": "4388714417570750533",
"messageId": "392881109386641643",
"name": "John Smith",
"type": "text",
"text": "Can I get this in another color?",
"context": {
"referred_product": {
"catalog_id": "404818654473184",
"product_retailer_id": "GBSPR12A"
}
}
}

Referral

70
 Request Headers Content-Type: application/json

Request Body {
""referral"": {
""image"": {
""id"": ""4b43410d-22a7-408f-8829-2b95772fd74b""
},
""source_type"": ""post"",
""source_id"": ""531356374912044"",
""body"": """",
""headline"": ""2, 3 BHK Apartments at Southern Bypass, Kolkata"",
""source_url"": ""https://fb.me/cxcxcxcx""
},
""waNumber"": ""919797979797"",
""replyId"": ""4535467629286368783"",
""mobile"": ""919898989898"",
""name"": ""suvo"",
""text"": ""I saw this on Facebook..."",
""type"": ""text"",
""timestamp"": ""1623498888000""
}

Identity Change event

Request Headers Content-Type: application/json

Request Body {
"system": "{\"new_wa_id\":\"16315558890\",\"body\":\"User A changed from
+1 (631) 555-8889 to +1 (631) 555-8890\",\"type\":\"user_changed_number\"}"
"waNumber": "919004375289",
"mobile": "16315558889",
"type": "system",
"timestamp": "1574080102000"
}

Sticker message event

71
 Request Headers Content-Type: application/json

Request Body {
"waNumber": "919898989898",
"mobile": "919797979797",
"sticker":
"{\"signature\":\"4a1aec7851bc661146dd09a8b9d215b6f9079f3fe50846af5c
64279a6c714bf8\",\"mime_type\":\"image/webp\",\"url\":\"https://gs-datar
eceiver-whatsapp.s3.ap-south-1.amazonaws.com/4930975292786643603_13
03daf0-d579-4005-9abe-c3817d9c1235?X-Amz-Algorithm=AWS4-HMAC-SHA2
56&X-Amz-Date=20230621T064129Z&X-Amz-SignedHeaders=host&X-Amz-Ex
pires=172800&X-Amz-Credential=AKIAV4FTFRLFCLI4BR77%2F20230621%2Fa
p-south-1%2Fs3%2Faws4_request&X-Amz-Signature=\"}",
"name": "John Smith",
"type": "sticker",
"timestamp": "1687329688000"
}

Download Inbound Media Attachments

When users send a media attachment (image / document / audio / video / voice) on WhatsApp, the
webhook event will contain a JSON object containing two parameters “url” and “signature”. To download
the media attachment, form the Media Download URL by appending the value of the “signature” parameter
to the “url” and use WGET command to download the media from Gupshup.

For example: if the JSON object for an image sent by the user on WhatsApp is –

{
"signature": "c4f82d0d148dbc31d4e0b107e4057053348e7803a0d6efb168d0ec656f233a5d",
"mime_type": "image/jpeg",
"url": "https://gs-datareceiver-whatsapp.s3.ap-south-1.amazonaws.com/49da5a96-9372-4445-beb5-
49be43c787b3?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20190730T070452Z&X-Amz-
SignedHeaders=host&X-Amz-Expires=172799&X-Amz-Credential=AKIAJU3SPMQCTHBIWILA%2F20190730%2Fap-
south-1%2Fs3%2Faws4_request&X-Amz-Signature="
}

Then, the Media Download URL is

https://gs-datareceiver-whatsapp.s3.ap-south-1.amazonaws.com/49da5a96-9372-4445-beb5-49be43c787b3?X-

72
Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20190730T070452Z&X-Amz-SignedHeaders=host&X-Amz-
Expires=172799&X-Amz-Credential=AKIAJU3SPMQCTHBIWILA%2F20190730%2Fap-south-
1%2Fs3%2Faws4_request&X-Amz-
Signature=c4f82d0d148dbc31d4e0b107e4057053348e7803a0d6efb168d0ec656f233a5d

Note: The media file will only be available for 48 hours before it is deleted. Please download as soon as
possible.

Send a Customer Support Reply

Use the Gupshup Messaging API to send a reply message to a customer on WhatsApp within the Customer
Care Window (within 24 hours since the customer’s last message. During the Customer Care Window, free
form messages can be sent and the below message types are supported. However, please note WhatsApp
policies must be adhered to and even free-form customer support reply messages must be relevant to the
customer’s query and may contain product recommendations, offers, etc.

Note: Even if the customer has not opted in to receive notifications, the business can reply back to the
customer within 24 hours.

Supported Message Types

Type Supported Content-types

Text English (max. 4000 characters) and Unicode characters (max. 1024 characters)
Image image/jpeg, image/png
Document application/pdf, application/msword, application/vnd.ms-powerpoint,
application/vnd.ms-excel, text/plain
Audio audio/acc, audio/mp4, audio/amr, audio/mpeg, audio/ogg, codecs=opus
Video video/mp4, video/3gpp
Note: Only H.264 video codec and AAC audio codec is supported.
Sticker webp

Send a Text Message

The method for sending a text message in response to a customer’s inbound message is “SendMessage”.

API Endpoint
To send a text message on WhatsApp in response to a customer’s inbound message, the API request is
made to this endpoint:

https://media.smsgupshup.com/GatewayAPI/rest

Request Headers
Content-Type application/x-www-form-urlencoded

73
Request Body
Key Description Example
userid The userid of your Gupshup account. The number must be in 2000155005
REQUIRED | string pure numeric format with no special characters.

Note: Gupshup will provide separate userid and password

to send Customer Support reply messages, it will not be the
same as the userid to send
Notifications.

password The password of your Gupshup account for sh1gw4e

REQUIRED | string authentication of the userid
method The API method to perform a specific action i.e. send SendMessage
REQUIRED | string a message on WhatsApp
Must be: SendMessage
auth_scheme The authentication scheme of the API. plain
REQUIRED | string
Must be: plain
v The API version. 1.1
REQUIRED | string
Must be: 1.1
send_to The phone number of the recipient to whom message is being 919892123456
REQUIRED | string sent. Number must be in E.164
format.
msg The text message to be sent to the customer. It must Hello%20World!
REQUIRED | string be URL encoded.
isHSM This indicates whether the message is a Message Template false
REQUIRED | boolean (HSM) i.e. a pre-approved message template. Since this is a
Customer support reply, always set this as ‘false’.
Must be: false
msg_type The type of message to be sent to the customer. Depending on DATA_TEXT
OPTIONAL | string ‘type’, the relevant parameters must be sent as part of the reque
payload. By default, type is TEXT unless otherwise specified.

Must be one of: DATA_TEXT, TEXT, LOCATION, CONTACTS

data_encoding The encoding type of the message i.e. plain English text or Unico text
OPTIONAL | string i.e. message is in another language or contains special character
emoji .

Must be one of: text, Unicode_text

format The API response message format. Default value is text, unless json

74
 OPTIONAL | string otherwise specified.

Must be one of: text, json, xml

preview_url This indicates whether a preview should be displayed for a link true
OPTIONAL | boolean present in the ‘msg’ parameter. By default, it will be ‘false’
which means links will be clickable but no preview will be seen.
Preview of a URL means that the title of the webpage
along with thumbnail is displayed.

Must be one of: true, false

msg_id A Custom message ID that can be specified by the business. 13438913215357
OPTIONAL | string This will be attached to Message Status Callbacks and can help 81
you track messages using your internal IDs. 200 characters
alphanumeric values are allowed for msg_id and it must be
unique for every message sent.
extra A Custom parameter that can be used as an identifier for SUPER100SEGME
OPTIONAL | string reporting purposes. You can input any text in this parameter T
and the same value will be forwarded in the Status Callback.
50 alphanumeric characters are allowed for this parameter.
linkTrackingEnabled This parameter can be used to specify linktracking for links True
OPTIONAL | string present in the ‘msg’ request parameter
Must be : True/false

Sample Requests

Below is a sample payload when sending a text message on WhatsApp.

curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest' \

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'send_to=919999999999' \
--data-urlencode 'msg_type=DATA_TEXT' \
--data-urlencode 'userid=2000XXXXXX' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'password=XXXXXXX' \
--data-urlencode 'method=SendMessage' \
--data-urlencode 'v=1.1' \
--data-urlencode 'format=json' \
--data-urlencode 'msg=This is test message'

Encrypted request
Below is a sample GET request with encrypted data in the payload, to send a message on WhatsApp:

75
https://media.smsgupshup.com/GatewayAPI/rest?userid=2000XXXXXX&encrdata={{Base64
_Encoded_Encrypted_ Data}}

where, value of encrdata =

{{method=SendMessage&format=json&password=XXXXXXXX&send_to=919777777778&v=1.1&auth_sche
me=plain&msg_type=DATA_TEXT&msg=Welcome%20to%20Gupshup%20API}}

Please note:

​ The “userid” parameter is mandatory and its value is to be sent in an unencrypted format. All the other
parameters must be sent in encrypted format using AES 256 encryption and base64 encoded with the
Key shared, in the “encrdata” parameter.
​ You must use the key generated for your enterprise account to encrypt API parameter values when
sending the API request. Once the request is received by Gupshup, the payload is decrypted by
Gupshup and sent ahead to WhatsApp.
​ Please read Appendix A for detailed steps and code samples on how to encrypt the payload before
sending an API request.

Send a Media Message

The method for sending a media attachment message in response to a customer’s inbound message is
“SendMediaMessage”.

Media Type Max. Media Upload Size

Image 5 MB
Document 100 MB
Audio 16 MB
Video 16 MB

API Endpoint
To send a media message on WhatsApp in response to a customer’s inbound message, the API request is
made to this endpoint:

https://media.smsgupshup.com/GatewayAPI/rest

Request Headers
Content-Type application/x-www-form-urlencoded

Request Body
Key Description Example

76
userid The userid of your Gupshup account. The number must be i 2000155005
REQUIRED | string pure numeric format with no special characters.

Note: Gupshup will provide separate userid and password t

send Customer Support reply messages, it will not be the
same as the userid to send
Notifications.

password The password of your Gupshup account for sh1gw4e

REQUIRED | string authentication of the userid
method The API method to perform a specific action i.e. send a SendMediaMessage
REQUIRED | string message on WhatsApp

Must be: SendMediaMessage

auth_scheme The authentication scheme of the API. plain
REQUIRED | string
Must be: plain
v The API version. 1.1
REQUIRED | string
Must be: 1.1
send_to The phone number of the recipient to whom message is be 919892123456
REQUIRED | string sent. Number must be in E.164
format.
msg_type The type of message to be sent to the customer. IMAGE
REQUIRED | string
Must be one of: IMAGE, DOCUMENT, AUDIO
media_url The Public URL where the media attachment file is hosted. https://image.shutterst
REQUIRED | string k.c om/image-
illustration/movie-ticke
icon-260nw-663331288
g
isHSM This indicates whether the message is a Message Template false
REQUIRED | boolean (HSM) i.e. a pre-approved message template. Since this is a
Customer support reply, always set this as ‘false’.
Must be: false
caption The caption text to be sent along with the media Your ticket is confirmed
REQUIRED | string attachment. for
20-DEC-2019.
msg The text message to be sent to the customer via SMS Your ticket is confirmed
OPTIONAL | string if fallback to SMS is configured. for
20-DEC-2019.
data_encoding The encoding type of the message i.e. plain English text or text
OPTIONAL | string Unicode i.e. message is in another language or contains
special characters / emoji .

Must be one of: text, Unicode_text

77
 format The API response message format. Default value is text, json
OPTIONAL | string unless otherwise specified.

Must be one of: text, json, xml

preview_url This indicates whether a preview should be displayed for a true
OPTIONAL | boolean link present in the ‘msg’ parameter. By default, it will be ‘fal
which means links will be clickable but no preview
will be seen. Preview of a URL means that the title of the
webpage along with thumbnail of favicon is displayed.

Must be one of: true, false

msg_id A Custom message ID that can be specified by the business. 134389132153571381
OPTIONAL | string This will be attached to Message Status Callbacks and can
help you track messages using your internal IDs. 200
characters alphanumeric
values are allowed for msg_id and it must be unique for
every message sent.
linkTrackingEnabled This parameter can be used to specify linktracking for links True
OPTIONAL | string present in the ‘msg’ request parameter
Must be : True/false

Sample Requests

Image
Below is a sample POST request when sending an image on WhatsApp, within the 24 hour Customer Care
Window.
curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'send_to=9999999999' \
--data-urlencode 'msg_type=IMAGE' \
--data-urlencode 'userid=2000xxxxxx' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'password=xxxxxxx' \
--data-urlencode 'method=SendMediaMessage' \
--data-urlencode 'v=1.1' \
--data-urlencode 'format=text' \
--data-urlencode
'media_url=https://homepages.cae.wisc.edu/~ece533/images/airplane.png' \
--data-urlencode 'caption=This is a test image.' \
--data-urlencode 'isHSM=false'

Document
Below is a sample GET request when sending a document / file on WhatsApp, within the 24 hour Customer
Care Window.
curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest' \
--header 'Content-Type: application/x-www-form-urlencoded' \

78
--data-urlencode 'send_to=9999999999' \
--data-urlencode 'msg_type=DOCUMENT \
--data-urlencode 'userid=2000xxxxxx' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'password=xxxxxxx' \
--data-urlencode 'method=SendMediaMessage' \
--data-urlencode 'v=1.1' \
--data-urlencode 'format=text' \
--data-urlencode
'media_url=https://homepages.cae.wisc.edu/~ece533/documents/Policy.pdf' \
--data-urlencode 'caption=This is a test document.' \
--data-urlencode 'isHSM=false'

Audio
Below is a sample GET request when sending an audio file on WhatsApp, within the 24 hour Customer Care
Window.

curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest' \

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'send_to=9999999999' \
--data-urlencode 'msg_type=AUDIO \
--data-urlencode 'userid=2000xxxxxx' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'password=xxxxxxx' \
--data-urlencode 'method=SendMediaMessage' \
--data-urlencode 'v=1.1' \
--data-urlencode 'format=text' \
--data-urlencode
'media_url=https://homepages.cae.wisc.edu/~ece533/audio/file.mp3' \
--data-urlencode 'caption=This is a test audio.' \
--data-urlencode 'isHSM=false'

Video
Below is a sample GET request when sending an video on WhatsApp, within the 24 hour Customer Care
Window.

curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest' \

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'send_to=9999999999' \
--data-urlencode 'msg_type=VIDEO \
--data-urlencode 'userid=2000xxxxxx' \
--data-urlencode 'auth_scheme=plain' \

79
--data-urlencode 'password=xxxxxxx' \
--data-urlencode 'method=SendMediaMessage' \
--data-urlencode 'v=1.1' \
--data-urlencode 'format=text' \
--data-urlencode
'media_url=https://homepages.cae.wisc.edu/~ece533/videos/tutorial1.mp4' \
--data-urlencode 'caption=This is a test video.' \
--data-urlencode 'isHSM=false'

Encrypted Media

Below is a sample GET request with encrypted data in the payload, to send a document on WhatsApp:

https://media.smsgupshup.com/GatewayAPI/rest?userid=2000XXXXXX&encrdata={{Base64
_Encoded_Encrypted_ Data}}

where value of encrdata =

{{method=SendMediaMessage&format=json&password=XXXXXXXX&send_to=919777777778&v=1.1&au
th_scheme=plain&msg_type=DOCUMENT&isHSM=false&media_url=http://www.africau.edu/images/defaul
t/sam ple.pdf&caption=Account%20Statement}}

Please note:

​ The “userid” parameter is mandatory and its value is to be sent in an unencrypted format. All the other
parameters must be sent in encrypted format using AES 256 encryption and base64 encoded with the
Key shared, in the “encrdata” parameter.
​ You must use the key generated for your enterprise account to encrypt API parameter values when
sending the API request. Once the request is received by Gupshup, the payload is decrypted by
Gupshup and sent ahead to WhatsApp.
​ Please read Appendix A for detailed steps and code samples on how to encrypt the payload before
sending an API request.

Send a Location Message

The method for sending a location message in response to a customer’s inbound message is
“SendMessage”.

API Endpoint
To send a location message on WhatsApp in response to a customer’s inbound message, the API request is
made to this endpoint:

https://media.smsgupshup.com/GatewayAPI/rest

80
Request Headers
Content-Type application/x-www-form-urlencoded

Request Body
Key Description Example
userid The userid of your Gupshup account. The number 2000155005
REQUIRED | string must be in pure numeric format with no special
characters.

Note: Gupshup will provide separate userid and

password to send Customer Support reply messages,
it will not be the same as the userid to send
Notifications.
password The password of your Gupshup account for sh1gw4e
REQUIRED | string authentication of the userid

method The API method to perform a specific action i.e. send SendMessage
REQUIRED | string a message on WhatsApp

Must be: SendMessage

auth_scheme The authentication scheme of the API. Plain
REQUIRED | string
Must be: plain

v The API version. 1.1

REQUIRED | string
Must be: 1.1

send_to The phone number of the recipient to whom message 919892123456

REQUIRED | string being sent. Number must be in E.164
format.

isHSM This indicates whether the message is a Message false

REQUIRED | boolean Template (HSM) i.e. a pre-approved message template
Since this is a Customer support reply, always set this
as ‘false’.
Must be: false
msg_type The type of message to be sent to the customer. LOCATION
REQUIRED | string Depending on ‘type’, the relevant parameters must be
sent as part of the request payload. By default, type is
TEXT unless otherwise specified.
Must be one of: DATA_TEXT, TEXT, LOCATION,
CONTACTS

81
 location The Location payload in JSON format containing the { "longitude": -122.425332,
REQUIRED | string latitude, longitude, name and address (latitude and "latitude": 37.758056, "name
longitude are mandatory). "Facebook", "address": "1
Hacker Way,
This parameter is mandatory if msg_type=LOCATION
Menlo Park, CA 94025" }
msg The text message to be sent to the customer on Facebook Address: 1 Hacker
OPTIONAL | string SMS in case fallback to SMS is enabled on the Way, Menlo Park, CA 94025.
account. It must be URL encoded. Directions:
http://bit.ly/2O8WUKz
data_encoding The encoding type of the message i.e. plain English Text
OPTIONAL | string text or Unicode i.e. message is in another language
or contains special characters / emoji .

Must be one of: text, Unicode_text

format The API response message format. Default value is Json
OPTIONAL | string text, unless otherwise specified.

Must be one of: text, json, xml

msg_id A Custom message ID that can be specified by the 134389132153571381
OPTIONAL | string business. This will be attached to Message Status
Callbacks and can help you track messages using
your internal IDs. 200 characters alphanumeric
values are allowed for msg_id and it must be unique
for every message sent.

extra A Custom parameter that can be used as an identifier SUPER100SEGMENT

OPTIONAL | string for reporting purposes. You can input any text in this
parameter and the same value will be forwarded in
the Status Callback. 50 alphanumeric
Characters are allowed for this parameter.

Sample Requests
Simple request
Below is a sample curl for a GET request to send a location message on WhatsApp, within the 24 hour
Customer Care Window.

curl --location -g --request POST 'https://media.smsgupshup.com/GatewayAPI/rest?

send_to=91xxxxxxxxxx&password=xxxx&method=SendMessage&v=1.1&format=json&msg_type
=LOCATION&auth_scheme=plain&userid=2000xxxxxx&location= { "longitude":
-122.425332, "latitude": 37.758056, "name": "testss", "address": "1 Hacker Way,
Menlo Park, CA 94025" }&isHSM=false'

Encrypted request
Below is a sample GET request with encrypted data in the payload, to send a location message on

82
WhatsApp:

https://media.smsgupshup.com/GatewayAPI/rest?userid=2000XXXXXX&encrdata={{Base64
_Encoded_Encrypted_ Data}}

where, value of encrdata =

{{method=SendMessage&format=json&password=XXXXXXXX&send_to=919777777778&v=1.1&auth_sch
eme=plain&msg_type=LOCATION&location={"longitude": -122.425332, "latitude": 37.758056, "name":
"Facebook", "address": "1 Hacker Way, Menlo Park, CA94025"}}}

Please note:

● The “userid” parameter is mandatory and its value is to be sent in an unencrypted format. All the
other parameters must be sent in encrypted format using AES 256 encryption and base64 encoded
with the Key shared, in the “encrdata” parameter.
● You must use the key generated for your enterprise account to encrypt API parameter values when
sending the API request. Once the request is received by Gupshup, the payload is decrypted by
Gupshup and sent ahead to WhatsApp.
● Please read Appendix A for detailed steps and code samples on how to encrypt the payload before
sending an API request

Send a Contact Card

The method for sending a contact card in response to a customer’s inbound message is “SendMessage”.

API Endpoint
To send a contact card message on WhatsApp in response to a customer’s inbound message, the API
request is made to this endpoint:

https://media.smsgupshup.com/GatewayAPI/rest

Request Headers
Content-Type application/x-www-form-urlencoded

Request Body

Key Description Example

83
userid The userid of your Gupshup account. The number 2000155005
REQUIRED | string must be in pure numeric format with no special
characters.

Note: Gupshup will provide separate userid and

password to send Customer Support reply messages,
it will not be the same as the userid to send
Notifications.
password The password of your Gupshup account for sh1gw4e
REQUIRED | string authentication of the userid
method The API method to perform a specific action i.e. SendMessage
REQUIRED | string send a message on WhatsApp

Must be: SendMessage

auth_scheme The authentication scheme of the API. Plain
REQUIRED | string
Must be: plain
v The API version. 1.1
REQUIRED | string
Must be: 1.1
send_to The phone number of the recipient to whom message 919892123456
REQUIRED | string is being sent. Number must be in E.164
format.
msg_type The type of message to be sent to the customer. CONTACTS
REQUIRED | string Depending on ‘type’, the relevant parameters must be
sent as part of the request payload. By default,
type is TEXT unless otherwise specified.
Must be one of: DATA_TEXT, TEXT, LOCATION, CONTACTS

contacts The Contacts payload in JSON format containing the [

REQUIRED | string contact details. {
"name": { "first_name": "John
This parameter is mandatory if msg_type=CONTACTS "formatted_name":
"John Smith", "last_name":
"Smith"
},
"org": { "company":
"WhatsApp", "department":
"Design",
"title": "Manager"
},
"phones": [
{
"phone": "+1 (650)

84
 555-1234",
"type": "WORK",
"wa_id": "16505551234"
}
]
}
]
msg The text message to be sent to the customer on SMS in [Name] John Smith [Phone] +
OPTIONAL | string case fallback to SMS is enabled on the account. It 650-555-1234
must be URL encoded. [Org] WhatsApp

data_encoding The encoding type of the message i.e. plain English Text
OPTIONAL | string text or Unicode i.e. message is in another language or
contains special characters / emoji .

Must be one of: text, Unicode_text

format The API response message format. Default value is Json

OPTIONAL | string text, unless otherwise specified.

Must be one of: text, json, xml

msg_id A Custom message ID that can be specified by the 134389132153571381

OPTIONAL | string business. This will be attached to Message Status
Callbacks and can help you track messages using your
internal IDs. 200 characters alphanumeric values are
allowed for msg_id and it must be unique
for every message sent.
extra A Custom parameter that can be used as an identifier SUPER100SEGMENT
OPTIONAL | string for reporting purposes. You can input any text in this
parameter and the same value will be forwarded in the
Status Callback. 50 alphanumeric
characters are allowed for this parameter

Sample Requests
Below is a sample POST request when sending a contact card on WhatsApp, within the 24 hour Customer
Care Window.

85
curl --location -g --request POST
'https://media.smsgupshup.com/GatewayAPI/rest?send_to=91xxxxxxxxxx&password=xxxxx&method=
SendMessage&v=1.1&format=json&msg_type=contacts&auth_scheme=plain&userid=2000xxxxxx&conta
cts=[
{
"addresses": [
{
"city": "Menlo Park",
"country": "United States",
"country_code": "us",
"state": "CA",
"street": "1 Hacker Way",
"type": "HOME",
"zip": "94025"
},
{
"city": "Menlo Park",
"country": "United States",
"country_code": "us",
"state": "CA",
"street": "200 Jefferson Dr",
"type": "WORK",
"zip": "94025"
}
],
"birthday": "2012-08-18",
"emails": [
{
"email": "[email protected]",
"type": "WORK"
},
{
"email": "[email protected]",
"type": "WORK"
}
],
"name": {
"first_name": "John",
"formatted_name": " Adolph Blaine Charles David Earl Frederick
Gerald Hubert Irvin John Kenneth Lloyd Martin Nero Oliver Paul Quincy Randolph Sherman
Thomas Uncas Victor William Xerxes Yancy Wolfeschlegelsteinhausenbergerdorff, Senior",
"last_name": "Smith"
},
"org": {
"company": "WhatsApp",
"department": "Design",
"title": "Manager"

86
 },
"phones": [
{
"phone": "+1 (940) 555-1234",
"type": "HOME"
},
{
"phone": "+1 (650) 555-1234",
"type": "WORK",
"wa_id": "16505551234"
},{
"phone": "8767879963",
"type": "WORK",
}
],
"urls": [
{
"url": "https://www.facebook.com",
"type": "WORK"
}
]
}
]&isHSM=false'

Encrypted request

Below is a sample request to send an encrypted request for a message of type ‘contact’ within the 24 hour
Customer Care Window.

https://media.smsgupshup.com/GatewayAPI/rest?userid=2000XXXXXX&encrdata={{Base64_Encoded_
Encrypted_ Data}}

Where, encrdata =
{{method=SendMessage&format=json&password=XXXXXXXX&send_to=919777777778&v=1.1&auth_scheme=plain&
msg_type=CONTACTS&contacts=[{
"addresses": [
{
"city": "Menlo Park",
"country": "United States",
"country_code": "us",
"state": "CA",
"street": "1 Hacker Way",
"type": "HOME",
"zip": "94025"
},
{
"city": "Menlo Park",

87
"country": "United States",
"country_code": "us",
"state": "CA",
"street": "200 Jefferson Dr",
"type": "WORK",
"zip": "94025"
}
],
"birthday": "2012-08-18",
"emails": [
{
"email": "[email protected]",
"type": "WORK"
},
{
"email": "[email protected]",
"type": "WORK"
}
],
"name": {
"first_name": "John",
"formatted_name": " Adolph Blaine",
"last_name": "Smith"
},
"org": {
"company": "WhatsApp",
"department": "Design",
"title": "Manager"
},
"phones": [
{
"phone": " 1 (940) 555-1234","type": "HOME"
},
{
"phone": " 1 (650) 555-1234",
"type": "WORK",
"wa_id": "16505551234"
},{
"phone": "8767879963",
"type": "WORK",
}
],
"urls": [
{
"url": "https://www.facebook.com",
"type": "WORK"
}
]
}
]&isHSM=false

88
Please note:
● The “userid” parameter is mandatory and its value is to be sent in an unencrypted format. All the
other parameters must be sent in encrypted format using AES 256 encryption and base64 encoded
with the Key shared, in the “encrdata” parameter.

● You must use the key generated for your enterprise account to encrypt API parameter values when
sending the API request. Once the request is received by Gupshup, the payload is decrypted by
Gupshup and sent ahead to WhatsApp.

● Please read Appendix A for detailed steps and code samples on how to encrypt the payload before
sending an API request.

Send a List Message

Since Lists are supported by Text messages the method will be “SendMessage”

API Endpoint
To send a contact card message on WhatsApp in response to a customer’s inbound message, the API
request is made to this endpoint:

https://media.smsgupshup.com/GatewayAPI/rest

Request Headers
Content-Type application/x-www-form-urlencoded

Request Body
Key Description Example
userid The userid of your Gupshup account. The number must 2000155005
REQUIRED | string be in pure numeric format with no special characters.

Note: Gupshup will provide separate userid and passwo

to send Customer Support reply messages, it will not
be the same as the userid to send
Notifications.

password The password of your Gupshup account for sh1gw4e

REQUIRED | string authentication of the userid
method The API method to perform a specific action i.e. SendMessage
REQUIRED | string send a message on WhatsApp

Must be: SendMessage

auth_scheme The authentication scheme of the API. Plain
REQUIRED | string
Must be: plain

89
v The API version. 1.1
REQUIRED | string
Must be: 1.1
send_to The phone number of the recipient to whom the 919892123456
REQUIRED | string message is being sent. Number must be in E.164
Format.
msg The Message that will be sent in the body of the Hello John,
REQUIRED | string message As per your request please f
Must be within 1024 characters including variable the list of ATMs in and aroun
values the Pincode shared by you.
Tap on “List” to view further
and make a selection.
action This is the encoded JSON that specifies the list sections, %7B%0A%09%22button%22
REQUIRED | string rows and description 3A%20%22Vaccine%20Cente
%22%2C%0A%0A%09%22se
ons%22%3A%20%5B%7B%0
%09%09%22rows%22%3A%
%5B%7B%0A%09%09%09%0
%22id%22%3A%20%22id1%
%2C%0A%09%09%09%09%2
itle%22%3A%20%22North%
City%20%20Store%22%2C%0
%09%09%09%09%22descrip
n%22%3A%20%22123%20N
h%20Main%20City%22%0A%
9%09%09%7D%2C%0A%0A%
9%09%09%7B%0A%09%09%
9%09%22id%22%3A%20%22
2%22%2C%0A%09%09%09%
9%22title%22%3A%20%22G
ater%20Area%20Pharmacy%
2%2C%0A%09%09%09%09%
2description%22%3A%20%2
778%20Panaroma%20Docto
2C%20Township%20NA%22%
A%09%09%09%7D%2C%0A%
9%09%09%7B%0A%09%09%
9%09%22id%22%3A%20%22
3%22%2C%0A%09%09%09%
9%22title%22%3A%20%22C
tral%20Pharmacy%22%2C%0
%09%09%09%09%22descrip
n%22%3A%20%2223%20Cen

90
 al%20Line%20Road%20City%
0NA%22%0A%09%09%09%7
%2C%0A%0A%09%09%09%7
%0A%09%09%09%09%22id%
2%3A%20%22id4%22%2C%0
%09%09%09%09%22title%2
%3A%20%22Lakeside%20Dr
store%22%2C%0A%09%09%
%09%22description%22%3A
20%2289%20Riverroad%20c
%20NA%22%0A%09%09%09
7D%2C%0A%09%09%09%7B
0A%09%09%09%09%22id%2
%3A%20%22id5%22%2C%0A
09%09%09%09%22title%22%
A%20%22Southwest%20City
20center%22%2C%0A%09%0
%09%09%22description%22
A%20%22870%20Southwest
20Main%20St%2C%20City%
NA%22%0A%09%09%09%7D
0A%0A%09%09%5D%0A%09
7D%5D%0A%7D
interactive_type The type of Interactive message to be sent to the list
REQUIRED | string customer.
This is a mandatory parameter
Has to be list for List Messages

msg_type The type of message to be sent to the customer. text

OPTIONAL | string Depending on ‘type’, the relevant parameters must be
sent as part of the request payload. By default,
type is TEXT unless otherwise specified.
Must be one of: DATA_TEXT, TEXT, LOCATION, CONTACT
data_encoding The encoding type of the message i.e. plain English Text
OPTIONAL | string text or Unicode i.e. message is in another language or
contains special characters / emoji .

Must be one of: text, Unicode_text

format The API response message format. Default value is Json
OPTIONAL | string text, unless otherwise specified.

Must be one of: text, json, xml

91
 msg_id A Custom message ID that can be specified by the 134389132153571381
OPTIONAL | string business. This will be attached to Message Status
Callbacks and can help you track messages using your
internal IDs. 200 characters alphanumeric values are
allowed for msg_id and it must be unique
for every message sent.
header In a Text message, a header usually refers to the ‘Title’ o Text message :
OPTIONAL | string the message. “Booking confirmation for
60 alphanumeric characters (with variable values) are Movie”
allowed for this parameter.
footer A short line of text to the bottom of the message “Get yourself web-checked-i
OPTIONAL | string template. to avoid queues”
60 alphanumeric characters are allowed for this
parameter.
A Custom parameter that can be used as an 45123id
extra identifier for reporting purposes. You can input any
OPTIONAL | string text in this parameter and the same value will be
forwarded in the Status Callback. 50 alphanumeric
Characters are allowed for this parameter.
linkTrackingEnabled This parameter can be used to specify linktracking for True
OPTIONAL | string links present in the ‘msg’ request parameter
Must be : True/false

JSON structure:

{
"button": "Menu_name",
"sections": [{
"title": "Section_1_name",
"rows": [{
"id": "Row_1_id",
"title": "Row_1_title",
"description": "Row_1_Description"
}
]
},
{
"title": "Section_2_name",
"rows": [{
"id": "Row_3_id",
"title": "Row_3_title",
"description": "Row_3_Description"
}
92
 ]
}
]
}
Example JSON for action for List messages (Decoded)

{
"button": "Vaccine Center",
"sections": [{
"rows": [{
"id": "id1",
"title": "North City Store",
"description": "123 North Main City"
},

{
"id": "id2",
"title": "Greater Area Pharmacy",
"description": "4778 Panaroma Doctor, Township NA"
},
{
"id": "id3",
"title": "Central Pharmacy",
"description": "23 Central Line Road City NA"
},

{
"id": "id4",
"title": "Lakeside Drugstore",
"description": "89 Riverroad city NA"
},
{
"id": "id5",
"title": "Southwest City center",
"description": "870 Southwest Main St, City NA"
}
]
}
]
}

93
 Action components explained:

Key Description Specification

button This specifies the Title / Name of the L ● Maximum characters allowed:
REQUIRED | String ● Alphanumeric, Unicode, Emoji
Spaces permitted.
● Special Characters are rendere
as specified.
sections_title This specifies the section titles ● Maximum characters allowed:
Optional | String ● Alphanumeric , Unicode &
Spaces permitted
● Special Characters are rendere
as specified.
● Maximum such sections
permitted is 10
This indicates the individual row name
rows_title which can be selected via the associate ● Maximum characters allowed:
REQUIRED | String Radio button ● Alphanumeric, Emojis, Spaces
permitted
● Special Characters are rendere
as specified.
● Maximum such rows permitted
is 10
rows_id This is an identifier to indicate the ● Maximum characters allowed:
REQUIRED | String specific rows_title. ● Alphanumeric, Spaces permitt
● Special Characters are rendere
In a single request with more than one as specified.
rows_title, the rows_id value has to be ● Emojis are not allowed
unique.

The same rows_id can be used in othe

requests.

rows_description A brief one-liner that provides addition ● Maximum characters allowed:

Optional | String context for the selection choice. ● Alphanumeric, Emojis, Spaces
permitted.
● Special Characters are rendere
as specified.

Sample Requests
Below is a sample POST request when sending a List message on WhatsApp, within the 24 hour Customer
Care Window.

94
 curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest'
\
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'method=SENDMESSAGE' \
--data-urlencode 'msg=Welcome to ABC Bank please select one to avail our
service.' \
--data-urlencode 'msg_type=text' \
--data-urlencode 'userid=2000XXXXX' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'password=XXXXXX' \
--data-urlencode 'format=text' \
--data-urlencode 'interactive_type=list' \
--data-urlencode 'send_to=9999999999' \
--data-urlencode 'action={
"button": "Menu",
"sections": [
{
"title": "Balance",
"rows": [
{
"id": "id1",
"title": "My Balance",
"description": "Select to check Account Balance"
}
]
},
{
"title": "Open Account",
"rows": [
{
"id": "id2",
"title": "Saving",
"description": "Click here to open saving account"
}
]
},
{
"title": "Service",
"rows": [
{
"id": "id4",
"title": "Customer care",
"description": "select to connect with Customer care"
},
{
"id": "id5",
"title": "Call Back",
"description": "We will call you back in 10 min"
}
]
},
{
"title": "KYC",
"rows": [
{
"id": "id7",

95
 "title": "Phone",
"description": "To change Phone number"
},
{
"id": "id8",
"title": "Email",
"description": "Change email address"
}
]
}
]
}' \
--data-urlencode 'v=1.1' \
--data-urlencode 'format=TEXT' \
--data-urlencode 'footer=for more details please visit www.abcbank.com' \
--data-urlencode 'header=ABC Bank'

Encrypted request

Below is a sample GET request with encrypted data in the payload, to send a List message on WhatsApp in a
24 hour window.

https://media.smsgupshup.com/GatewayAPI/rest?userid=2000XXXXXX&encrdata={{Base64
_Encoded_Encrypted_ Data}}
where, encrdata =
method=SendMessage&msg=Welcome%20to%20ABC%20Bank%20please%20select%20one%20to%20avail%20our%2
0service.&msg_type=text&auth_scheme=plain&password=XXXXXXX&interactive_type=list&send_to=91XXXXXXXXXX&
v=1.1&format=JSON&footer=ABC%20Bank&header=ABC%20Bank&action=%7B%0A%09%22button%22%3A%20%22Va
ccine%20%25%25%F0%9F%98%83HhhCent%22%2C%0A%0A%09%22sections%22%3A%20%5B%7B%0A%09%09%22ro
ws%22%3A%20%5B%7B%0A%09%09%09%09%22id%22%3A%20%22id1%40123%23!%26%22%2C%0A%09%09%09%0
9%22title%22%3A%20%22North%20City%20%20%40%40**Store%22%2C%0A%09%09%09%09%22description%22%3
A%20%22123%F0%9F%98%83North%20Main%20%20%20%25%25%25%25City%22%0A%09%09%09%7D%2C%0A%0A
%09%09%09%7B%0A%09%09%09%09%22id%22%3A%20%22id2%22%2C%0A%09%09%09%09%22title%22%3A%20%
22Greater%20Area%20Pharmacy%22%2C%0A%09%09%09%09%22description%22%3A%20%224778%20Panaroma%2
0Doctor%2C%20Township%20NA%22%0A%09%09%09%7D%2C%0A%09%09%09%7B%0A%09%09%09%09%22id%22%
3A%20%22id3%22%2C%0A%09%09%09%09%22title%22%3A%20%22Central%20Pharmacy%22%2C%0A%09%09%09%
09%22description%22%3A%20%2223%20Central%20Line%20Road%20City%20NA%22%0A%09%09%09%7D%2C%0A%
0A%09%09%09%7B%0A%09%09%09%09%22id%22%3A%20%22id4%22%2C%0A%09%09%09%09%22title%22%3A%2
0%22Lakeside%20Drugstore%22%2C%0A%09%09%09%09%22description%22%3A%20%2289%20Riverroad%20city%2
0NA%22%0A%09%09%09%7D%2C%0A%09%09%09%7B%0A%09%09%09%09%22id%22%3A%20%22id5%22%2C%0A%
09%09%09%09%22title%22%3A%20%22Southwest%20City%20center%22%2C%0A%09%09%09%09%22description%2
2%3A%20%22870%20Southwest%20Main%20St%2C%20City%20NA%22%0A%09%09%09%7D%0A%0A%09%09%5D%
0A%09%7D%5D%0A%7D

Please note:

96
 ● The “userid” parameter is mandatory and its value is to be sent in an unencrypted format. All the
other parameters must be sent in encrypted format using AES 256 encryption and base64 encoded
with the Key shared, in the “encrdata” parameter.

● You must use the key generated for your enterprise account to encrypt API parameter values when
sending the API request. Once the request is received by Gupshup, the payload is decrypted by
Gupshup and sent ahead to WhatsApp.

● Please read Appendix A for detailed steps and code samples on how to encrypt the payload before
sending an API request.
Send a Dynamic Quick Reply Buttons:

Dynamic Quick reply buttons are supported for both Text & Media (Image, Document & Video) hence the
supported methods will be – “SendMessage” & “SendMediaMessage”

Sending Dynamic Buttons for Text Messages:

API Endpoint
To send a contact card message on WhatsApp in response to a customer’s inbound message, the API
request is made to this endpoint:

https://media.smsgupshup.com/GatewayAPI/rest

Request Headers
Content-Type application/x-www-form-urlencoded

Request Body

Key Description Example

userid The userid of your Gupshup account. The number 2000155005
REQUIRED | string must be in pure numeric format with no special
characters.

Note: Gupshup will provide separate userid and

password to send Customer Support reply messages,
it will not be the same as the userid to send
Notifications
password The password of your Gupshup account for sh1gw4e
REQUIRED | string authentication of the userid
method The API method to perform a specific action i.e. SendMessage
REQUIRED | string send a message on WhatsApp

Must be: SendMessage

auth_scheme The authentication scheme of the API. Plain
REQUIRED | string

97
 Must be: plain
v The API version. 1.1
REQUIRED | string
Must be: 1.1
send_to The phone number of the recipient to whom the 919892123456
REQUIRED | string message is being sent. Number must be in E.164
Format.
msg The Message that will be sent in the body of the Hello John,
REQUIRED | string message As per your request please
Must be within 1024 characters including variable find the list of ATMs in and
values around the Pincode shared
by you.
Tap on “List” to view furthe
and make a selection.
action This is the encoded JSON that specifies the button Sample specified below at
REQUIRED | string name and identifiers the end of this table.

interactive_type The type of Interactive message to be sent to the dr_button

REQUIRED | string customer.
This is a mandatory parameter

Must to be dr_button for dynamic reply buttons

msg_type The type of message to be sent to the customer. text
REQUIRED | string Depending on ‘type’, the relevant parameters must be
sent as part of the request payload. By default,
type is TEXT unless otherwise specified.
Must be one of: TEXT, DATA_TEXT
data_encoding The encoding type of the message i.e. plain English Text
OPTIONAL | string text or Unicode i.e. message is in another language or
contains special characters / emoji.

Must be one of: text, Unicode_text

format The API response message format. Default value is Json
OPTIONAL | string text, unless otherwise specified.

Must be one of: text, json, xml

msg_id A Custom message ID that can be specified by the 134389132153571381
OPTIONAL | string business. This will be attached to Message Status
Callbacks and can help you track messages using your
internal IDs. 200 characters alphanumeric values are
allowed for msg_id and it must be unique
for every message sent.
extra A Custom parameter that can be used as an SUPER100SEGMENT
OPTIONAL | string identifier for reporting purposes. You can input any
text in this parameter and the same value will be
forwarded in the Status Callback. 50 alphanumeric
98
 Characters are allowed for this parameter.
header In a Text message, a header usually refers to the Text message :
OPTIONAL | string ‘Title’ of the message. “Booking confirmation for
60 alphanumeric characters (with variable values) are Movie”
allowed for this parameter.

footer A short line of text to the bottom of the message “Get yourself
OPTIONAL | string template. web-checked-in, to avoid
60 alphanumeric characters are allowed for this queues”
parameter.
linkTrackingEnabled This parameter can be used to specify linktracking for True
OPTIONAL | string links present in the ‘msg’ request parameter
Must be : True/false

isHSM This indicates whether the message is a Message false

REQUIRED | boolean Template (HSM) i.e. a pre-approved message
template. Since this is a Customer support reply,
always set this as ‘false’.

Must be: false

Sending Dynamic Buttons for Media Messages:

API Endpoint
To send a contact card message on WhatsApp in response to a customer’s inbound message, the API
request is made to this endpoint:

https://media.smsgupshup.com/GatewayAPI/rest

Request Headers

Content-Type application/x-www-form-urlencoded

Request Body

Key Description Example

userid The userid of your Gupshup account. The number 2000155005
REQUIRED | string must be in pure numeric format with no special
characters.

Note: Gupshup will provide separate userid and

password to send Customer Support reply messages,
it will not be the same as the userid to send
Notifications.

99
password The password of your Gupshup account for sh1gw4e
REQUIRED | string authentication of the userid
method The API method to perform a specific action i.e. SendMediaMessage
REQUIRED | string send a message on WhatsApp

Must be: SendMediaMessage

auth_scheme The authentication scheme of the API. plain
REQUIRED | string
Must be: plain
v The API version. 1.1
REQUIRED | string
Must be: 1.1
send_to The phone number of the recipient to whom message 919892123456
REQUIRED | string being sent. Number must be in E.164
format.
msg_type The type of message to be sent to the customer. IMAGE
REQUIRED | string
Must be one of: IMAGE, DOCUMENT, VIDEO
media_url The Public URL where the media attachment file is https://image.shutterstock.c
REQUIRED | string hosted. om/image-
illustration/movie-ticket-
icon-260nw-663331288.jpg
isHSM This indicates whether the message is a Message false
REQUIRED | boolean Template (HSM) i.e. a pre-approved message
template. Since this is a Customer support reply,
always set this as ‘false’.

Must be: false

caption The caption text to be sent along with the media Your ticket is confirmed for
REQUIRED | string Attachment. 20-DEC-2019.

action This is the encoded JSON that specifies the button %7B%0A%09%22buttons%2
REQUIRED | string name and identifiers %3A%20%5B%7B%0A%09%
%09%22type%22%3A%20%
reply%22%2C%0A%09%09%
%22reply%22%3A%20%7B%
A%09%09%09%09%22id%22
3A%20%22123-%E0%A5%A7
22%2C%0A%09%09%09%09
22title%22%3A%20%22%E0
A4%A8%E0%A4%BE%E0%A4
B0%E0%A5%8D%E0%A4%A5
20%E0%A4%B8%E0%A5%87
E0%A4%A3%E0%A5%8D%E0
A4%9F%E0%A4%B0%F0%9F

100
 98%83%22%0A%09%09%09
7D%0A%09%09%7D%2C%0A
09%09%7B%0A%09%09%09
22type%22%3A%20%22repl
%22%2C%0A%09%09%09%2
eply%22%3A%20%7B%0A%
%09%09%09%22id%22%3A%
0%22123-2%22%2C%0A%09
09%09%09%22title%22%3A
20%22Gas%22%0A%09%09
9%7D%0A%09%09%7D%2C%
A%09%09%7B%0A%09%09%
9%22type%22%3A%20%22r
ly%22%2C%0A%09%09%09%
2reply%22%3A%20%7B%0A
09%09%09%09%22id%22%3
%20%22123-3%22%2C%0A%
9%09%09%09%22title%22%
A%20%22Mobile%22%0A%0
%09%09%7D%0A%09%09%
%0A%5D%0A%7D
interactive_type The type of Interactive message to be sent to the dr_button
REQUIRED | string customer.
This is a mandatory parameter
Has to be dr_button for dynamic reply buttons
msg The text message to be sent to the customer via SMS Your ticket is confirmed for
OPTIONAL | string if fallback to SMS is configured. 20-DEC-2019.

data_encoding The encoding type of the message i.e. plain English text
OPTIONAL | string text or Unicode i.e. message is in another language or
contains special characters / emoji .

Must be one of: text, Unicode_text

format The API response message format. Default value is json
OPTIONAL | string text, unless otherwise specified.

Must be one of: text, json, xml

preview_url This indicates whether a preview should be displayed f true
OPTIONAL | boolean a link present in the ‘msg’ parameter. By default, it
will be ‘false’ which means links will be clickable but
no preview will be seen. Preview of a URL means that
the title of the webpage along with thumbnail is
displayed.

Must be one of: true, false

101
 msg_id A Custom message ID that can be specified by the 134389132153571381
OPTIONAL | string business. This will be attached to Message Status
Callbacks and can help you track messages using your
internal IDs. 200 characters alphanumeric
values are allowed for msg_id and it must be unique
for every message sent.
footer A short line of text to the bottom of the message “Get yourself web-checked-
OPTIONAL | string template. to avoid queues”
60 alphanumeric characters are allowed for this
parameter.
linkTrackingEnabled This parameter can be used to specify linktracking for True
OPTIONAL | string links present in the caption
Must be : True/false

JSON structure for action:

{
"buttons": [
{
"type": "reply",
"reply": {
"id": "button_id_1",
"title": "button_name_1"
}
},
{
"type": "reply",
"reply": {
"id": "button_id_2",
"title": "button_name_2"
}
},
{
"type": "reply",
"reply": {
"id": "button_id_3",
"title": "button_name_3"
}
}
]
}

Example JSON for action for Dynamic Buttons: (Decoded version)

{
"buttons": [{
"type": "reply",
"reply": {
"id": "123-1",

102
 "title": "Electric"
}
},
{
"type": "reply",
"reply": {
"id": "123-2",
"title": "Gas"
}
},
{
"type": "reply",
"reply": {
"id": "123-3",
"title": "Mobile"
}
}
]
}
Key Description
Action ● The type has to mandatorily be “reply”
● The id has to be an alphanumeric string with a character length of 256 (special
characters and spaces are permitted)
● The title is the name of the button. The maximum number of characters allowe
is 20 (Alphanumeric, Emojis and spaces permitted; special characters if inserted
appear as is)
● A single request with more than one button must have unique values for “id” as
this will be sent in the incoming web-hook events to the call back URL so that th
button selected can be identified.
● Maximum buttons allowed is 3.
● The same “id” value can be used in other requests.
Sample Requests

Text with Dynamic Buttons:

Below is a sample POST request to send a dynamic button text Message on WhatsApp, within the 24 hour
Customer Care Window.

curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest'

\
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'method=SendMessage' \
--data-urlencode 'send_to=91XXXXXXX' \
--data-urlencode 'msg_type=Text' \
--data-urlencode 'userid=20000XXXXXX' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'password=XXXXXX' \
--data-urlencode 'v=1.1' \
--data-urlencode 'format=text' \
--data-urlencode 'data_encoding=TEXT' \

103
 --data-urlencode 'msg=Welcome to ABC Bank. Kindly select your Accountt Type.'
\
--data-urlencode 'action={
"buttons": [{
"type": "reply",
"reply": {
"id": "1a",
"title": "Balance"
}
},
{
"type": "reply",
"reply": {
"id": "1b",
"title": "Current"
}
},
{
"type": "reply",
"reply": {
"id": "1c",
"title": "Savings"
}
}
]
}' \
--data-urlencode 'interactive_type=dr_button' \
--data-urlencode 'footer=ABC Bank ' \
--data-urlencode 'msg_id=Test01' \
--data-urlencode 'isHSM=false'

Media with Dynamic Buttons

Below is a sample POST request when sending a dynamic button Media Message (Document) on WhatsApp,
within the 24 hour Customer Care Window.

curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest' \

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'method=SendMediaMessage' \
--data-urlencode 'send_to=91XXXXXXX' \
--data-urlencode 'msg_type=IMAGE' \
--data-urlencode 'userid=20000XXXXXX' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'password=XXXXXX' \
--data-urlencode 'v=1.1' \
--data-urlencode 'format=text' \
--data-urlencode 'data_encoding=TEXT' \
--data-urlencode 'media_url=https://www.gstatic.com/webp/gallery3/1.png' \
--data-urlencode 'msg=Welcome to ABC Bank. Kindly select your Accout Type.' \
--data-urlencode 'action={
"buttons": [{
"type": "reply",
"reply": {
"id": "1a",
"title": "Balance"

104
 }
},
{
"type": "reply",
"reply": {
"id": "1b",
"title": "Current"
}
},
{
"type": "reply",
"reply": {
"id": "1c",
"title": "Savings"
}
}
]
}' \
--data-urlencode 'interactive_type=dr_button' \
--data-urlencode 'footer=ABC Bank ' \
--data-urlencode 'msg_id=Test01' \
--data-urlencode 'isHSM=false'
Encrypted request
It is possible to encrypt requests using the 256 Bit AES encryption key generated for the 2-way account.
Below is a sample GET request with encrypted data in the payload, to send a Media message with Dynamic
button on WhatsApp in a 24 hour window.

https://media.smsgupshup.com/GatewayAPI/rest?userid=2000XXXXXX&encrdata={{Base64
_Encoded_Encrypted_ Data}}
where, encrdata =

method=SendMediaMessage&msg_type=DOCUMENT&auth_scheme=plain&password=XXXXX&data_encod
ing=TEXT&interactive_type=dr_button&send_to=91XXXXXXXXXX&v=1.1&format=TEXT&footer=Only%20Me
dium%20size%20left%20to%20get%20it%20now%20please%20click%20on%20here%20now&linkTrackingE
nabled=True&action=%7B%0A%09%22buttons%22%3A%20%5B%7B%0A%09%09%09%22type%22%3A%20
%22reply%22%2C%0A%09%09%09%22reply%22%3A%20%7B%0A%09%09%09%09%22id%22%3A%20%221
23-%E0%A5%A7%22%2C%0A%09%09%09%09%22title%22%3A%20%22%E0%A4%A8%E0%A4%BE%E0%A4
%B0%E0%A5%8D%E0%A4%A5%20%E0%A4%B8%E0%A5%87%E0%A4%A3%E0%A5%8D%E0%A4%9F%E0%A
4%B0%F0%9F%98%83%22%0A%09%09%09%7D%0A%09%09%7D%2C%0A%09%09%7B%0A%09%09%09%2
2type%22%3A%20%22reply%22%2C%0A%09%09%09%22reply%22%3A%20%7B%0A%09%09%09%09%22id
%22%3A%20%22123-2%23%23%23%23%23%23*%26!%20%20%20%20%20%20%20%20%20%20%20%20%
22%2C%0A%09%09%09%09%22title%22%3A%20%22Gas%22%0A%09%09%09%7D%0A%09%09%7D%2C%
0A%09%09%7B%0A%09%09%09%22type%22%3A%20%22reply%22%2C%0A%09%09%09%22reply%22%3A
%20%7B%0A%09%09%09%09%22id%22%3A%20%221233%22%2C%0A%09%09%09%09%22title%22%3A%
20%22Mobile%206P123%25%25%25%22%0A%09%09%09%7D%0A%09%09%7D%0A%5D%0A%7D&media_
url=http://enterprise.smsgupshup.com/help/in/EnterpriseEmailAPIDocument.pdf&caption=hi%20test%20m
essage&isHSM=false&filename=test.pdf

Please note:

105
 ● The “userid” parameter is mandatory and its value is to be sent in an unencrypted format. All the
other parameters must be sent in encrypted format using AES 256 encryption and base64 encoded
with the Key shared, in the “encrdata” parameter.

● You must use the key generated for your enterprise account to encrypt API parameter values when
sending the API request. Once the request is received by Gupshup, the payload is decrypted by
Gupshup and sent ahead to WhatsApp.

● Please read Appendix A for detailed steps and code samples on how to encrypt the payload before
sending an API request.

Sending Single and Multi-Product Messages

Single Product Messages:

API Endpoint:
https://media.smsgupshup.com/GatewayAPI/rest

Request Headers:

Content-Type application/x-www-form-urlencoded

Request Body:

Key Description Example

userid The userid of your Gupshup account. The number must be in 2000155005
REQUIRED | string pure numeric format with no special characters.
Note: Gupshup will provide separate userid and
password to send Customer Support reply messages, it will not
be the same as the userid to send
Notifications.
Use the two-way account

password The password of your Gupshup account for sh1gw4e

REQUIRED | string authentication of the userid

106
method The API method to perform a specific action i.e. send a message o SendMessage
REQUIRED | string WhatsApp
Must be: SendMessage

auth_scheme The authentication scheme of the API. Plain

REQUIRED | string Must be: plain

v The API version. 1.1

REQUIRED | string Must be: 1.1

send_to The phone number of the recipient to whom the message is 919892123456
REQUIRED | string being sent. Number must be in E.164
Format.

msg The Message that will be sent in the body of the message Spread happiness in this
REQUIRED | string Must be within 1024 characters including variable values Diwali Shop Now !!

action This is the encoded JSON that specifies product_retailer_id and %7B%0A%20%20%22cat
REQUIRED | string catalog_id log_id%22%3A%20%223
5734710358881%22%2C
%0A%20%20%22produc
_retailer_id%22%3A%20
%22f86o93ihkn%22%0A
7D%0A%0A

interactive_type The type of Interactive message to be sent to the customer. product

REQUIRED | string This is a mandatory parameter
Must be “product” for Single Product Messages

msg_type The type of message to be sent to the customer. Depending on text

OPTIONAL | string ‘type’, the relevant parameters must be sent as part of the request
payload. By default,
the type is TEXT unless otherwise specified.
Must be one of: DATA_TEXT, TEXT

data_encoding The encoding type of the message i.e. plain English text or Unicod Text
OPTIONAL | string i.e. message is in another language or contains special characters /
emoji .
Must be one of: text, Unicode_text

107
format The API response message format. Default value is text unless Json
OPTIONAL | string otherwise specified.
Must be one of: text, json, xml

msg_id A Custom message ID that can be specified by the business. This 134389132153571381
OPTIONAL | string will be attached to Message Status Callbacks and can help you trac
messages using your internal IDs. 200 characters alphanumeric
values are allowed for msg_id and it must be unique
for every message sent.

footer A short line of text to the bottom of the message template. “Check your Cart before
OPTIONAL | string 60 alphanumeric characters are allowed for this parameter. placing order”

extra A Custom parameter that can be used as an 45123id

OPTIONAL | string Identifier for reporting purposes. You can input any text in this
parameter and the same value will be forwarded in the Status
Callback. 50 alphanumeric
characters are allowed for this parameter.

isHSM This indicates whether the message is a Message Template (HSM false
REQUIRED | boolean i.e. a pre-approved message template. Here, the API will run a
template check and submit the message as an HSM to WhatsApp
server. By default, unless specified, it will be ‘false’

Must be one of: true, false

JSON structure for the ‘action’ parameter:

JSON Structure JSON example

{ {
"catalog_id": "catalog-id", "catalog_id": "315734710358881",
"product_retailer_id": "product-SKU-in-catalog" "product_retailer_id": "f86o93ihkn"
} }

108
 Key Description

catalog_id ID for the catalog you want to use for this message. Retrieve this ID via Commerce
REQUIRED | string Manager.

product_retailer_ Unique identifier of the product in a catalog. This can be retrieved via Commerce
REQUIRED | string Manager.

Sample request

Below is a sample POST request to send a Single Product message on WhatsApp, within the 24 hour
Customer Care Window.

curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest' \

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'userid=2000XXXXXX' \
--data-urlencode 'password=XXXXXXXX' \
--data-urlencode 'method=SendMessage' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'v=1.1' \
--data-urlencode 'send_to=91XXXXXXXXXX' \
--data-urlencode 'msg=Enjoy Shopping here' \
--data-urlencode
'action={"catalog_id":"XXXXXXXXXX","product_retailer_id":"XXXXXXX"}' \
--data-urlencode 'interactive_type=product' \
--data-urlencode 'isHSM=false'

Multi-Product messages

API Endpoint:
https://media.smsgupshup.com/GatewayAPI/rest
Request Headers:

Content-Type application/x-www-form-urlencoded

Request Body

Key Description Example

109
userid The userid of your Gupshup account. The number must 2000155005
REQUIRED | string be in pure numeric format with no special characters.
Note: Gupshup will provide separate userid and passwor
to send Customer Support reply messages, it will not be
the same as the userid to send
Notifications. Use the two way account

password The password of your Gupshup account for sh1gw4e

REQUIRED | string authentication of the userid

method The API method to perform a specific action i.e. send a SendMessage
REQUIRED | string message on WhatsApp
Must be: SendMessage

auth_scheme The authentication scheme of the API. Plain

REQUIRED | string Must be: plain

v The API version. 1.1

REQUIRED | string Must be: 1.1

send_to The phone number of the recipient to whom the messag 919892123456
REQUIRED | string is being sent. Number must be in E.164
Format.

msg The Message that will be sent in the body of the messag Spread happiness in this
REQUIRED | string Must be within 1024 characters including variable values Diwali Shop Now !!

110
action This is the encoded JSON that specifies the product list %7B%0A%20%20%22cata
REQUIRED | string sections, rows and description g_id%22%3A%20%223157
4710358881%22%2C%0A%
20%20%22sections%22%3
%20%5B%0A%20%20%20
20%7B%0A%20%20%20%
0%20%20%22title%22%3A
%20%22Section%201%22%
2C%0A%20%20%20%20%
0%20%22product_items%
2%3A%20%5B%0A%20%2
%20%20%20%20%20%20%
7B%0A%20%20%20%20%
0%20%20%20%20%20%22
product_retailer_id%22%3
A%20%22f86o93ihkn%22%
0A%20%20%20%20%20%2
0%20%20%7D%0A%20%2
%20%20%20%20%5D%0A
20%20%20%20%7D%2C%
A%20%20%20%20%7B%0A
%20%20%20%20%20%20%
22title%22%3A%20%22Se
tion%202%22%2C%0A%20
%20%20%20%20%20%22p
oduct_items%22%3A%20%
5B%0A%20%20%20%20%
0%20%20%20%7B%0A%2
%20%20%20%20%20%20%
20%20%20%22product_re
ailer_id%22%3A%20%22o
vst7wade%22%0A%20%20
%20%20%20%20%20%20%
7D%0A%20%20%20%20%
0%20%5D%0A%20%20%2
%20%7D%0A%20%20%5D
%0A%7D

interactive_type The type of Interactive message to be sent to the product_list

REQUIRED | string customer.
This is a mandatory parameter
Has to be “product_list” for Multi Product Messages

111
header The title of the header component of the MPM Our Product
REQUIRED | string message

msg_type The type of message to be sent to the customer. text

OPTIONAL | string Depending on ‘type’, the relevant parameters must be
sent as part of the request payload. By default,
the type is TEXT unless otherwise specified.
Must be one of: DATA_TEXT, TEXT

data_encoding The encoding type of the message i.e. plain English text Text
OPTIONAL | string or Unicode i.e. message is in another language or
contains special characters / emoji .
Must be one of: text, Unicode_text

format The API response message format. Default value is text, Json
OPTIONAL | string unless otherwise specified.
Must be one of: text, json, xml

msg_id A Custom message ID that can be specified by the 134389132153571381

OPTIONAL | string business. This will be attached to Message Status
Callbacks and can help you track messages using your
internal IDs. 200 characters alphanumeric values are
allowed for msg_id and it must be unique
for every message sent.

header In a Text message, a header usually refers to the

OPTIONAL | string ‘Title’ of the message. “SALE”
60 alphanumeric characters (with variable values) are
allowed for this parameter.

footer A short line of text to the bottom of the message “Check your Cart before
OPTIONAL | string template. placing an order”
60 alphanumeric characters are allowed for this
parameter.

extra A Custom parameter that can be used as an identifier 45123id

OPTIONAL | string for reporting purposes. You can input any text in this
parameter and the same value will be forwarded in the
Status Callback. 50 alphanumeric
Characters are allowed for this parameter.

112
 isHSM This indicates whether the message is a Message false
REQUIRED | boolean Template (HSM) i.e. a pre-approved message template.
Here, the API will run a template check and submit the
message as an HSM to WhatsApp server. By default,
unless specified, it will be ‘false’

Must be one of: true, false

JSON structure for the ‘action’ parameter:

JSON Structure JSON example

{ {
"catalog_id":"catalog-id", "catalog_id": "315734710358881",
"sections": [ "sections": [
{ {
"title": "the-section-title1", "title": "Section 1",
"product_items": [ "product_items": [
{ "product_retailer_id": { "product_retailer_id": "f86o93ihkn" },
"product-SKU-in-catalog1" }, {"product_retailer_id": "ke1cj16tgq" }
{ "product_retailer_id": ]
"product-SKU-in-catalog2" }, },
... {
]}, "title": "Section 2",
{ "product_items": [
"title": "the-section-title2", {"product_retailer_id": "o8vst7wade"},
"product_items": [ {"product_retailer_id": "f86o93ihkn"}
{ "product_retailer_id": ]
"product-SKU-in-catalog3" } }
... ]
]}, }
...
]}

Action components:

Key Description

catalog_id ID for the catalog you want to use for this message. Retrieve this ID via Commerce
REQUIRED | string Manager.

sections Array of section objects. You must include at least one section.
REQUIRED | string

title Include a title for each section if you plan to use more than one.
REQUIRED | string

113
 product_items Array of product objects that should be displayed.
REQUIRED | string

product_retailer_ Unique identifier of the product in a catalog. This can be retrieved via Commerce
REQUIRED | string Manager.

Sample Requests:

Below is a sample POST request to send a Multi-Product message on WhatsApp, within the 24 hour
Customer Care Window.

curl --location --request POST 'https://media.smsgupshup.com/GatewayAPI/rest' \

--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'send_to=917406601953' \
--data-urlencode 'msg_type=text' \
--data-urlencode 'userid=2000xxxxxx' \
--data-urlencode 'auth_scheme=plain' \
--data-urlencode 'password=xxxxx' \
--data-urlencode 'method=SendMessage' \
--data-urlencode 'v=1.1' \
--data-urlencode 'format=json' \
--data-urlencode 'msg=Please select a product from the catalogue below!\rType
*0* to go back.' \
--data-urlencode 'action={
"catalog_id": "354830406633327",
"sections": [
{
"title": "Section 1",
"product_items": [
{ "product_retailer_id": "40378217562274" },
{"product_retailer_id": "42351654371490" }
]
},
{
"title": "Section 2",
"product_items": [
{"product_retailer_id": "29386563420202"},
{"product_retailer_id": "42633034399906"}
]
}
]
}
' \
--data-urlencode 'header=testing' \
--data-urlencode 'interactive_type=Product_list'

Sending a Sticker Message

API Endpoint:
https://media.smsgupshup.com/GatewayAPI/rest

114
curl --location 'https://media.smsgupshup.com/GatewayAPI/rest' \
--form 'send_to="919797979797"' \
--form 'msg_type="STICKER"' \
--form 'userid="20000xxxxx"' \
--form 'auth_scheme="plain"' \
--form 'password="xxxxx"' \
--form 'v="1.1"' \
--form 'format="text"' \
--form 'isHSM="false"' \
--form 'method="SendMediaMessage"' \
--form
'media_url="https://sftp-campaigns-images.s3.amazonaws.com/CampaignTeam/512x512.we
bp"'

Request Headers:

Content-Type application/x-www-form-urlencoded

Request Body

Key Description Example

userid The userid of your Gupshup account. The number must be in 2000155005
REQUIRED | string pure numeric format with no special characters.
Note: Gupshup will provide separate userid and password to
send Customer Support reply messages, it will not be the
same as the userid to sendNotifications. Use the two way
account

password The password of your Gupshup account for sh1gw4e

REQUIRED | string authentication of the userid

method The API method to perform a specific action i.e. send a SendMediaMessage
REQUIRED | string message on WhatsApp
Must be: SenMediadMessage

auth_scheme The authentication scheme of the API. Plain

REQUIRED | string Must be: plain

v The API version. 1.1

REQUIRED | string Must be: 1.1

115
 send_to The phone number of the recipient to whom the message is 919892123456
REQUIRED | string being sent. Number must be in E.164
Format.

media_url The Public URL where the media https://sftp-campaigns-im

REQUIRED | string ges.s3.amazonaws.com/Ca
attachment file is hosted. mpaignTeam/512x512.web
p
Formatting Options
WhatsApp supports some formatting in messages. To format all or part of a message, use these formatting
symbols:

Formatting Symbol Example How message displays on WhatsAp

Bold Asterisk (*) Your total is *$10.50*. Your total is $10.50.

Italics Underscore (_) Welcome to _WhatsApp_! Welcome to WhatsApp!
Strike-through Tilde (~) This is ~better~ best! This is better best!
Code Three backticks (```) ```print 'Hello World';``` print 'Hello World';

Emoji are also supported. List of supported emoji are at https://emojipedia.org/whatsapp/ . Copy the emoji
symbol in the message when sending through API. Use data_encoding=Unicode_text when sending a
message containing emoji and be mindful of the 1024-character limit for a Unicode message.

API Response

A successful API request generates an HTTP 200 response. The response will be specified as a JSON array
with response status and unique identifier.

{
"response": {
"id": "3914460380512464906-350465300787800379",
"phone": "919777777778",
"details": "", "status": "success"
}
}

This indicates that the message has been successfully sent to mobile number 919777777778 under a
Unique Identifier ‘3914460380512464906-350465300787800379’. The identifier string is unique for each
recipient number and is auto generated at the time of message submission. First number is the transaction
ID and second one is message ID. If a custom msg_id is passed in the API request (say, msg_id =1343891), it
would be set as the message ID and returned back in the API response message as the second half of the
unique identifier. For instance, the ‘id’ parameter would be ‘3914460380512464906-1343891’.

116
WhatsApp Delivery Reports

The sent, delivery, read or failed status of Notification and Customer Support Reply messages sent to
WhatsApp using the Gupshup Messaging API can be tracked in real time and via downloadable delivery
reports.

Businesses can initiate a conversation using a template message. The category of the template message that
is used, will define the conversation category,and this will be a part of the downloadable delivery reports.
Details are explained in the respective section below.

Real time Delivery Reports

Message Status Webhooks are triggered by specific events such as a successful message delivery or a
message read receipt on WhatsApp. Whenever that trigger event occurs, the Gupshup Messaging API
registers the event and immediately sends a notification (HTTP/HTTPS POST request) to the Callback URL
specified in your account settings indicating when your message has been sent, delivered or read or failed
on WhatsApp.

Please reach out to your account manager to set the Callback URL for your account in order to receive
message status webhook events. Only one callback URL can be specified per account.

Let's say you have given www.example.com/RealTimeDLR/readurl as the callback URL for a given user
account, Gupshup will send a HTTP/HTTPS POST request (Content-Type=application/x-www-
form-urlencoded) with payload as a key-value pair where 'response' is the key and the value contains a JSON
array of one or more status callback events. There can be up to 20 status callback events per request.

Please note: For the latest implementation of WhatsApp conversations, in order to track conversation based
delivery events, a new parameter is introduced called: ‘conversation’. This will be as a nested JSON Object
will include delivery information such as sent, read, delivered or failed for the conversation messages.

curl --location --request POST 'https://customer callback URL' \

--header 'Content-Type: application/json' \
--data-raw '[
{
"srcAddr": "919898989898",
"channel": "WHATSAPP",
"externalId": "4561577673055671823-327736131207676738",
"cause": "SUCCESS",
"errorCode": "000",
"destAddr": "919999999999",
"eventType": "DELIVERED",
"eventTs": 16X3XX6X30000
}
]'

117
Request payload description:

Key Description Example

externalId Unique ID for each message in the format: 4561577673055671823-32773
causeId-msgId 131207676738
eventType Status of the message request SENT
Possible values are
{SENT, DELIVERED, READ, FAILED}

srcAddr This is WhatsApp Business phone number 919898989898

channel This indicates the messaging channel i.e. WhatsApp WhatsApp
errorCode Error code associated with the different 025
delivery status
eventTs UNIX Timestamp for the delivery event 1643163337000
cause This is the cause specific to eventType. SENT
This will have different values for
eventType = FAILED
destAddr The Phone number of the recipient. 919999999999
hsmTemplateId The template ID of the message that was used to trigg567787
OPTIONAL the message request.

Starting June 1, 2023, the real-time delivery event will be as below (This is not enabled by default for all
the customers):
[
{
"srcAddr": "919898989898",
"channel": "WHATSAPP",
"hsmTemplateId": "6330963",
"externalId": "4873914210717831261-128116432999904428",
"cause": "SENT",
"errorCode": "025",
"destAddr": "91XXXXXXXXXX",
"eventType": "SENT",
"eventTs": 1680527479000,
"conversation": {
"expiration_timestamp": 1680613560,
"origin": {
"type": "marketing"
},
"id": "072a7f95683c6c2bffef5655c706c50d"
},
"pricing": {
"category": "marketing"
}
}
]

118
New Parameter Details:

Key Description Value

conversation This json will contain "conversation": {

conversation details. "expiration_timestamp": 1680613560,
"origin": {
"type": "marketing"
},
"id":
"072a7f95683c6c2bffef5655c706c50d"

expiration_timestamp Unix timestamp representing 24 1680613560

hours after the message

origin Original type of conversation {

"type": "marketing"
},

Id Unique conversation Id sent by 072a7f95683c6c2bffef5655c706c50d

WhatsApp

pricing Final type of conversation {"category":"marketing"}

*origin: type values are identical to pricing: category now, but Meta may add new values to
origin:type in future which is why both exist.

Downloadable Delivery Reports

It is possible to download delivery reports for Notifications and customer support messages (2-way) from
the WhatsApp Analytics Panel.
The Analytics panel user can login and navigate to the ‘Reports’ tab from the menu and then choose a date
range and the Account (Notification or customer support)

Detailed Delivery reports:

Gupshup has implemented the conversations model specified by WhatsApp Business messaging. The offline
downloadable delivery reports for the WhatsApp messages have been enhanced to indicate newer
conversation categories.

Gupshup has introduced the below tags pertaining to different categories of conversations and messages
within the conversations (referred to as platform messages);these tags will be a part of the downloadable
reports under ‘CATEGORY TYPE’
A detailed mapping for your better understanding is a below:

119
 Conversation category Type of message Tag

Marketing Conversation MC

Marketing Platform MC_PF

Utility Conversation UC

Utility Platform UC_PF

Authentication Conversation AC

Authentication Platform AC_PF

Service Conversation SC

Service Platform SC_PF

Referral Conversation RC

Referral Platform RC_PF

Cause corresponding to the eventType / status

errorCode cause eventType / Status

000 SUCCESS DELIVERED

025 SENT DELIVERED
026 READ DELIVERED
020 OTHER FAILED
003 UNKNOWN_SUBSCRIBER FAILED
010 DEFERRED FAILED
022 BLOCKED_FOR_USER FAILED
101 24 Hour exceeded FAILED

Cause Explanation:

• SENT: Message is sent to WhatsApp server successfully (equivalent of single grey tick on
WhatsApp)
• SUCCESS: Message is delivered to the user on WhatsApp (equivalent of two grey ticks on
WhatsApp)
• READ: Message is read by the user on WhatsApp (equivalent of two blue ticks on WhatsApp)

120
• UNKNOWN_SUBSCRIBER: Unknown/invalid number/does not exist on WhatsApp
• BLOCKED_FOR_USER: User is not opted in to WhatsApp
• DEFERRED: Messages that could not be sent to WhatsApp
• OTHER: Message that are sent to WhatsApp but could not be delivered for reasons that don’t
fall under any mentioned category
• 24 Hour exceeded: Error occurs when the business is attempting to reply using template-free
messages while the current 24 hour reply window has expired.

121
APPENDIX A

Symmetric Key Encryption process for method=“Send Message” is described here. The same steps need to
be followed for any other API method as well. Refer section below for sample AES GCM Encryption code.

Form a Querystring using rest of the API parameters and its values:

Querystring:

method=SendMessage&send_to=919XXXXXXXXX&msg=
This%20is%20a%20test%20message&msg_type=TEXT&auth_scheme=plain&password=password&v=1.1
&format=text

Encrypt the query string using AES encryption algorithm (256-bit algorithm)

● Use only GCM mode

● Length of the IV (Initialization Vector) parameter should be 12 bytes. IV value should be unique for
every API request/call.
● Length of authentication tag should be 16 bytes
● Output of AES Encryption (256 bit) should be encoded using base 64 Urlsafe

Output of base64 urlsafe should be passed in encrdata parameter. Base64 encoded encrypted cipher will be
passed as a payload in encrdata parameter.

Sample encrypted payload using above steps: raMuJzQKkfBvWWESo6Lyyhr2q-

5NvTpogCJwku_doItZBsQg7Wj3Lt8qm_jGQMsvpHfGTBREiMNO8FmyahWBsv27tH5n8q0vPgd3kxYgpCbC
QHGfQ0KobiGYnKqHBdqICa_UDLIQrjOjeX4XJOGVyA1bQOaUHA9qSFZ3Ob5SwZk8Ua5tJ5th5L8Nmk6AZA
-P0N8JvwzLjVkSZzIywc1cDU5jlQS6uEartb6z

122
Sample AES GCM Encryption code

This code returns the encrypted payload that needs to be passed in encrdata parameter.

import java.nio.charset.StandardCharsets; import java.security.Key;

import java.security.SecureRandom;

import javax.crypto.Cipher;

import javax.crypto.spec.GCMParameterSpec; import javax.crypto.spec.SecretKeySpec;

import org.apache.commons.codec.binary.Base64;

public class AES

private static final int GCM_IV_LENGTH = 12;

private static final int GCM_TAG_LENGTH = 16;

private static final String GIVEN_KEY = "QOahfcdo98NLjYJuhP4-VKigx51NkUETsKlIu9uXZFY";

public static String encrypt(String text) throws Exception

byte[] bytes = text.getBytes(StandardCharsets.UTF_8);

Key secretKey = new SecretKeySpec(Base64.decodeBase64(GIVEN_KEY), "AES"); byte[] iv = new
byte[GCM_IV_LENGTH];new SecureRandom().nextBytes(iv);

Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");

SecretKeySpec keySpec = new SecretKeySpec(secretKey.getEncoded(), "AES");

GCMParameterSpec gcmParameterSpec = new GCMParameterSpec(GCM_TAG_LENGTH * 8, iv);

cipher.init(Cipher.ENCRYPT_MODE, keySpec, gcmParameterSpec);

byte[] cipherText = cipher.doFinal(bytes);

byte[] finalArray = new byte[cipherText.length + GCM_IV_LENGTH];

123
System.arraycopy(iv, 0, finalArray, 0, GCM_IV_LENGTH); System.arraycopy(cipherText, 0, finalArray,
GCM_IV_LENGTH, cipherText.length);

return new String(Base64.encodeBase64URLSafe(finalArray), StandardCharsets.UTF_8);

}

public static void main(String[] args) throws Exception

/* Note that values in query String are URL encoded. */

String queryString = "method=SendMessage&send_to=919XXXXXXXXX&msg=

This%20is%20a%20test%20message&msg_type=TEXT&auth_scheme=plain&password=password&v=1.1
&format=text ";
System.out.println(AES.encrypt(queryString));

}
***********************************************************************************

Sample AES GCM Encryption code (node.js)

let encrypt = (text) => {

const crypto = require('crypto');
const GCM_IV_LENGTH = 12;
const GCM_TAG_LENGTH_BYTES = 16;
const GIVEN_KEY = "QOahfcdo98NLjYJuhP4-VKigx51NkUETsKlIu9uXZFY";//32 byte key
const ALGO = "aes-256-gcm";

//initialization vector
const iv = Buffer.from(crypto.randomBytes(GCM_IV_LENGTH), 'utf8');

//key decoding
let decodedKey = Buffer.from(GIVEN_KEY, 'base64');

//initializing the cipher

const cipher = crypto.createCipheriv(ALGO, decodedKey, iv, { authTagLength: GCM_TAG_LENGTH_BYTES })
cipher.setAutoPadding(false);
124
 //running encryption
const encrypted = Buffer.concat([cipher.update(text, 'utf8')]);
cipher.final()

//Obtaining auth tag

tag = cipher.getAuthTag();
const finalBuffer = Buffer.concat([iv, encrypted, tag]);

//converting string to base64

const finalString = finalBuffer.toString('base64');

//making the string url safe

const urlSafeString = finalString.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
return urlSafeString;
}

console.log(encrypt("password=XXXXXX&method=TWO_FACTOR_AUTH&v=1.1&phone_no=919XXXXXXXXX
&otp_code=1564"));

***********************************************************************************

Sample AES GCM Encryption code (Language: Python)

#!/usr/bin/python3
'''
- An external Python module 'pycryptodomex' is used in the below program, as The default
'PyCrypto' Library that comes with Python3, doesn't support AES/GCM mode of encryption.
- 'pycryptodomex' can be installed via pip for python3 using:
pip install pycryptodomex
- For more information visit: https://pycryptodome.readthedocs.io/
'''

from Cryptodome.Cipher import AES

from Cryptodome.Random import get_random_bytes
from base64 import urlsafe_b64decode,urlsafe_b64encode

GCM_IV_LENGTH = 12
GCM_TAG_LENGTH_BYTES = 16
GIVEN_KEY = "QOahfcdo98NLjYJuhP4-VKigx51NkUETsKlIu9uXZFY"

queryString = """method=SendMessage&send_to=919XXXXXXXXX&msg=
This%20is%20a%20test%20message&msg_type=TEXT&auth_scheme=plain&password=password&v=1.1
&format=text"""

125
def decode_b64_key(str_key):
#utility method that checks for padding before decoding the key
byte_key = bytes(str_key,'utf-8')
missing_padding = 4-len(byte_key)% 4
if missing_padding:
byte_key += b'=' * missing_padding
return urlsafe_b64decode(byte_key)

def encrypt(str_text):
#initialization vector/nonce
nonce = get_random_bytes(GCM_IV_LENGTH)

#decoding base64 key to byte array

decodedKey = decode_b64_key(GIVEN_KEY)#urlsafe_b64decode(GIVEN_KEY)

#converting original text to byte array

bytes_text = bytes(str_text,'utf-8')

#Initializing Cipher AES/GCM/NoPadding

cipher = AES.new(decodedKey,AES.MODE_GCM,nonce=nonce,mac_len=GCM_TAG_LENGTH_BYTES)

#carrying out encryption

ciphertext, tag = cipher.encrypt_and_digest(bytes_text)
finalbytesbuffer =b"".join([nonce,ciphertext, tag])

#converting bytearray to url safe base64 format

return(urlsafe_b64encode(finalbytesbuffer).decode('utf-8'))

print(encrypt(queryString))

***********************************************************************************

126