SMS is the simplest, easiest, and most commonly used communication channel for enterprises addressing consumers on a larger scale. Various industries, such as banking, finance, retail, healthcare, travel, and hospitality, use SMS to communicate with consumers. This guide shows how you can send a SMS using Gupshup APIs.
We will cover the following topics in this guide:
Inbound events/DLR events sent by operators for SMSs sent, will be sent to your Webhook i.e. If a SMS is successfully sent to the user, Gupshup registers the event and immediately sends a notification (HTTP POST request) to the Webhook specified in your application settings. Some important notes on Webhook:
If the callback URL is toggled OFF, you can see incoming messages under Inbound Messages | Events field. Messages and events logged under this field are stored temporarily, meaning if you refresh the page, the logs will be cleared.
Using Gupshup APIs you can send SMSs to permitted countries.
API request
curl --location --request POST 'http://api.gupshup.io/sms/v1/message/:appid' \
--header 'Authorization: api_key' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'destination=918XX9X33X59' \
--data-urlencode 'message=hi' \
--data-urlencode 'source=GSDSMS'
Request Headers
Content-type
|
application/json |
apikey
|
The unique identifier for a Gupshup account. |
Request Body
| key | Description | Example | Required |
|---|---|---|---|
|
|
The phone number on which the message is to be sent. |
441735481364 |
Yes |
|
|
The content of the message. |
Hi, your transaction is complete. |
Yes |
|
|
The sender ID associated with the approved template message. |
GSDSMS |
Required only for India. |
Path variables
| Key | Description | Example | Required |
|---|---|---|---|
|
|
The unique identifier for an app. |
|
Yes |
API Response
{
"status": "submitted",
"messageId": "888748c2-0049-4a2f-98d0-5f6967b9d9fd"
}
| Key | Description | Example |
|---|---|---|
|
|
The delivery status of the message. |
|
|
|
Unique identifier for a message. |
|
These events state the status of the messages sent. We will send notifications to inform you of the status of a message. When a message is sent, you will receive notifications for when the message is enqueued, sent, and delivered or failed. 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.
{
"destination": "5535121332829",
"messageId": "6a5a9990-80b3-4a2e-9d37-6442261095a9",
"ts": "1633074677239",
"status": "enqueued | sent | delivered | failed"
}
The payload object
| Key | Description | Example |
|---|---|---|
|
|
The phone number of the customer to whom the message was sent. The number is in E.164 format |
5535121332829 |
|
|
This is MessageId for tracking the status of the message |
|
|
|
The timestamp of the DLR event |
|
|
|
The DLR status of message. The status can be: |
|
Failure reasons and error codes
| Error code | Description |
|---|---|
| NOT_WHITELISTED_COUNTRY(8001) | The country you have selected is not currently activated |
| INSUFFICIENT_WALLET_BALANCE(8002) | You do not have sufficient funds to proceed |
| SENT_FAILED(8003) | Message sent failure |
| INVALID_PHONE_NUMBER(8004) | Please enter valid phone number |
| SERVER_ERROR(8005) | The server encountered an internal error and was unable to complete your request |
| USER_NOT_OPTED_IN(8006) | The entered phone number is not opted in |
| TEMPLATE_MATCHING_FAILED(8007) | The template Id does not match with the entered sender ID |
| INVALID_SENDER_ID(8008) | Please enter valid Sender ID |
| DISABLED_COUNTRY(8009) | The recipient country is in a disabled state, please view ?Application Settings? to enable it. |
| TEMPLATE_DISABLED(8010) | The selected template is in a disabled state |
| BAD_REQUEST(8011) | You have sent a request this server could not understand |
| NOT_FOUND(8012) | Template/Sender ID not found |
| HEADER_DISABLED(8013) | The selected Sender ID is in a disabled state |
| COUNTRY_NOT_FOUND(8014) | The selected country is currently not available |
For a sandbox app, the recipient's number must be whitelisted for the app before you can send a SMS message to them. Additionally, Gupshup provides 5 USD worth of free credits in the Gupshup wallet.
There are two ways in which you can whitelist a number.
Sender IDs are alphanumeric keywords you can use to send messages from. It can help the user identify your business. Sender ID formats vary by channel.
Currently sender IDs are only supported for India. For the remaining permitted countries: Brazil, Colombia, Mexico and Peru, User defined Sender IDs are not allowed, and are assigned depending on the country and the operators.
Businesses based in India can log in to their Airtel DLT account to import their approved Sender IDs and templates. To learn more about DLT registration, click here.
The degree of rules and regulations for SMS vary from country-to-country. Owing to the personal nature of SMS messages, it is highly regulated by government bodies all over the globe. Using Gupshup APIs you can send SMSs to users based in the following countries: Brazil, Mexico, Colombia, Peru & India.