WhatsApp Access API documentation API docs now available in: Portuguese, German, Russian and Spanish

Today, more than 1.5 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 API 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 provides specifications of the Gupshup's 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's Messaging API. Also, this guide is applicable for application(app) of type Access API and those created after 28th January 2020 on our platform. In case you have an app which was created before the said date, please migrate the app to V2

Summary of the topics that will be covered in this guide:

1. Set Webhook/Callback URL
2. Inbound Message and Events
   • Events
   • Inbound Message
     • Text
       • Customer Replied to a business message
       • Customer clicked on a Quick Reply template message Button
     • Media
       • Image
       • Audio
       • Video
       • Document
       • Sticker
     • Interactive Messages
       • Customer Replied to a List message
       • Customer Replied to a Quick Reply Button
     • Other messages
       • Location
       • Contact Card
       • Referral
3. Outbound Message
   • Session Messaging
     • API Endpoint
     • API Request
       • Send Text
         • Formatting Options
       • Media
         • Send Image
         • Send Document/File
         • Send Audio
         • Send Video
         • Sticker
       • Interactive Messages
         • List messages
         • Quick replies
       • Other Message Types
         • Send Location
         • Send Contact card
     • API Response
   • Template Messaging
     • API Endpoint
     • API Request
       • Send Text
       • Media
         • Send Image
         • Send Video
         • Send Document
         • Send Location
       • Interactive Messages
         • Call to action
         • Quick replies
     • API Response
4. Miscellaneous APIs
   • Get Opt-in User list API
   • Mark User Opt-in
   • Mark User Opt-out
   • Get Template list
   • Check Wallet balance

Set Webhook/Callback URL

Webhooks handle incoming messages from people who respond to you on WhatsApp including text, location, and media such as pictures and documents as well as the status of the messages you've sent. They are an important channel to deliver, both timely notifications as well as out-of-band errors, and it is thus highly recommended you set one in the application settings.

Inbound messages sent by customers to your WhatsApp Business Phone Number will be sent to your Webhook i.e. customer sends a text message or media attachment on WhatsApp the Gupshup platform registers the event and immediately sends a notification (HTTP POST request) to the Webhook specified in your application settings. Some important notes on Webhook:

1. The webhook should return HTTP_SUCCESS (code: 2xx) with an empty response. Failing to do so within 10 Seconds, we will consider that the notification has failed and we will try again after a short delay.
2. Your webhook should process inbound messages & events asynchronous but acknowledge its reception synchronously & immediately. Best acknowledge time should be less than 100 millisecond, it is understood that there can be a network delay. Hence, recommended is within 500-1000 millisecond. The Greater your response time, the more delayed inbound messages and events you will receive each time.
3. The webhook should accept HTTP header: User-Agent
4. The webhook should accept user event: sandbox-start
5. The webhook should have public access and if for security reason you want to keep it private you are required to whitelist Gupshup's inbound request IPs - please contact devsupport@gupshup.io to get these IPs

In case you are facing issues to set Webhook please refer to this FAQ to know the procedure to troubleshoot.

Refer below image to locate set Webhook/Callback option in the app's settings. If the callback URL toggle is OFF. You can see incoming messages under Inbound Messages | Events field. Messages and events logged under this field are stored temporary meaning if you refresh the page the logs will be cleared.

Inbound Message and Events

There are 5 types of inbound notifications that may be delivered to your webhook, they are:

1. user-event
2. system-event
3. message-event
4. billing-event
5. message

The above notification types can be categorized in two - Events and Inbound Messages, let us first get familiar with the inbound notification structure:

Inbound payload content type

Parameters/Properties common to all incoming notification

{
  "app": "DemoApp",
  "timestamp": 1580227766370,
  "version": 2,
  "type": "user-event"|"template-event"|"message-event"|"message",
  "payload": << This varies according to 'type' property value >>
}

Events

In this section we will understand:
1.  user-event : These are generated by our platform when some event occurs. For example, the following system events are received when:
    - A callback URL is set for an app or while using the proxy command to invoke your app on Gupshup Proxy bot phone number(+917834811114) for testing the app
    - An end-user gives consent(Opt-in) to receive notification from a business phone number.

{
   "app":"DemoApp",
   "timestamp":1580142086287,
   "version":2,
   "type":"user-event",
   "payload":{
      "phone":"callbackSetPhone"|"918x98xx21x4",
      "type":"sandbox-start"|"opted-in"|"opted-out"
   }
}

The payload object

The user-event type:

2.  system-events : These are generated by our platform when some event occurs. You can choose to receive these events on your callback URL from the settings in app dashbaord. For example, the following system events are received when:
    - A system event of type template is received when the status of template is updated. For example, a submitted template has been approved or rejected.
    - A system event of type account is received. For example, when the status of the submitted Phone Number or Display Name for a WABA is updated.
The system events are categorized into two types:

• Template-event

  {
  "app": "jeet20",
  "timestamp": 1636986446609,
  "version": 2,
  "type": "template-event",
  "payload":{ "id": "4dacef15-6c04-12db-b393-6190ac567eff", "status": "REJECTED/APPROVED/DELETED/DISABLED", "elementName": "abcd", "languageCode": "en_US", "rejectedReason": "INAVLID_FORMAT" }
  }
  

  The payload object

  Key	Type	Description	Example
  id	string	It is the unique identifier for a template on the Gupshup platform. You can find the template ID using the API Get template list	4dacef15-6c04-12db-b393-6190ac567eff
  status	string	The updated status of a template. Possible values are REJECTED|APPROVED|DELETED|DISABLED	APPROVED
  elementName	string	The unique name for a template set at during template creation. The elementName of a template is unique within a WABA's namespace	order_update
  languageCode	string	The langauge of the template. You can refer to the language code and the associated langauge here.	en_US
  rejectedReason	string	The reason for template rejection.	INVALID_FORMAT

• Account-events
  Account events are received when an event occurs in a specific WABA. For example, when a WhatsApp business policy is voilated by a WABA, or if the messaging tier limit of a WABA is updated.

The account-event types, and their payload objects are as follows:

3.  message-event : These events states the status of the message sent using the send message API to WhatsApp API client(which essentially send out message to the customer). The WhatsApp Business API client will send notifications to inform you of the status of the messages between you and users. When a message is sent successfully, you will receive a notification when the message is sent, delivered, and read. The order of these notifications in your app may not reflect the actual timing of the message status. View the timestamp to determine the timing, if necessary. The notifications you may receive are:

{
   "app":"DemoAPI",
   "timestamp":1580546677791,
   "version":2,
   "type":"message-event",
   "payload":{
      "id":"59f8db90-c37e-4408-90ab-cc54ef8246ad"(Gupshup Message ID)|"gBEGkYaYVSEEAgnZxQ3JmKK6Wvg" (WhatsApp Message ID)
      "gsId": "ee4a68a0-1203-4c85-8dc3-49d0b3226a35" (Gupshup Message ID - This property is only applicable for DLR events)
      "type":"enqueued"|"failed"|"sent"|"delivered"|"read",
      "destination":"91XX985XX10X",
      "payload": << This varies according to 'type' property value >>;
   }
}

The payload object

message-event types

Message failure codes and their reasons:

To know more about WhatsApp Business API Client Error Codes refer here

4.  billing-event : The event: billing-event is triggered only when a conversation is billable. For free conversations you will not receive a billing-event.

{
    "app": "DemoAPI",
    "timestamp":1580546677791,
    "version":2,
    "type": "billing-event",
    "payload":{
        "deductions":{
            "type": "FEP/UIC/BIC",
            "model": "NBP/CBP",
            "source": "whatsapp"
       },
        "references":{
            "id":"59f8db90c37e-4408-90ab-cc54ef8246ad",
            "gsId":"ee4a68a0-1203-4c85-8dc3-49d0b3226a35",
            "conversationId":"532b57b5f6e63595ccd74c6010e5c5c7",
            "destination":"91XX985XX10X"
        }
    }
}

Deductions object description

References object description

Inbound Message

In this section we will understand event: message that you receive on your callback URL. This event states the type of message payload received on your callback URL when a customer sends a message to the registered WhatsApp Business API phone number.

Headers

Parameters/Properties common to all incoming message

{   
  "app": "DemoApp", 
  "timestamp": 1580227766370,   
  "version": 2, 
  "type": "message",    
  "payload": {  
    "id": "ABEGkYaYVSEEAhAL3SLAWwHKeKrt6s3FKB0c",   
    "source": "918x98xx21x4",   
    "type": "text"|"image"|"file"|"audio"|"video"|"contact"|"location"|"button_reply"|"list_reply", 
    "payload": {    
      //Varies according to the type of payload.    
    },  
    "sender": { 
      "phone": "918x98xx21x4",  
      "name": "Smit",   
      "country_code": "91", 
      "dial_code": "8x98xx21x4" 
    },  
    "context": {    
      "id": "gBEGkYaYVSEEAgnPFrOLcjkFjL8",  
      "gsId": "9b71295f-f7af-4c1f-b2b4-31b4a4867bad"    
    }   
  } 
}   

The payload object

The sender object

The context object

Let us see one by one the types of incoming message received on the Callback URL:

Text

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

{ 
  "app": "DemoApp", 
  "timestamp": 1580227766370,   
  "version": 2, 
  "type": "message",    
  "payload": {  
    "id": "ABEGkYaYVSEEAhAL3SLAWwHKeKrt6s3FKB0c",   
    "source": "918x98xx21x4",   
    "type": "text", 
    "payload": {    
      "text": "Hi"  
    },  
    "sender": { 
      "phone": "918x98xx21x4",  
      "name": "Smit",   
      "country_code": "91", 
      "dial_code": "8x98xx21x4" 
    }   
  } 
}

Customer replied to a business message

Users can respond to a specific message in WhatsApp. For the business to understand the context of a message reply, we include the context object. This context object provides the Gupshup message id(property: gsId) of the message to which the customer replied and the WhatsApp message id(property: id) of the original message.
The following is an example of an inbound message that is a reply to a message that business has sent.

{
  "app": "DemoApp",
  "timestamp": 1590854464792,
  "version": 2,
  "type": "message",
  "payload": {
    "id": "ABEGkYaYVSEEAgo-sMx1DoUoQJRW",
    "source": "918x98xx21x4",
    "type": "text",
    "payload": {
      "text": "hi"
    },
    "sender": {
      "phone": "918x98xx21x4",
      "name": "Smit",
      "country_code": "91",
      "dial_code": "8x98xx21x4"
    },
    "context": {
      "id": "gBEGkYaYVSEEAgnPFrOLcjkFjL8",
      "gsId": "9b71295f-f7af-4c1f-b2b4-31b4a4867bad"
    }
  }
}

Customer clicked on a Quick Reply template message button

When your customer clicks on a quick reply button, a response is sent to your Webhook URL. Below is an example of the callback format.
For the business to understand the context of a message reply, we include the context object. This context object provides the Gupshup message id(property: gsId) of the message to which the customer replied and the WhatsApp message id(property: id) of the original message. In addition to this payload object provides the button text which the user clicked.

{
  "app": "DemoApp",
  "timestamp": 1590854464792,
  "version": 2,
  "type": "message",
  "payload": {
    "id": "ABEGkYaYVSEEAgo-sMx1DoUoQJRW",
    "source": "918x98xx21x4",
    "type": "text",
    "payload": {
      "text": "View Account Balance",
      "type": "button"
    },
    "sender": {
      "phone": "918x98xx21x4",
      "name": "Smit",
      "country_code": "91",
      "dial_code": "8x98xx21x4"
    },
    "context": {
      "id": "gBEGkYaYVSEEAgnPFrOLcjkFjL8",
      "gsId": "9b71295f-f7af-4c1f-b2b4-31b4a4867bad"
    }
  }
}

Media

When a message with media (image | document | audio | video | sticker) is received, the WhatsApp Business API client will download the media. Once the media is downloaded, a notification is sent to our platform and we which is to your Webhook. This message contains information that identifies the media object and enables you to find and download the object.

Common media payload

Image

Below is a sample payload when a customer sends an image along with a caption on WhatsApp to your business number. Caption is only present if specified.

{   
  "app": "DemoApp", 
  "timestamp": 1580227895991,   
  "version": 2, 
  "type": "message",    
  "payload": {  
    "id": "ABEGkYaYVSEEAhAE0dyndiP9cVlr4hC5xU64",   
    "source": "918x98xx21x4",   
    "type": "image",    
    "payload": {    
      "caption": "Sample image",    
      "url": "https://filemanager.gupshup.io/fm/wamedia/DemoApp/546af999-825e-485b-bf54-4a3323824cca",  
      "contentType": "image/jpeg",  
      "urlExpiry": 1624956794816    
    },  
    "sender": { 
      "phone": "918x98xx21x4",  
      "name": "John",   
      "country_code": "91", 
      "dial_code": "8x98xx21x4" 
    }   
  } 
}   

Audio

Below is a sample payload when a customer sends an audio file or voice message on WhatsApp to your business phone number. In case of voice message the content type is always: audio/ogg; codecs=opus

{   
  "app": "DemoApp", 
  "timestamp": 1580228104661,   
  "version": 2, 
  "type": "message",    
  "payload": {  
    "id": "ABEGkYaYVSEEAhC8Sqz6bdT95X8wgVH28wz8",   
    "source": "918x98xx21x4",   
    "type": "audio",    
    "payload": {    
      "url": "https://filemanager.gupshup.io/fm/wamedia/DemoApp/eae8a65a-b3ec-4085-94a6-3738338835fc",  
      "contentType": "audio/ogg; codecs=opus",  
      "urlExpiry": 1624956864635    
    },  
    "sender": { 
      "phone": "918x98xx21x4",  
      "name": "John",   
      "country_code": "91", 
      "dial_code": "8x98xx21x4" 
    }   
  } 
}   

Video

Below is a sample payload when a customer sends a video file along with a caption on WhatsApp to your business number.

{   
  "app": "DemoApp", 
  "timestamp": 1580228336953,   
  "version": 2, 
  "type": "message",    
  "payload": {  
    "id": "ABEGkYaYVSEEAhDHMK-ctBQwqxyKoMbKcxES",   
    "source": "918x98xx21x4",   
    "type": "video",    
    "payload": {    
      "caption": "Sample video",    
      "url": "https://filemanager.gupshup.io/fm/wamedia/DemoApp/9f5ff20a-d14f-47ea-b336-754756a8b950",  
      "contentType": "video/mp4",   
      "urlExpiry": 1580833136954    
    },  
    "sender": { 
      "phone": "918x98xx21x4",  
      "name": "John",   
      "country_code": "91", 
      "dial_code": "8x98xx21x4" 
    }   
  } 
}   

Document

Below is a sample payload when a customer sends a document along with a caption on WhatsApp to your business number. Caption is only present if specified.

{   
  "app": "DemoApp", 
  "timestamp": 1580228523976,   
  "version": 2, 
  "type": "message",    
  "payload": {  
    "id": "ABEGkYaYVSEEAhCzqobr15BdMPcRup1fIXAJ",   
    "source": "918x98xx21x4",   
    "type": "file", 
    "payload": {    
      "caption": "Document caption",    
      "name": "samplefile.pdf", 
      "url": "https://filemanager.gupshup.io/fm/wamedia/DemoApp/b6e4e360-be01-4ffa-8928-84b8f40dd2eb",  
      "contentType": "application/pdf", 
      "urlExpiry": 1624957181122    
    },  
    "sender": { 
      "phone": "918x98xx21x4",  
      "name": "Smit",   
      "country_code": "91", 
      "dial_code": "8x98xx21x4" 
    }   
  } 
}   

Sticker

Below is a sample payload when a customer sends a sticker on WhatsApp to your business number.

{
  "app": "DemoApp",
  "timestamp": 1580228523976,
  "version": 2,
  "type": "message",
  "payload": {
    "id": "ABEGkYaYVSEEAhCzqobr15BdMPcRup1fIXAJ",
    "source": "918x98xx21x4",
    "type": "sticker",
    "payload": {
      "url": "https://filemanager.gupshup.io/fm/wamedia/DemoApp/32030cb2-68de-4c3c-a795-c4647fd4a9c7",
      "contentType": "image/webp",
      "urlExpiry": 1624957279044
    },
    "sender": {
      "phone": "918x98xx21x4",
      "name": "John",
      "country_code": "91",
      "dial_code": "8x98xx21x4"
    }
  }
}

Interactive Messages

Customer replied to a List message

Below is a sample payload when a customer select and submit an item from the list message on WhatsApp to your business number.

{
  "app": "DemoApp",
  "timestamp": 1580228523976,
  "version": 2,
  "type": "message",
  "payload": {
    "id": "ABEGkYaYVSEEAhCzqobr15BdMPcRup1fIXAJ",
    "source": "918x98xx21x4",
    "type": "list_reply",
    "payload": {
            "title": "section 1 row 1",
            "id": "list1",
            "reply":"section 1 row 1 1",
            "postbackText":"section 1 row 1 postback payload",
            "description": "first row of first section description"
        },
    "sender": {
      "phone": "918x98xx21x4",
      "name": "John",
      "country_code": "91",
      "dial_code": "8x98xx21x4"
    },
    "context": {
        "id": "gBEGkYaYVSEEAgnPGGVYGg1uNU4",
        "gsId": "cbdafe39-1023-42a7-89d6-6c01a3388bb5"
    }
  }
}

Customer replied to a Quick Reply button

Below is a sample payload when a customer select an button from the quick reply message on WhatsApp to your business number.

{
  "app": "DemoApp",
  "timestamp": 1580228523976,
  "version": 2,
  "type": "message",
  "payload": {
    "id": "ABEGkYaYVSEEAhCzqobr15BdMPcRup1fIXAJ",
    "source": "918x98xx21x4",   
    "type": "button_reply", 
    "payload": {    
            "title": "First",   
            "id": "qr1",    
            "reply":"First 1"   
        },  
    "sender": { 
      "phone": "918x98xx21x4",  
      "name": "John",   
      "country_code": "91", 
      "dial_code": "8x98xx21x4" 
    },  
    "context": {    
        "id": "gBEGkYaYVSEEAgkvE0f1ZkfXX78",    
        "gsId": "123b0fb2-0620-493b-8f7e-5a1ceb6d8c58"  
    }   
  } 
}   

Other Messages

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.

{   
  "app": "DemoApp", 
  "timestamp": 1580228767338,   
  "version": 2, 
  "type": "message",    
  "payload": {  
    "id": "ABEGkYaYVSEEAhCIxTq7KXQIqby1Uo-IO7_E",   
    "source": "918x98xx21x4",   
    "type": "location", 
    "payload": {    
      "longitude": "72.8552172",    
      "latitude": "19.1453658"  
    },  
    "sender": { 
      "phone": "918x98xx21x4",  
      "name": "Smit",   
      "country_code": "91", 
      "dial_code": "8x98xx21x4" 
    }   
  } 
}   

Contact Card

Below is a sample payload when a customer shares a contact card to your business number.

{
  "app": "DemoApp",
  "timestamp": 1584898884710,
  "version": 2,
  "type": "message",
  "payload": {
    "id": "ABEGkYaYVSEEAhD9cTZVyPlOGYZJOnviI7OJ",
    "source": "918x98xx21x4",
    "type": "contact",
    "payload": {
      "contacts": [
        {
          "addresses": [
            {
              "city": "Menlo Park",
              "country": "United States",
              "countryCode": "us",
              "state": "CA",
              "street": "1 Hacker Way",
              "type": "HOME",
              "zip": "94025"
            },
            {
              "city": "Menlo Park",
              "country": "United States",
              "countryCode": "us",
              "state": "CA",
              "street": "200 Jefferson Dr",
              "type": "WORK",
              "zip": "94025"
            }
          ],
          "emails": [
            {
              "email": "test@fb.com",
              "type": "WORK"
            },
            {
              "email": "test@whatsapp.com",
              "type": "WORK"
            }
          ],
          "ims": [

          ],
          "name": {
            "first_name": "Dev",
            "formatted_name": "Dev Support",
            "last_name": "Support"
          },
          "org": {
            "company": "Dev Support"
          },
          "phones": [
            {
              "phone": "+91 77383 05433",
              "type": "Mobile"
            }
          ],
          "urls": [
            {
              "url": "https://www.facebook.com",
              "type": "WORK"
            }
          ]
        }
      ]
    },
    "sender": {
      "phone": "918x98xx21x4",
      "name": "Smit",
      "country_code": "91",
      "dial_code": "8x98xx21x4"
    }
  }
}

Referral

Included in notifications when a user clicks on an ad that clicks to WhatsApp and sends a message to the business. This object has the ad's information.

{
    "app": "DemoApp",
    "timestamp": 1624350395531,
    "version": 2,
    "type": "message",
    "payload": {
        "id": "ABEGkZlpNARoAgo6v1b-zBR7EnX3",
        "source": "918x98xx21x4",
        "type": "text",
        "payload": {
            "text": "I saw this on Facebook..."
        },
        "sender": {
            "phone": "918x98xx21x4",
            "name": "Smit",
            "country_code": "91",
            "dial_code": "8x98xx21x4"
        },
        "referral": {
                "body": "Test post payload",
                "headline": "Demo Gupshup ad",
                "image": {
                    "id": "6a35b528-429d-4fe3-953d-536ef0397ece"
                },
                "source_id": "951242428775548",
                "source_type": "post",
                "source_url": "https://fb.me/2oNXGTsjn"
        }
    }
}

Outbound Message

Session messaging

This guide teaches you how to send a session message to a customer using the send message API. Currently, this type of messaging can only be done within 24 hours of the last message sent by the user. If you try to send a message outside the 24-hour window, you get a failure event on your webhook. To understand the User states on our platform, please refer to this article, this will help you to use the API more effectively.
Let us understand the API specification/signature i.e the API Endpoint, Headers, Request body and its Response in details:

API Endpoint

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

https://api.gupshup.io/sm/api/v1/msg

API Request

Sample API Request

curl --location --request POST 'https://api.gupshup.io/sm/api/v1/msg' \
--header 'Cache-Control: no-cache' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a' \
--data-urlencode 'channel=whatsapp' \
--data-urlencode 'source=917834811114' \
--data-urlencode 'destination=918x98xx21x4' \
--data-urlencode 'message={"type": "text","text": "Hi John, how are you?"}' \
--data-urlencode 'src.name=DemoApp' \
--data-urlencode 'disablePreview=false'

Headers

Request Body

Common message object parameters

Send text message

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

- A text message can be a max of 4096 characters long.
- To include a URL preview in the message and make sure the URL begins with http:// or https://.
- A URL to be previewed: hostname is required, IP addresses will not be considered.
- If a text message has multiple URL, the first URL will be only previewed

Formatting Options

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

Emoji are also supported. List of supported emoji are at https://emojipedia.org/whatsapp/ . Copy the emoji symbol in the text message when sending through API.

Media

Send Image message

Below is a sample payload when sending an image on WhatsApp.

- Supported Content-Types: image/jpeg, image/png
- maximum file size: 5 MB

Send document/file message

Below is a sample payload when sending a document / file on WhatsApp.

- Supported Content-Types: Any valid MIME-type
- maximum file size: 100 MB

Send Audio message

Below is a sample payload when sending an audio file on WhatsApp.

- Supported Content-Types: audio/aac, audio/mp4, audio/amr, audio/mpeg, audio/ogg; codecs=opus. Note: The base audio/ogg type is not supported.
- maximum file size: 16 MB

Send Video message

Below is a sample payload when sending a video on WhatsApp.

- Supported Content-Types: video/mp4, video/3gpp. Note: Only H.264 video codec and AAC audio codec is supported.
- maximum file size: 16 MB

Send Stickers

Below is a sample payload when sending a sticker on WhatsApp.

- Each sticker has a transparent background.
- Stickers must be exactly 512x512 pixels.
- Each sticker must be less than 100 KB.

Interactive Messages

Send List Messages

Messages including a menu of up to 10 options. This type of message offers a simpler and more consistent way for users to make a selection when interacting with a business. Below is a sample payload for sending list messages to your end-user.

Send Quick replies

This type of message offers a quicker way for users to make a selection from a menu when interacting with a business. Reply buttons have the same user experience as interactive templates with buttons.
Below is a sample payload when sending Quick replies message to end-users on WhatsApp.

Other Messages

Send location message

Below is a sample payload for sending static location to your end-user.

Send Contact Card

Below is a sample payload for share a contact card with your end-user.

API Response

The send message API request received by our platform are processed asynchronously hence, you will always get a HTTP_SUCCESS(200 to 299) response range if the API request was made correctly. API response includes an object with a Gupshup message identifier and status as submitted and your webhook will receive message-event which states that your submitted message to WhatsApp API client(which actually sends message to the customer) is enqueued or failed.

{"status":"submitted","messageId":"ee4a68a0-1203-4c85-8dc3-49d0b3226a35"}

The Gupshup message identifier i.e the messageId in the API response, will help to track the messages via the message events i.e. “enqueued”|“failed”|“sent”|“delivered”|“read” received on the webhook.

Template messaging

Template messaging enables a business to send out notification to their customers outside 24 hours window. WhatsApp mandates that notification should be only send to the users who has given consent to receive messages from the business. Keeping this as a default behavior on our platform, template messages can be only sent to users who are marked opt-in. To Mark a user as opt-in use Mark User Opt-in API

We have been receiving queries from our platform users that they are facing issues to send template messages to their end-user. On analysis we found these issues were mostly related to message mismatch with that of the approved template. Hence, a new template messaging API was released to reduce such errors.
This doesn't indicates that the generic API to send both session and template message is deprecated for template messaging, one can still make use of it. Below is the traditional template messaging API:

Unlike above API, were you are required to send the entire message body with text markers/placeholders. The new template messaging API only takes template id and placeholders value.

Let us understand the API specification/signature i.e the API Endpoint, Headers, Request body and its Response in details:

API Endpoint

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

http://api.gupshup.io/sm/api/v1/template/msg

API Request

Sample API Request

curl --location --request POST 'http://api.gupshup.io/sm/api/v1/template/msg' \
--header 'apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'source=917834811114' \
--data-urlencode 'destination=918x98xx21x4' \
--data-urlencode 'template={"id": "c6aecef6-bcb0-4fb1-8100-28c094e3bc6b","params": ["Agent","Local Address","Tracking code"]}'

Headers

Request Body

API Response

The send message API request received by our platform are processed asynchronously hence, you will always get a HTTP_SUCCESS(200 to 299) response range if the API request was made correctly. API response includes an object with a Gupshup message identifier and status as submitted and your webhook will receive message-event which states that your submitted message to WhatsApp API client(which actually sends message to the customer) is enqueued or failed.

{
    "messageId": "bf70b8c4-a5b9-4acd-b108-512ce704f4dc",
    "status": "submitted"
}

The Gupshup message identifier i.e the messageId in the API response, will help to track the messages via the message events i.e. “enqueued”|“failed”|“sent”|“delivered”|“read” received on the webhook.

Sample API request for each message types. These examples are for illustrative purposes only and cannot be used. You must create your own samples and have them approved in order to test.

Send Text

curl --location --request POST 'http://api.gupshup.io/sm/api/v1/template/msg' \
--header 'apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'source=917834811114' \
--data-urlencode 'destination=918x98xx21x4' \
--data-urlencode 'template={"id": "c6aecef6-bcb0-4fb1-8100-28c094e3bc6b","params": ["Agent","Local Address","Tracking code"]}'

Media

Send Image

curl --location --request POST 'http://api.gupshup.io/sm/api/v1/template/msg' \
--header 'apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'source=917834811114' \
--data-urlencode 'destination=918x98xx21x4' \
--data-urlencode 'template={"id": "c6aecef6-bcb0-4fb1-8100-28c094e3bc6b","params": ["Agent","Local Address","Tracking code"]}' \
--data-urlencode 'message={"type":"image","image":{"link":"https://images.pexels.com/photos/248797/pexels-photo-248797.jpeg"}}'

Send Video

curl --location --request POST 'http://api.gupshup.io/sm/api/v1/template/msg' \
--header 'apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'source=917834811114' \
--data-urlencode 'destination=918x98xx21x4' \
--data-urlencode 'template={"id": "c6aecef6-bcb0-4fb1-8100-28c094e3bc6b","params": ["Agent","Local Address","Tracking code"]}' \
--data-urlencode 'message={"type":"video","video":{"link": "https://www.buildquickbots.com/whatsapp/media/sample/video/sample01.mp4"}}'

Send Document

curl --location --request POST 'http://api.gupshup.io/sm/api/v1/template/msg' \
--header 'apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'source=917834811114' \
--data-urlencode 'destination=918x98xx21x4' \
--data-urlencode 'template={"id": "c6aecef6-bcb0-4fb1-8100-28c094e3bc6b","params": ["Agent","Local Address","Tracking code"]}' \
--data-urlencode 'message={"type":"document","document":{"link":"https://www.buildquickbots.com/whatsapp/media/sample/pdf/sample01.pdf","filename": "Sample funtional resume"}}'

Send Location

curl --location --request POST 'http://api.gupshup.io/sm/api/v1/template/msg' \
--header 'apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'source=917834811114' \
--data-urlencode 'destination=918x98xx21x4' \
--data-urlencode 'template={"id": "c6aecef6-bcb0-4fb1-8100-28c094e3bc6b","params": ["Agent","Local Address","Tracking code"]}' \
--data-urlencode 'message={"type":"location","location":{"longitude":"","latitude":""}}'

Interactive Messages

Call to action

For an approved media interactive template like this:
Hi {{1}}, Please find the attached bill. For more details please visit our website. | [Visit Website,https://www.gupshup.io/developer/{{1}}]

Where we have placeholder in message body as well as in call to action button, the API request can be:

curl --location --request POST 'http://api.gupshup.io/sm/api/v1/template/msg' \
--header 'apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'source=917834811114' \
--data-urlencode 'destination=918x98xx21x4' \
--data-urlencode 'template={"id": "c49ee21d-4d39-452d-a6c1-25b7615e01e4","params": ["John","docs/bot-platform/guide/whatsapp-api-documentation"]}' \
--data-urlencode 'message={"type":"document","document":{"link":"https://www.buildquickbots.com/whatsapp/media/sample/pdf/sample01.pdf","filename": "Sample funtional resume"}}'

Quick replies

For an approved interactive template like this:
You can now view your Account Balance or Mini statement for Account ending with {{1}} simply by selecting one of the options below. | [View Account Balance] | [View Mini Statement]
Where we have placeholder in message body and just postback button, the request will be:

curl --location --request POST 'http://api.gupshup.io/sm/api/v1/template/msg' \
--header 'apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'source=917834811114' \
--data-urlencode 'destination=918x98xx21x4' \
--data-urlencode 'template={"id": "c6aecef6-bcb0-4fb1-8100-28c094e3bc6b","params": ["12323XXXX"]}'

Miscellaneous APIs

Get Opt-in User list

This API will help you get a list of all the users interacted with your business phone number and their opt-in status:
Curl request

API Request

curl --location --request GET 'https://api.gupshup.io/sm/api/v1/users/{{App_Name}}' \
--header 'apikey: {{Gupshup_Account_APIKey}}'

API Response

{
  "status": "success",
  "users": [
    {
      "countryCode": "91",
      "lastMessageTimeStamp": 1585593959851,
      "optinSource": "URL",
      "optinStatus": "OPT_IN",
      "optinTimeStamp": 1585504095053,
      "phoneCode": "8x98xx21x4"
    }
  ]
}

Mark User Opt-in

API Request

curl --location --request POST 'https://api.gupshup.io/sm/api/v1/app/opt/in/{{App_Name}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'apikey: {{Gupshup_Account_APIKey}}' \
--data-urlencode 'user={{User_Mobile_Number}}'

User_Mobile_Number value is a valid phone number with country code. Example: 918x98xx21x4

API Response Code

202

Mark User Opt-out

API Request

curl --location --request POST 'https://api.gupshup.io/sm/api/v1/app/opt/out/{{App_Name}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'apikey: {{Gupshup_Account_APIKey}}' \
--data-urlencode 'user={{User_Mobile_Number}}'

User_Mobile_Number value is a valid phone number with country code. Example: 918x98xx21x4

API Response Code

202

Get Template list

Let us understand this API:

API Endpoint

https://api.gupshup.io/sm/api/v1/template/list/:AppName

Headers

API Request

curl --location --request GET 'https://api.gupshup.io/sm/api/v1/template/list/:AppName' \
--header 'apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a'

API Response
HTTP response code: 200

{
"status": "success",
"templates": [
  {
     "category": "ACCOUNT_UPDATE",
     "createdOn": 1580978917761,
     "data": "{{1}} debited with {{2}} on {{3}} for {{4}}.",
     "elementName": "common_transaction_2",
     "id": "05c82e91-05e5-4d35-b280-2d3d20feda38",
     "languageCode": "en_US",
     "languagePolicy": "deterministic",
     "master": false,
     "meta": "{\"example\":\"[Your Bank ac ending with 1245] debited with [Rs. 10000] on [11-Jan-2011] for [ATM cash withdrawal].\"}",
     "modifiedOn": 1581966008618,
     "status": "APPROVED",
     "templateType": "TEXT",
     "vertical": "TRANSACTIONS"
  },
  {
     "category": "ISSUE_RESOLUTION",
     "createdOn": 1593540550247,
     "data": "Hola! Soy {{1}} de Ofisí, recibimos una llamada suya, ¿en qué puedo ayudarle?",
     "elementName": "recibimos_llamada",
     "id": "072867eb-dd12-46f5-950d-2dd03a7677e5",
     "languageCode": "es_MX",
     "languagePolicy": "deterministic",
     "master": true,
     "meta": "{\"example\":\"Hola! Soy [Leon] de Ofisí, recibimos una llamada suya, ¿en qué puedo ayudarle?\"}",
     "modifiedOn": 1593627001825,
     "status": "APPROVED",
     "templateType": "TEXT",
     "vertical": "ISSUE RESOLUTION"
   }
 ]
}

Property id is the template id.

Check Wallet balance

API Request

curl --location --request GET 'https://api.gupshup.io/sm/api/v2/wallet/balance' \
--header 'apikey: {{Gupshup Account apikey}}'

API Response Code

200

API Response Body

{
    "balance": 1313.7675,
    "status": "success"
}