WhatsApp Business API
Gupshup's WhatsApp Business API provides you APIs to send free form messages or session messages and template messages (utility/marketing/authentication) to users on WhatsApp. Both of these types of messages are together referred as 'Outbound Messages'
Here we will look at the different types of outbound messages you can send using Gupshup's API
Session messaging
You can send Session messages to Active users only. When a user sends a message to your WhatsApp Business API, they become an active user. A session starts from the latest user message. Sessions remain Active for 24 hours.
You can use our send message API for sending session messages
Send message API
The following guide will help you understand Gupshup's send message API. Using a single endpoint, you can send various messages to users on WhatsApp.
API Endpoint
Headers
| Header | Value |
|---|---|
| Content-Type | application/x-www-form-urlencoded |
| api_key | Your Gupshup account API key |
Request body
| Key | Type | Description | Example |
|---|---|---|---|
channel | string | The channel for sending messages. | |
source | string | For Live apps - Your registered WhatsApp Business API phone number. For Sandbox apps - Gupshup's sandbox/proxy number 917834811114 The number must be in E. 164 format. | 917834811114 |
src.name | string | The Gupshup app name registered against the phone number provided in the API. | DemoAPI |
destination | string | User's phone number. | 919876543210 |
message | object | The message object will change depending on the type of message. | Refer message object description |
disablePreview | Boolean | Optional This will enable/disable preview for media messages. | true |
encode | Boolean | Optional This flag is used for sending an emoji in an Interactive List message. If the list message consists of emojis, set the encode flag to 'true'. This flag will not affect any other type of message. | true |
API Response
Send message API requests received by our platform are processed asynchronously, and hence you will always get an HTTP_SUCCESS(200 to 299) response range if the API request made is correct. The API response includes an object with a Gupshup unique message identifier and status as submitted. Your callback URL/webhook will receive a message event stating the submitted message to the WhatsApp API client(which eventually sends the message to the customer) is enqueued or has failed.
| Header | Value |
|---|---|
| Content-Type | text/html |
{
"status":"submitted",
"messageId":"ee4a68a0-1203-4c85-8dc3-49d0b3226a35"
}
The Gupshup unique message identifier that is the messageId in the API response will help you track messages through the inbound message events - enqueued, failed, sent, delivered, and read that you obtain on your webhook/callback URL.
Template messaging
Template messages are Highly Structured(HSM)/ Notification messages. Once your WhatsApp Business API is Live, you can create template messages and submit them to WhatsApp for approval. You can send Template messages to users that you have opted-in. To know how you can opt-in users, read frequently asked questions.
API Endpoint
Headers
| Header | Value |
|---|---|
| Content-Type | application/x-www-form-urlencoded |
| Apikey | Your Gupshup account API key |
Request body
| Key | Type | Description | Sample |
|---|---|---|---|
source | string | Your registered WhatsApp Business API phone number. The number must be in E. 164 format. | 917834811114 |
destination | string | User's phone number. | 919876543210 |
template | object | See template object description | {"id": "c6aecef6-bcb0-4fb1-8100-28c094e3bc6b","params": ["Agent","Local Address","Tracking code"]} |
message | object | Required only if the template is of type Media - Image, Video, Document(.pdf) or location. See message object description | Image: {"type":"image","image":{"link":""}}Video: {"type":"video","video":{"link":""}}Document: {"type":"document","document":{"link":""}}Location: {"type":"location","location":{"longitude":"","latitude":""}} |
Template object description
| Key | Description | Sample |
|---|---|---|
id | Unique identifier for a template Use this API to get all template details for an app. | c6aecef6-bcb0-4fb1-8100-28c094e3bc6b |
params | Array of placeholders/variables in the template in the order of occurrence. | ["Agent","Local Address","Tracking code"] |
Message object description
| Key | Type | Description | Sample |
|---|---|---|---|
type | string | The type of media. Possible values are: image, video, document and location | image |
image, video, document, or location | object | This object has the link to the type of media file specified | {"link":"https://www.buildquickbots.com/whatsapp/media/sample/jpg/sample01.jpg"} |
API Response
Send message API requests received by our platform are processed asynchronously, and hence you will always get an HTTP_SUCCESS(200 to 299) response range if the API request made is correct. The API response includes an object with a Gupshup unique message identifier and status as submitted. Your callback URL/webhook will receive a message event stating the submitted message to the WhatsApp API client(which eventually sends the message to the customer) is enqueued or has failed.
| Header | Value |
|---|---|
| Content-Type | text/html |
{
"status":"submitted",
"messageId":"ee4a68a0-1203-4c85-8dc3-49d0b3226a35"
}
The Gupshup unique message identifier that is the messageId in the API response will help you track messages through the inbound message events - enqueued, failed, sent, delivered, and read that you obtain on your webhook/callback URL.
Sample requests
Following are sample API requests for each message type. These examples are for your reference only. You can create templates from settings in the app dashboard and submit them to WhatsApp for review.
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"]}'
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://www.buildquickbots.com/whatsapp/media/sample/jpg/sample01.jpg"}}'
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"}}'
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"}}'
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":""}}'
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"}}'
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"]}'
Let's have a look at the error codes for the above outbound message APIs:
| Error code | Description |
|---|---|
1001 - Last mapped bot and sender details mismatched | It occurs if your Access API app is not Live yet and you are using the sandbox mode to send a template message. To receive messages from your Access API app in sandbox mode, you must first send a WhatsApp message (proxy YourAppName) to the Gupshup proxy phone number (+917834811114). |
1002 - Number does not exist on WhatsApp | The phone number you sent the message to is not registered on WhatsApp. |
1003 - Unable to send message | Check your wallet balance | Message sending failed because of insufficient balance. |
1004 - Message sending failed as user is inactive for session message and template messaging is disabled. | You have disabled template messaging for your app, and the user is not active for a session. |
1005 - Message sending failed as user is inactive for session message and template did not match | The message is not a template message, and the user is not active for a session. |
1006 - Message sending failed as user is inactive for session message and not opted in for template message | The user is not opted-in, and the user is not active for a session. |
1007 - Message sending failed as user is inactive for session message, not opted in for template message and template did not match | The message is not a template message, the user is not opted-in and not active for a session. |
1008 - User is not Opted in and Inactive | The user is not opted-in and not active for a session. |
1010 - Invalid Media URL | It occurs if your Access API app is not Live yet and you are using the sandbox mode to send a message. A sandbox Access API app is limited and only supports sending media messages given here. |
1011 - Invalid Media Size | The size of the media file is not supported. |
For any other error code, click here.
Updated 11 months ago