Thundersms API (1.0.0)

Download OpenAPI specification:Download

This documentation provides clear instructions on how to integrate our API using different HTTP and JSON APIs.

We are here to assist you in configuring, accessing, and utilizing our API for our services.

Introduction

Our APIs are built using the REST standard, which enables you to effortlessly send messages to your end users, simplifying your work. With this feature, you can send alerts, reminders, notifications, and even verification messages containing one-time passcodes (OTP).

To integrate our API, you can use any HTTP recipient in any programming language of your choice.

API Endpoint

http://portal.thundersms.com/api/v2/

Note: Few elements in the endpoint may change from service to service.

Available HTTP methods

In our API, we utilize HTTP verbs to determine the action you wish to perform on an object. You can use (GET) to retrieve information, (DELETE) to remove an object, or (POST) to create a new one. In cases where your web application doesn’t support POST or DELETE directly, we offer an alternative method by allowing you to specify the desired action using the query parameter _method.

Products/Services

List of product names and product codes

Product Code Product Name
T Transactional SMS
P Promotional SMS
S TransScrub SMS
G Global SMS
VOC Voice Flow
WAP Whatsapp Messaging
RCS RCS Messaging
VBR Viber Messaging

Authentication

To authenticate your API requests, each request must include request headers with your access token.

If you don’t have an access token, you can find it in the menu bar under Developers -> API Keys/Access Tokens.

In case your application cannot send an authorization header, you can provide your access key using the GET parameter access_token.

Note: Your API keys carry significant privileges. It is crucial to keep them completely secure and refrain from sharing your secret API keys in publicly accessible places, such as GitHub.

On our platform, we offer incoming request whitelisting for our REST API. You can whitelist specific IP addresses when generating the access token.

CURL Example

$ curl {endpoint}auth/me \
-H 'Authorization: Bearer 38e896f55670311982434e929559xxxx' \
-H 'Accept: application/json'

GET Example

$ curl {endpoint}auth/me?access_token=38e896f55670311982434e92955xxxx \
-H 'Accept: application/json'

Note: If possible, please use the authorization header.

IP Addresses

Our API platform operates on a globally distributed infrastructure, which means you cannot whitelist the IP addresses of our platform. It’s important to note that delivery reports and inbound messages may originate from various IP addresses.

API Access Key Security

Your API access key serves as your authentication token for API usage, making it crucial to handle them securely. It is essential to treat your API access keys with the same level of care as your passwords. Ensure they are stored securely and never shared with anyone.

One common mistake is unintentionally exposing API keys by committing them to public repositories on platforms like GitHub. This can lead to fraudsters discovering and misusing your API access key, potentially sending spam messages or depleting your account balance. There are several techniques to mitigate this risk. Storing your API access key in an environment variable, passing it as a command-line argument, or utilizing a secrets manager can all help prevent accidental exposure. Remember, avoid hard-coding your API access key and refrain from checking it into public code repositories.

Similarly, be cautious when sharing code snippets on platforms such as PasteBin, GitHub Gists, or StackOverflow, as it can inadvertently expose your API access key. Ensure that both you and your developers are aware of this risk and take the necessary precautions.

Rate Limits

To keep you in compliance, we maintain the appropriate rate limits:

API Value
All GET requests are limited to 1000 requests per minute. Once this limit has been crossed, your requests will be rejected, accompanied by an HTTP 429 error code indicating 'Too Many Requests'.

You can contact our support team to increase the limit. Our team will increase the limit case by case.

Error Codes

We utilize standard HTTP status codes to indicate the outcome of an API request.

Code Description
2xx the request has been processed successfully.
4xx Error caused by the provided information. For example, authentication issues, insufficient balance, or missing or incorrect parameters.

If an error occurs, the response body will provide a JSON-formatted message that precisely identifies the issue at hand. This informative response will clearly indicate the nature of the error and provide relevant details.

Attributes

Name Value
status This represents the error type. OK or 200 is success and rest everything is failed.
code This represents the HTTP code. This value is optional. Not be available in all responses.
message A human-readable description of the error. You can provide your users with this information to indicate what they can do about the error.

HTTP Status Codes

Code Status Description
200 OK Everything went as planned.
202 Accepted Request accepted.
400 Bad Request Something in your header or request body was malformed.
401 Unauthorized Necessary credentials were either missing or invalid.
403 Forbidden Your credentials are valid, but you don’t have access to the requested resource.
404 Not Found The resources cannot be found.
409 Conflict You might be trying to update the same resource concurrently.
422 Unprocessable Content Validation error
429 Too Many Requests You are calling our APIs more frequently than we allow.
5xx Server issue Something went wrong on our end. Please try again.

Overview

In this chapter, developers will discover the powerful capabilities of webhooks within the CPaaS platform and learn how to integrate them effectively into their applications.

Webhooks

Webhooks are an extension of an API, but instead of your code requesting data from our API platform, Thundersms sends the data to you. The data arrives in a web request to your application. Webhooks are customizable HTTP callbacks that are defined by the user and triggered by specific events. When the designated trigger event takes place, the API client detects the event, gathers the relevant data, and promptly sends a notification (in the form of an HTTP request) to the Webhook URL specified in the application settings. This notification serves to update the status of sent messages or inform you when a new message is received.

Webhooks Workflow

When you configure a webhook, you specify a URL that Thundersms sends HTTP POST requests to and subscribe it to specific event types. When a Webhook is triggered, Thundersms sends information about the affected object to your application. For example, when an end user receives an email message, Thundersms can make a POST request to your Webhook endpoint to let you know about it.

Webhook Flow

Note: It is crucial to ensure that your Webhook returns an HTTPS 2xx OK response when receiving notifications. If the response is not received or does not meet the required criteria, the API client interprets it as a failed notification and attempts to resend it after a certain delay.

Retrying failed webhooks

If the Webhook fails to send a response with a 2xx status code, or if the remote app does not respond within 3 seconds, the package considers the call as failed. In such cases, we will make two additional attempts to send the Webhook call.

To avoid overwhelming the remote app, we introduced a delay between each retry attempt. By default, we wait 10 seconds between the first and second attempts, 100 seconds between the third and fourth attempts, 1000 seconds between the fourth and fifth attempts, and so on. The maximum wait time is set at 100,000 seconds, equivalent to approximately 27 hours. This ensures that we do not excessively burden the remote app while allowing for reasonable retry intervals.

Signature

If you wish to have your callbacks signed and have made the proper configuration for this, the callbacks will have the following signature-related headers:

Name Description
Signature The signature generated by the system with the Webhook ID as a secret

Webhook

View All Webhooks

This endpoint sends an HTTP GET request to retrieve a list of webhooks for the specified endpoint. The response will include details of the webhooks available.

Note:

  • Kindly replace the token with your respective access_token.
  • Few elements in the endpoint may change from service to service.
Authorizations:
bearerAuth
query Parameters
filter[name]
string
Example: filter[name]={{webhook_id}}

Name of the Webhook to be retrieved.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "OK",
  • "meta": {
    },
  • "status": "OK"
}

Create Webhook

This endpoint allows you to create a new Webhook by sending an HTTP POST request.

Note:

  • If you are thinking of passing a Webhook ID in each request, an alternative approach is to create a subscription for that particular event. Refer to Create Subscription
  • Few elements in the endpoint may change from service to service.
Authorizations:
bearerAuth
Request Body schema: application/json
name
required
string

Enter the name of the Webhook that you want to create.

secret
string

Enter the secret key for the Webhook that you received as a secret.

status
number
Enum: "1" "0"

The status of the Webhook (0 for inactive, 1 for active)

token
string

Verification token for the initial Webhook verification challenge.

uri
required
string <url>

The URL of the server that will receive the Webhook POST request.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Created Successfully",
  • "status": "OK"
}

View Webhook by ID

This endpoint retrieves the details of a specific Webhook by its ID. The response will include the webhook's ID, name, URI, secret, verification code, status, creation timestamp, and last update timestamp.

Note:

  • Replace the {id} in the endpoint with the actual ID of the Webhook you want to see.
  • Few elements in the endpoint may change from service to service.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{webhook_Id}}

ID of the Webhook.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "OK",
  • "status": "OK"
}

Update Webhook

This endpoint allows you to update a specific Webhook by providing the Webhook ID in the URL path and the updated name and URI in the request body.

Note:

  • Few elements in the endpoint may change from service to service.
  • Replace the {id} in the endpoint with the actual ID of the Webhook you want to update.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{webhook_Id}}

ID of the Webhook.

Request Body schema: application/json
name
required
string

Enter the name of the Webhook that you want to modify.

uri
required
string

The URL of the server that will receive the Webhook POST request.

status
number
Enum: "1" "0"

The status of the Webhook (0 for inactive, 1 for active)

secret
string

Enter the secret key for the Webhook that you received as a secret.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Updated Successfully",
  • "status": "OK"
}

Delete Webhook

This endpoint is used to delete a specific Webhook by its ID.

A Webhook can go through a soft deletion process, during which its status is updated to inactive. Once the Webhook is restored, its status is then changed to active within the application.

Note: Replace the {id} in the endpoint with the actual ID of the Webhook you want to delete.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{webhook_Id}}

ID of the Webhook.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "message": "Deleted Successfully",
  • "status": "OK"
}

Subscription

You should subscribe to the events to get the payload of a sent or received message or call to the client’s specified Webhook URL.

Here is a list of events that can be used to send a payload to the provided Webhook URL.

Product Event Description
SMS sms:message:status Acknowledgement of message delivery or undelivery.
SMS sms:unsubscription Acknowledgement of opting out from any number.
Whatsapp whatsapp:message:in For receiving updates when the user sends a message to WhatsApp number
Whatsapp whatsapp:message:status For receiving DLR status from the WhatsApp number to the user
Whatsapp whatsapp:unsubscription Acknowledgement of opting out from any number.
RCS rcs:message:in For receiving RCS message event
RCS rcs:message:status For receiving RCS delivery updates
RCS rcs:unsubscription Acknowledgement of opting out from any number.
Voice voice:message:out To receive acknowledgements after CDR events.
Voice voice:unsubscription Acknowledgement of opting out from any number.
Viber viber:message:status To receive Viber delivery updates.
Viber viber:message:in To receive notifications when a user sends a message to the Viber number.
Viber viber:unsubscription Acknowledgement of opting out of any number.
Interact vmn:message:in Once we receive the acknowledgment, we will send the same to the webhook.
Contact contacts:subscriber:subscription For receiving contact creation and updating the event payload.

List All Subscriptions

This API endpoint makes an HTTP GET request to retrieve a list of subscriptions for Webhook.

Note:

  • Few elements in the endpoint may change from service to service.
  • Kindly replace the token with your respective access_token.
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "Subscriptions List",
  • "meta": {
    },
  • "status": "OK"
}

Create Subscription

This API endpoint allows you to create subscriptions by sending an HTTP POST request to the specified URL. The request should include the event, identity, and webhook_id in the payload.

Note:

  • Before creating subscription, please make sure you have already created Webhook, refer to Create Webhook.
  • Few elements in the endpoint may change from service to service.
Authorizations:
bearerAuth
Request Body schema: application/json
event
required
string

Type of event you subscribe to. Refer to All Events

identity
required
string

The identity associated with the subscription.

webhook_id
required
string

The ID of the Webhook for the subscription.

Responses

Request samples

Content type
application/json
Example
{
  • "event": "vmn:message:in",
  • "identity": "all",
  • "webhook_id": "{{webhook_Id}}"
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Subscription Saved Successfully",
  • "status": "OK"
}

View Subscription by ID

This endpoint retrieves subscription details for a specific ID. It makes an HTTP GET request to the specified endpoint.

Note:

  • Few elements in the endpoint may change from service to service.
  • Replace the id with the actual ID of the Webhook that you would like to see.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{Subscription_id}}

ID of the subscription.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Subscription",
  • "status": "OK"
}

Delete Subscription

This endpoint sends an HTTP DELETE request to delete a specific subscription.

Note: Replace the id with the actual ID of the Webhook that you would like to delete.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{Subscription_id}}

ID of the subscription.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "message": "Subscription Deleted Successfully",
  • "status": "OK"
}

Example Webhook Request to Your Server

This section describes the example Webhook request sent to your server or the payload generated after the triggering of events for SMS, WhatsApp, RCS, voice, interact, and contact.

The DLR Push API allows the delivery report of a sent message to be sent to the client’s specified Webhook URL using the POST method. You can create the Webhook URL by following the instructions below:

  • Navigate to the Webhooks section and create a new Webhook, refer to Create Webhook.
  • After creation, you will receive an id for the newly created Webhook.

SMS Example Request

This is an example Webhook request for an SMS, sent as an HTTP notification to the specified Webhook URL in the application settings.

Note:

  • The endpoint displayed in this documentation is an example endpoint. The actual endpoint will be the Webhook URL specified during the creation of the webhook.
  • The response and status of the Webhook request sent can be found in the webhooks logs section of the Thundersms website.
  • To request delivery reports, include the webhook_id parameter and its corresponding value in your API Request. Once the request is made, you will receive the delivery report.
  • You can only create a customized Webhook for event sms:message:status (message status notification).
Authorizations:
bearerAuth
Request Body schema: application/json
event
string

Specifies the specific event type. Choose the event type.

object

Contains detailed information about the event sms:message:status

Responses

Request samples

Content type
application/json
Example
{
  • "event": "sms:message:status",
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "status": "OK",
  • "code": 200,
  • "message": "Scheduled successfully.",
  • "data": [ ]
}

WhatsApp Example Request

This is an example Webhook request for an WhatsApp, sent as an HTTP notification to the specified Webhook URL in the application settings.

Note:

  • The endpoint displayed in this documentation is an example endpoint. The actual endpoint will be the Webhook URL specified during the creation of the webhook.
  • The response and status of the Webhook request sent can be found in the webhooks logs section of the Thundersms website.
  • You can only create a customized Webhook for event whatsapp:message:status (message status notification).
Authorizations:
bearerAuth
Request Body schema: application/json
event
string

Specifies the specific event type. Choose the event type.

object

Contains detailed information about the event whatsapp:message:status

Responses

Request samples

Content type
application/json
Example
{
  • "event": "whatsapp:message:status",
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "status": "OK",
  • "code": 200,
  • "message": "Scheduled successfully.",
  • "data": [ ]
}

RCS Example Request

This is an example Webhook request for an RCS, sent as an HTTP notification to the specified Webhook URL in the application settings.

Note:

  • The endpoint displayed in this documentation is an example endpoint. The actual endpoint will be the Webhook URL specified during the creation of the webhook.
  • The response and status of the Webhook request sent can be found in the webhooks logs section of the Thundersms website.
  • You can only create a customized Webhook for event rcs:message:status (message status notification).
Authorizations:
bearerAuth
Request Body schema: application/json
event
string

Specifies the specific event type. Choose the event type.

object

Contains detailed information about the event rcs:message:status

Responses

Request samples

Content type
application/json
Example
{
  • "event": "rcs:message:status",
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "status": "OK",
  • "code": 200,
  • "message": "Scheduled successfully.",
  • "data": [ ]
}

Engage Example Request

This is an example Webhook request for an Engage (voice), sent as an HTTP notification to the specified Webhook URL in the application settings.

Note:

  • The endpoint displayed in this documentation is an example endpoint. The actual endpoint will be the Webhook URL specified during the creation of the webhook.
  • The response and status of the Webhook request sent can be found in the webhooks logs section of the Thundersms website.
  • To request delivery reports, include the webhook_id parameter and its corresponding value when making a call through API Request. Once the request is made, you will receive the delivery report.
  • You can only create a customized Webhook for event voice:message:out (call status notification).
Authorizations:
bearerAuth
Request Body schema: application/json
event
string

Specifies the specific event type. Choose the event type.

object

Contains detailed information about the event voice:message:out

Responses

Request samples

Content type
application/json
Example
{
  • "event": "voice:message:out",
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "status": "OK",
  • "code": 200,
  • "message": "Scheduled successfully.",
  • "data": [ ]
}

Viber Example Request

This is an example Webhook request for an Viber, sent as an HTTP notification to the specified Webhook URL in the application settings.

Note:

  • The endpoint displayed in this documentation is an example endpoint. The actual endpoint will be the Webhook URL specified during the creation of the webhook.
  • The response and status of the Webhook request sent can be found in the webhooks logs section of the Thundersms website.
  • You can only create a customized Webhook for event viber:message:status (message status notification).
Authorizations:
bearerAuth
Request Body schema: application/json
event
string

Specifies the specific event type. Choose the event type.

object

Contains detailed information about the event viber:message:status

Responses

Request samples

Content type
application/json
Example
{
  • "event": "viber:message:status",
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "status": "OK",
  • "code": 200,
  • "message": "Scheduled successfully.",
  • "data": [ ]
}

Contact Example Request

This is an example Webhook request for an contact, sent as an HTTP notification to the specified Webhook URL in the application settings.

Note:

  • The endpoint displayed in this documentation is an example endpoint. The actual endpoint will be the Webhook URL specified during the creation of the webhook.
  • The response and status of the Webhook request sent can be found in the webhooks logs section of the Thundersms website.
Authorizations:
bearerAuth
Request Body schema: application/json
event
string
Value: "contacts:subscriber:subscription"

Specifies the specific event type.

object

Contains detailed information about the event contacts:subscriber:subscription

Responses

Request samples

Content type
application/json
{
  • "event": "contacts:subscriber:subscription",
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "status": "OK",
  • "code": 200,
  • "message": "Scheduled successfully.",
  • "data": [ ]
}

Interact Example Request

This is an example Webhook request for an interact, sent as an HTTP notification to the specified Webhook URL in the application settings.

Note:

  • The endpoint displayed in this documentation is an example endpoint. The actual endpoint will be the Webhook URL specified during the creation of the webhook.
  • The response and status of the Webhook request sent can be found in the webhooks logs section of the Thundersms website.
Authorizations:
bearerAuth
Request Body schema: application/json
event
string
Value: "vmn:message:in"

Specifies the specific event type.

object

Contains detailed information about the event vmn:message:in

Responses

Request samples

Content type
application/json
{
  • "event": "vmn:message:in",
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "status": "OK",
  • "code": 200,
  • "message": "Scheduled successfully.",
  • "data": [ ]
}

Smart Link Example Request

This is an example Webhook request for an smart link, sent as an HTTP notification to the specified Webhook URL in the application settings.

Note:

  • The endpoint displayed in this documentation is an example endpoint. The actual endpoint will be the Webhook URL specified during the creation of the webhook.
  • The response and status of the Webhook request sent can be found in the webhooks logs section of the Thundersms website.
Authorizations:
bearerAuth
Request Body schema: application/json
id
string

Unique identifier for the entry in the system.

link_id
number

An identifier associated with a specific link.

user_agent
string

Information about the user's browser or client application.

browser
string

The name of the user's web browser.

browser_version
string

The version number of the user's web browser.

platform
string

The operating system or platform on which the user is accessing the service.

device_type
string

The type of device used by the user.

device_brand
string

The brand or manufacturer of the user's device.

country
string

The country from which the request originates.

country_code
string

The country code associated with the country from which the request originates.

region
string

The region or state within the country from which the request originates.

city
string

The city from which the request originates.

mobile
string

The mobile phone number associated with the user.

created_at
string <yyyy-mm-dd H:i:s>

The date and time at which the entry was created or recorded in the system.

Responses

Request samples

Content type
application/json
{
  • "id": "b34e35ad-fe34-4a8b-977c-b21cd76cd7d6:1",
  • "link_id": 246,
  • "user_agent": "Mozilla/5.0)",
  • "browser": "Goole Chorme",
  • "browser_version": "23.3.1",
  • "platform": "Android",
  • "device_type": "smartphone",
  • "device_brand": "Redmi",
  • "country": "india",
  • "country_code": "IN",
  • "region": "Karnataka",
  • "city": "Bangalore",
  • "mobile": "9189195XXXXX",
  • "created_at": "2021-04-09 16:27:39"
}

Response samples

Content type
application/json
{
  • "status": "OK",
  • "code": 200,
  • "message": "Scheduled successfully.",
  • "data": [ ]
}

Compose Customized Webhook

For users seeking enhanced customization, Compose Webhook will help to receive the customized Webhook payload to precisely match your preferences and requirements.

Follow the below procedure to create customized Webhooks using the CPaaS Dashboard.

  1. Login to the CPaaS portal.

  2. Navigate to the Webhooks section of your application and click Create.

  3. Select the Customized Webhook.

  4. Enter the identification name in the TITLE field.

  5. Enter a callback URL into the designated URL field.

    Note:

    • The composed payload will be sent to this callback URL.
    • You can pass the replaced variables within the URL.
  https://www.domain.com/ack/receive?id={{id}}&mobile={{mobile}}&status={{status}}  
  https://www.domain.com/ack/receive?message_id={{id}}&mobile_number={{mobile}}&message_status={{status}}
  1. Choose the HTTP method for the Webhook request from the methods dropdown. By default, the GET method is selected.

  2. Add the required parameters and their values in the params tab by clicking the + icon.

    Note:

    • The available parameters are explained in Example Webhook Request to Your Server.
    • You have the flexibility to name the keys as you wish, but it's important that the values correspond to the replaced variables.
  3. Add the required headers and their values in the Headers tab by clicking the + icon. For example, authorization headers or custom headers.

  4. Choose between raw or form-data for the payload and add the keys and their values in the Body tab by clicking the + icon.

  5. Enter the receiver in the RECEIVER field only when creating the Webengage Webhook.

  6. Click Create.

Note:

  • After creation, you will receive an id for the newly created Webhook.
  • To request delivery reports for the SMS and Engage packages, ensure to include the parameter webhook_id along with its corresponding value in your API request.
  • Once you make the request, you will receive the delivery report as configured. For an example payload or the sample webhook request sent to your server, refer to Example Webhook Request to Your Server.
  • You can only create a customized Webhook for the below events:
Event Description
sms:message:status Message status notification
whatsapp:message:status Message status notification
rcs:message:status Message status notification
voice:message:out Call status notification
viber:message:status Message status notification

Token

Generate

This API endpoint is used to generate an access token. When a GET request is sent to the specified endpoint, the server will respond with the generated access token in the response body.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczovL2V1LmNwYWFzLXVhdC5iaWNzLmNvbS9hcGkvdjMvYXV0aC90b2tlbi9nZW5lcmF0ZSIsImlhdCI6MTY2ODc1Mzg0NiwiZXhwIjoxNjY4NzU3NDQ2LCJuYmYiOjE2Njg3NTM4NDYsImp0aSI6ImM0S012TWlzd08xZDVGQjIiLCJzdWIiOiIxMCIsInBydiI6IjIzYmQ1Yzg5NDlmNjAwYWRiMzllNzAxYzQwMDg3MmRiN2E1OTc2ZjcifQ.h4DQ6IQJTH5mNQFs0U5zy-e6WS2pGgSn36KIm4jeaRDkXs44m79E50s3S2FxZiBW0xjSEh7so6KOCrYHICQCA_ogeBq13gqiTqmgEykFuFIoxV_NI6B3Ap1oy6g9YaTa6jYH5lrylM72V4tg_YjG5mIH2Kw80HAva9LlYz76igUskPJ-nhWf6Fdx2MZZ1BYoLj1aVZaepbyvftfHXnqDBGGkEm_KcREszFyZYjEVwrkgZHmL2okVMQMhEzySEwrH2BdQ55vu36snEb_ck7qkfJLq2n9AL2rf1kBvr2FC90e_Pk8sJFOFYzQ0MZ1zaAmvBnVnODw0xE9mkJuehI7B4VvEfW_BK64TKgVkzUyRk0yKudHG26jDqfHCYojy8A1sPgfBPeZIbbE43-svOslHPoDlNTgM8HYNEd7hExkpZQaPPbYpnqlgdeBtDGGrx2hY03W-nDBT6W8tnGmgCYpolW6H1I13LI7NlaSnKkQ1aQp99DFDafN43s3SEtH-A30oekfq1WguawVRbOVmmcosECD_Bs0bJOLJSPYuMique8QdQ6372u9O6zT89X0RxwDoWvzPL35ZwLTel1zIvkGHLW1BPa34XtjtvrWUzcGIBeGd2U0N0TTEC70ukbNRYDaKaUVmqo_qhgfndx4PilIk4ppqCJAqHejBcDCENAbjtDI",
  • "expires_in": 3600,
  • "token_type": "bearer"
}

Refresh

This endpoint is used to refresh the access token. When the access token is about to expire, you can make a request to this endpoint to obtain a new token without having to re-authenticate.

The request does not require any parameters in the body or URL, as the token to be refreshed is typically included in the request headers.

The response will include the new access token along with its expiration time, allowing you to update your token and continue making authenticated requests.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczovL2V1LmNwYWFzLXVhdC5iaWNzLmNvbS9hcGkvdjMvYXV0aC90b2tlbi9yZWZyZXNoIiwiaWF0IjoxNjY4NzUzOTAwLCJleHAiOjE2Njg3NTc1MDYsIm5iZiI6MTY2ODc1MzkwNiwianRpIjoicEhTTFRVUGNGVmJGaTd0eiIsInN1YiI6IjEwIiwicHJ2IjoiMjNiZDVjODk0OWY2MDBhZGIzOWU3MDFjNDAwODcyZGI3YTU5NzZmNyJ9.eeUP1edl2XgGJcarOZzeOCpidoS8Y6g2pMsD35P8EA3MvpNf1Cu-3TGtkh_qNxAvizMwrbR_nGW51ffN75U77WClaBFV3kTrRFaveOpGZAceCMVkhO6dbJQbaio_cHaAgS9m_-CtswuCDH4-sMdHVa60hR9S4y4I6f6QEW5StMu_DXHF4d_PRSoy_9IEj0yjuVXI8B17V3XRy2nvXBIDr-XpAgQLEn82xt5_3MZRa_COpNAhDkHVVdjS8r2Oun8OS7aCGtwe2QdzlD8Uib-E0OXwZ8OtzHTeaYADZZcUzwAV98LhbrTfjPv_jLeoxpue2Q_yZyb9L3Mgzo1K-zlsgFprq0xMU9_UqSA2G-1kVIsRFqzozTDBWp04u0GEd6nEgmtHQ_6tI8M4DThA5Olr2LsQIqZtZ28XJE4KIDam1VCAyBN_uLj70NdduufeJNrEiFvJkim4TM3tQ1ynSNGaXQ6Fd6K_ME_HLq6yUK8ZuD2IHKT6HecTwzXYjqsIf6d8YpBLoNFELQLODzRHArKNh2cFw0nma8smSTqioubuLBOKzl_D9ok9BukUfjGpJLrZlDcHuoJAxhIF1EG5vaELpIzA2QJSZGQ2LVkzrjD2mauKkJuFjHAdcP-avUvSLgcqb25f-C-3oA8_xOSqoCx7sHftw0BsjUesnpOQOnhT8NU",
  • "expires_in": 3600,
  • "token_type": "bearer"
}

Overview

Our Short Message Service (SMS) API provides a convenient way to send text messages to users worldwide using straightforward RESTful APIs.

Key features of our SMS API include:

  • Programmatically send and receive a high volume of SMS messages globally.
  • Seamlessly integrate with the web technologies you already use, allowing your apps to scale effortlessly.
  • Experience low latency and high delivery rates when sending SMS.
  • Receive SMS for free using SMS-enabled local numbers available in various countries.
  • Pay only for the SMS messages you send, without any additional charges.

With our SMS API, you can efficiently reach your users through text messages, leveraging the benefits of global coverage, reliability, and cost-effectiveness.

Available HTTP Methods

Our API relies on HTTP verbs to determine the desired action for an object: reading (GET), deleting (DELETE), or creating (POST). In cases where your web application lacks support for POST or DELETE operations, we offer a solution. You can specify the desired method by including the query parameter _method.

Number Format

Numbers are a key concept to understand when working with the API. The following points should be considered before developing your application:

All phone numbers in the APIs use the E.164 format. This means that the numbers:

  • Omit both a leading + and the international access code, such as 00.
  • Contain no special characters, such as a space, (), or -.

For example, a US number would have the format 14155550101. A UK number would have the format 447700900123.

Sender ID

Every text message sent through our API is associated with a sender ID. When utilizing the API to send a text message, you have the option to use any of the approved sender IDs associated with your account.

If you haven’t created a sender ID yet, don’t worry! You can easily create one within our application. Once your Sender ID is approved, you can immediately begin sending messages using it.

Message Templates

Message templates are message formats for common reusable messages a business may want to send. Businesses must use message templates for sending notifications to customers.

SMS Length Summary

You should be mindful of the character limit and consider the following limitations to optimize your SMS.

Standard GSM Characters

No.of SMS No.of Characters
1 160 characters
2 (2 x 153) 306 characters
3 (3 x 153) 459 characters

Unicode Characters

No.of SMS No.of Characters
1 70 characters
2 (2 x 67) 134 characters
3 (3 x 67) 201 characters

Note: If any characters other than the following special characters are present in the message during the sending of a campaign type normal, they will be replaced with a question mark (?):

  • Whitespace characters
  • Alphanumeric characters (a-z, A-Z, 0-9)
  • Specific special characters: @ £ $ € ¥ è é ù ì ò Ç Ø ø Å å ? _ F Æ æ ß É ! “ # ¤ % & ’ ( ) * + , - . / : ; < = > ? ¡ ? Ö Ñ Ü § ¿ ö ñ ü à ä Ä \ { } ~ [ ]

Sender

View All Senders

This endpoint makes an HTTP GET request to retrieve a list of SMS senders. The response will include a list of SMS senders, each containing details such as sender ID, name, and status.

Note:

  • Kindly replace the token with your respective access_token and other parameters.
  • Few elements in the endpoint may change from service to service.

Status Description

Status Value Description
0 Pending
1 Approved
2 Rejected
Authorizations:
bearerAuth
query Parameters
filter[name]
string
Example: filter[name]={{sender_id}}

Name of the sender ID.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "Senders List",
  • "meta": {
    },
  • "status": "OK"
}

Create Sender

This endpoint allows you to create a new sender ID using the post method under your account.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth
Request Body schema: application/json
country_code
required
string

Enter the sender's country code in two letters.

entity_id
required
string

Enter the entity ID.

entity_name
required
string

Name of the company to which this sender belongs.

name
required
string

Enter the sender ID that you want to create.

service
required
string

The short code of the service name. Refer to Products/Services.

Responses

Request samples

Content type
application/json
{
  • "country_code": "IN",
  • "entity_id": "123233434355345555",
  • "entity_name": "SAMPLE COMPANY",
  • "name": "SEM{{random}}",
  • "service": "ENT"
}

Response samples

Content type
application/json
Example
{
  • "code": 200,
  • "data": {
    },
  • "message": "Sender Saved Successfully",
  • "status": "OK"
}

View Sender by ID

This endpoint makes an HTTP GET request to retrieve the details of a specific SMS sender by ID. The response will include the sender's ID, name, service details, entity name and ID, ISO country code, open status, purpose, status, creation timestamp, and last update timestamp.

Note:

  • Few elements in the endpoint may change from service to service.
  • Kindly replace the token with your respective access_token.
  • Replace the {id} in the endpoint with the actual ID of the sender you want to see.

Status Description

Status Value Description
0 Pending
1 Approved
2 Rejected
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{sender_id}}

Name of the sender ID.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Sender Data",
  • "status": "OK"
}

Edit Sender

This endpoint allows you to update a specific sender ID using the put method under your account.

Note:

  • Few elements in the endpoint may change from service to service.
  • Replace the {id} in the endpoint with the actual ID of the sender you want to edit.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{sender_id}}

Name of the sender ID.

Request Body schema: application/json
country_code
string

Enter the sender's country code in two letters.

entity_id
string

Enter the entity ID.

entity_name
string

Name of the company to which this sender belongs.

service
string

The short code of the service name. Refer to Products/Services

Responses

Request samples

Content type
application/json
{
  • "country_code": "IN",
  • "entity_id": "12345679",
  • "entity_name": "testing",
  • "service": "ENT"
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Sender Updated Successfully",
  • "status": "OK"
}

Delete Sender

This endpoint is used to delete a specific sender for SMS messages by making an HTTP DELETE request under your account.

Note:

  • Replace the {id} in the endpoint with the actual ID of the sender you want to delete.
  • Few elements in the endpoint may change from service to service.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{sender_id}}

Name of the sender ID.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "message": "Deleted Successfully",
  • "status": "OK"
}

Template

View All Templates

This endpoint makes an HTTP GET request to retrieve a list of SMS templates created under your account. The response will include information about the SMS templates, such as their names, IDs, and other relevant details.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth
query Parameters
filter[name]
string
Example: filter[name]={{template_id}}

Name of the template.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "Templates List",
  • "meta": {
    },
  • "status": "OK"
}

Create Template

This endpoint allows you to create a new SMS template by sending an HTTP POST request under your account.

Note: Few elements in the endpoint may change from service to service.

Template Types

Template Type Description
T Transactional
P Promotional
SI Service Implicit
SE Service Explicit
Authorizations:
bearerAuth
Request Body schema: application/json
body
required
string

Enter the body of the SMS (template).

name
required
string

Enter the name of the template that you want to refer to.

sender
required
string

Enter the approved sender ID associated with your account.

template_id
required
string

DLT Template ID.

type
required
string
Enum: "T" "P" "SI" "SE"

Type of the template

Responses

Request samples

Content type
application/json
{
  • "body": "testing sms 1",
  • "name": "test1",
  • "sender": "{{sender_name}}",
  • "template_id": "{{random}}",
  • "type": "T"
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Template Saved Successfully",
  • "status": "OK"
}

View Template by ID

This endpoint makes an HTTP GET request to retrieve details of a specific SMS template by its ID. The response will include the template's ID, sender ID, template type, sender, name, alias, body, body length, creation and update timestamps, and other relevant details.

Note:

  • Kindly replace the token with your respective access_token.
  • Few elements in the endpoint may change from service to service.
  • Replace the {id} in the endpoint with the actual ID of the template you want to see.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{template_id}}

Name of the template.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Template Data",
  • "status": "OK"
}

Edit Template

This endpoint allows you to update an existing SMS template by sending an HTTP PUT request under your account.

Note:

  • Replace the {id} in the endpoint with the actual ID of the template you want to edit.
  • Few elements in the endpoint may change from service to service.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{template_id}}

Name of the template.

Request Body schema: application/json
body
string

Enter the body of the SMS (template).

is_english
string
Enum: "1" "0"

Indicates whether the template is in English.

name
string

Enter the name of the template that you want to refer to.

template_id
required
string

DLT Template ID.

type
string
Enum: "P" "T" "SI" "SE"

The type of template.

Responses

Request samples

Content type
application/json
{
  • "body": "temp12",
  • "is_english": "1",
  • "name": "SENDER",
  • "template_id": "Welcome to Thundersms family",
  • "type": "T"
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Template Updated Successfully",
  • "status": "OK"
}

Delete Template

This endpoint sends an HTTP DELETE request to delete an SMS template by its ID under your account.

Note:

  • Replace the {id} in the endpoint with the actual ID of the template you want to delete.
  • Few elements in the endpoint may change from service to service.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{template_id}}

Name of the template.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": 1,
  • "message": "Template deleted successfully",
  • "status": "OK"
}

Unsubscriber

View All Unsubscribers

This endpoint makes an HTTP GET request to retrieve a list of unsubscribers from the SMS suppressions. The response will contain the details of the unsubscribed phone numbers.

Note:

  • Kindly replace the token with your respective access_token and other parameters.
  • Few elements in the endpoint may change from service to service.
Authorizations:
bearerAuth
query Parameters
filter[id]
string

The SMS unsubscription ID.

filter[iso]
string

The ISO code of the country. (e.g., IN, AF, etc.)

filter[receiver]
string

The unsubscribed mobile number.

filter[type]
string
Enum: "tag" "sender" "service"

Type of unsubscription

filter[value]
string

Value for any of the given type.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "Unsubscribers list",
  • "meta": {
    },
  • "status": "OK"
}

Create Unsubscriber

This endpoint allows you to add an unsubscriber to the list of unsubscribers for SMS communications.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth
Request Body schema: application/json
receiver
required
string

Enter the receiver that you want to add.

type
string
Enum: "tag" "product" "sender" "all"

Type of the receiver

value
string

Enter the value of the type.

Responses

Request samples

Content type
application/json
{
  • "receiver": "9176xxxxxxxx",
  • "type": "tag",
  • "value": "tag1"
}

Response samples

Content type
application/json
Example
{
  • "code": 200,
  • "data": {
    },
  • "message": "Receiver added successfully",
  • "status": "OK"
}

Clean Unsubscribers

This HTTP DELETE request is used to remove all unsubscribers from the SMS suppression list.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "message": "Deleted Successfully",
  • "status": "OK"
}

View Unsubscriber by ID

This endpoint retrieves information about a specific SMS unsubscriber by ID. The response will include details such as the ID, ISO country code, receiver number, type, value, and the creation timestamp of the unsubscriber.

Note:

  • Kindly replace the token with your respective access_token.
  • Few elements in the endpoint may change from service to service.
  • Replace the {id} in the endpoint with the actual ID of the unsubscriber you want to see.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{sms_optout_id}}

The SMS unsubscription ID.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Unsubscribers data",
  • "status": "OK"
}

Edit Unsubscriber

This endpoint allows you to update the details of an unsubscriber by making an HTTP PUT request to the specified endpoint.

Note:

  • Few elements in the endpoint may change from service to service.
  • Replace the {id} in the endpoint with the actual ID of the unsubscriber you want to edit.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{sms_optout_id}}

The SMS unsubscription ID.

Request Body schema: application/json
receiver
required
string

Enter the receiver that you want to edit.

type
string
Enum: "tag" "product" "sender" "all"

Type of the receiver

value
string

Enter the value of the type.

Responses

Request samples

Content type
application/json
{
  • "receiver": "9176xxxxxxxx",
  • "type": "tag",
  • "value": ""
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Receiver update successfully",
  • "status": "OK"
}

Delete Unsubscriber

This API endpoint sends an HTTP DELETE request to remove a specific unsubscriber from the list of SMS suppressions.

Note:

  • Replace the {id} in the endpoint with the actual ID of the unsubscriber you want to delete.
  • Few elements in the endpoint may change from service to service.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{sms_optout_id}}

The SMS unsubscription ID.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "message": "Deleted Successfully",
  • "status": "OK"
}

Import Unsubscriber

This API endpoint allows you to import unsubscribers for SMS suppression by uploading a file.

Note: Few elements in the endpoint may change from service to service.

Request Parameter

Parameter Description Limit Required
file File containing unsubscriber numbers. (Supported file types: txt, csv, xls, xlsx) 100 MB Yes
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "message": "Receivers accepted for import",
  • "status": "OK"
}

Blocked Templates

View Blocked Templates List

This endpoint makes an HTTP GET request to retrieve a list of blocked templates for SMS suppression. The response will include the status, code, message, and data (an array of block templates). The meta section provides information about the current page and the total count.

Note:

  • Kindly replace the token with your respective access_token and other parameters.
  • Few elements in the endpoint may change from service to service.
Authorizations:
bearerAuth
query Parameters
filter[id]
string

ID of the blocked template.

filter[template_id]
string

ID of the template added to the blocked list.

filter[status]
number
Enum: "0" "1"

Status of the blocked template.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "Block templates list",
  • "meta": {
    },
  • "status": "OK"
}

Create Block Template

This endpoint allows you to add a new block template by making an HTTP POST request.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth
Request Body schema: application/json
status
string
Enum: "1" "0"

Enter the status of the template.

template_id
required
string

Enter the ID of the template to be added to the blocked list.

Responses

Request samples

Content type
application/json
{
  • "status": "9",
  • "template_id": "{{block_template_id}}"
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Block template added successfully",
  • "status": "OK"
}

Clean Blocked Templates

This HTTP DELETE request is used to delete all blocked templates at once.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "message": "Deleted Successfully",
  • "status": "OK"
}

View Blocked Template by ID

This endpoint makes an HTTP GET request to retrieve blocked template data for a specific template ID. The response will include the ID of the template, the template ID, and the status of the template.

Note:

  • Kindly replace the token with your respective access_token.
  • Few elements in the endpoint may change from service to service.
  • Replace the {id} in the endpoint with the actual ID of the blocked template you want to see.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{created_block_template_id}}

ID of the blocked template.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Block template data",
  • "status": "OK"
}

Edit Blocked Template

This endpoint allows you to update a specific blocked template using an HTTP PUT request.

Note:

  • Replace the {id} in the endpoint with the actual ID of the blocked template you want to edit.
  • Few elements in the endpoint may change from service to service.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{created_block_template_id}}

ID of the blocked template.

Request Body schema: application/json
status
string
Enum: "1" "0"

Enter the status of the template.

template_id
string

Enter the ID of the template to be updated.

Responses

Request samples

Content type
application/json
{
  • "status": "1",
  • "template_id": "986458"
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Block template updated successfully",
  • "status": "OK"
}

Delete Blocked Template

This endpoint sends an HTTP DELETE request to delete a specific blocked template by its ID.

Note:

  • Replace the {id} in the endpoint with the actual ID of the blocked template you want to delete.
  • Few elements in the endpoint may change from service to service.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{created_block_template_id}}

ID of the blocked template.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "message": "Deleted Successfully",
  • "status": "OK"
}

Import Blocked Templates

This endpoint allows you to import blocked templates by uploading a file.

Note: Few elements in the endpoint may change from service to service.

Request Parameters

Parameter Description Limit Required
file File containing template IDs. (Supported file types: txt, csv, xls, xlsx) 100 MB Yes
caption Enter receiver caption n/a No
filename Receiver file name n/a No
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "message": "Blocked templates accepted for import",
  • "status": "OK"
}

Send Message

SMS Sending Options

This API provides various options available for sending SMS messages. You can send the SMS in the below-mentioned ways:

Option Description
Send SMS Directly send SMS messages to recipients without any special encoding or features.
Send SMS with auto-detect Automatically detect the type of content in the SMS message, such as whether it contains normal text or Unicode characters, and handle it accordingly.
Send SMS with normal text Send SMS messages containing normal text without any special characters or formatting.
Send SMS with unicode characters Send SMS messages containing Unicode characters, allowing for the inclusion of non-standard characters and symbols.
Send SMS with scheduled delivery Schedule the delivery of SMS messages for a future date and time, allowing for planned communication with recipients at specific times.
Send SMS with short link This API enables you to send SMS messages with short links. When you include lengthy URLs in a message, the API automatically condenses them into short URLs before sending them to the user.

Note:

  • Before you begin sending SMS messages through this API, we recommend testing your content against pre-approved templates. This step is crucial to preventing any rejection of your SMS messages.
  • Few elements in the endpoint may change from service to service.
Authorizations:
bearerAuth
Request Body schema: application/json
One of
sender
required
string

The registered and approved sender ID

to
required
string

An array of message destination addresses. The destination address should include the country code prefix.

message
required
string

The message content.

service
required
string

The short code of the service name. Refer to Products/Services

time
string <yyyy-mm-dd hh:mm:ss>

The scheduled time for sending the SMS.

type
string
Enum: "U" "N" "A"

The type of SMS to be sent is Unicode, Normal, or Auto-detect.

flash
number
Enum: "1" "0"

Enable flash SMS (1 for enabled, 0 for disabled).

custom
string

Your own unique ID

port
string

Port number to which SMS has to be delivered.

entity_id
string

Principal Entity ID registered in the DLT portal.

template_id
string

The template ID registered in the DLT portal.

max_units
number
Enum: "2" "3"

The maximum number of units allowed for the message.

webhook_id
string

The id of the Webhook created in the Webhook section for which the SMS response to be sent after delivery report from the operator. Read more. Instead of passing webhook_id every time in the payload, refer to Create Subscription.

object

Additional metadata for the SMS.

Responses

Request samples

Content type
application/json
Example
{
  • "sender": "demo",
  • "to": [
    ],
  • "message": "Your OTP is 123456",
  • "service": "ENT",
  • "time": "2024-03-10 14:06:10",
  • "type": "A",
  • "flash": 1,
  • "custom": "12345",
  • "port": "3908",
  • "entity_id": "12345678",
  • "template_id": "98456363",
  • "max_units": 2,
  • "webhook_id": "{{webhook_Id}}",
  • "meta": {
    }
}

Response samples

Content type
application/json
Example
{
  • "data": [
    ],
  • "message": "1 numbers accepted for delivery.",
  • "group_id": "1a772ff9-26ff-4e2c-9921-93ba453ef967",
  • "status": 200
}

Send Template Message

This API endpoint makes an HTTP POST request to send a template SMS using the template alias name or template id of the predefined template created in your account to specified recipients.

Example Template:

Dear {{name}}, Thanks for registering with us. Your details as follows {{email}}, {{phone}}.

Note: When sending a message, ensure that the data is passed into the data payload. Then the content will be automatically replaced within the template.

Output Message:

Dear Demo, Thanks for regisitering with us. Your details as follows demoxxxx@gmail.com, 9176XXXXXXXX.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth
Request Body schema: application/json
alias
required
string

An alias of the registered template. (Required if id is not present)

id
required
string

ID of the registered template. (Required if alias is not present)

required
object

Variable values for replacing in template content.

object

Additional metadata for the SMS.

required
object

This block contains contact information.

Responses

Request samples

Content type
application/json
{
  • "alias": "variable",
  • "data": {
    },
  • "meta": {
    },
  • "recipient": {
    }
}

Response samples

Content type
application/json
Example
{
  • "status": 200,
  • "message": "2 numbers accepted for delivery.",
  • "group_id": "7c0291e6-0941-440b-b83c-3c0337abd733",
  • "data": [
    ]
}

Send Text Message

This API offers two options for sending text messages. You can send text messages using the following methods:

Option Description
Send text message This API endpoint makes an HTTP POST request to send a text message.
Text message with short link This API enables you to send text messages with short links. When you include lengthy URLs in a message payload, the API automatically condenses them into short URLs before sending them to the user.

Note:

  • Few elements in the endpoint may change from service to service.
  • The recipient block inside the channel is related to a particular communication channel, and it is optional. The outside recipient channel contains common recipients for every channel.
Authorizations:
bearerAuth
Request Body schema: application/json
One of
required
Array of objects

This block contains information related to the messaging channel.

object

Details about the message to be sent.

required
object

This block contains contact information related to the channel.

Responses

Request samples

Content type
application/json
Example
{
  • "channels": [
    ],
  • "message": {
    },
  • "recipient": {
    }
}

Response samples

Content type
application/json
Example
{
  • "data": [
    ],
  • "message": "Message(s) Queued successfully",
  • "status": "OK"
}

DLR Status

Pull DLR Status

This endpoint makes an HTTP GET request to retrieve the status of a specific SMS message using its ID. The request should include the message ID as a query parameter in the URL, and the data should be url_encoded.

You can pass any of the query parameters to get a DLR response. If the request includes a group_id or date, pagination links will be provided. The number of records per page will be limited to 100.

Note: Few elements in the endpoint may change from service to service.

Message Status

Status Description
SCHEDULED The message is scheduled. Delivery has not yet been initiated. A message submitted with a scheduled delivery time may return this status when queried. This value was added for SMPP v5.0. MCs supporting earlier versions of SMPP v3.3 and SMPP v3.4 are likely to return ENROUTE for scheduled messages.
ENROUTE or EN_ROUTE The message is in enroute state. This is a general state used to describe a message as being active within the MC. The message may be in retry or dispatched to a mobile network for delivery to the mobile.
DELIVERED Message is delivered to the destination. No further deliveries will occur.
EXPIRED Message validity period has expired. The message has failed to be delivered within its validity period and/or retry period. No further delivery attempts will be made.
DELETED Message has been deleted. The message has been cancelled or deleted from the MC. No further delivery attempts will take place.
UNDELIVERABLE Message is undeliverable. The message has encountered a delivery error and is deemed permanently undeliverable. No further delivery attempts will be made. Certain network or MC internal errors result in the permanent non-delivery of a message. Examples of such errors would be an unknown subscriber or network error that indicated that the given destination mobile was denied SMS service or could not support SMS.
Authorizations:
bearerAuth
query Parameters
id
string
Example: id={{message_id}}

ID of the SMS message.

mobile
string

Mobile number with country code

cid
string

Your custom ID

date
string

For which date you want the report

group_id
string

Message group ID

Responses

Response samples

Content type
application/json
Example
{
  • "code": 200,
  • "data": [
    ],
  • "message": "OK",
  • "status": "OK"
}

Pricing

View Pricing

This endpoint allows you to retrieve the pricing information for sending SMS messages. By making a GET request, you can obtain the pricing details for different destinations and message types and view all country-wise pricing lists.

Note:

  • Few elements in the endpoint may change from service to service.
  • Kindly replace the token with your respective access_token and other parameters.
Authorizations:
bearerAuth
query Parameters
filter[iso]
string

The ISO code of the country. (e.g., IN, AF, etc.)

filter[service]
string

The short code of the service name. Refer to Products/Services

filter[status]
number
Enum: "0" "1"

Status of the SMS messages.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "Pricing List",
  • "meta": {
    },
  • "status": "OK"
}

Gateway

The SMPP (Short Message Peer-to-Peer) Gateway is a protocol utilized by the telecommunications industry for seamless exchange of SMS messages between Short Message Service Centers (SMSC) and External Short Messaging Entities (ESME). The SMPP protocol is transmitted via TCP/IP, enabling swift and efficient delivery of SMS messages.

Introduction

The messaging platform employs the SMPP v3.4 Protocol Specification Issue 1.5. It is worth noting that our platform is designed to maintain backward compatibility with SMPP v3.3. Therefore, it is recommended to refer to both this document and the SMPP v3.4 Specification v1.5 to ensure a comprehensive understanding of the functionality and features associated with SMPP. Prior familiarity with SMPP is assumed while reading this documentation.

Server List

CPaaS Alerts has multiple SMPP servers for you to connect to. Each SMPP server offers the ability to connect to it via the regular (plaintext) method or via a TLS1.0 or better connection.

Here is an overview of the available servers:

Hostname Plain Port TLS Port
smpp1.txtsms.me 3634 3635
smpp2.txtsms.me 3634 3635

Additional TLV

Mandatory TLV Tag value in decimal Tag value in hex
PE_ID 5120 1400
Template_ID 5121 1401
Telemarketer_ID(TM_ID) 51212 1402

Connectivity

Clients may connect to the Messaging Platform Server multiple times. This may be of importance if the client wishes to deploy multiple applications simultaneously. To connect to the platform, one needs to specify the following parameters:

IP Address and Port: This is the TCP/IP endpoint on which the ESME should connect to the platform.

Username: This is the username (system_id) of your account configured on the platform.

Password: Password for the above account. Required for security reasons to prevent unauthorized access to your account.

System_type: Set the system_type field to smpp.

Interface_version: The client application should connect with the interface_version field set to 0x34 (52 decimal) if it is using SMPP v3.4; otherwise, the platform assumes that the application uses SMPP v3.3.

enquire_link: The application should issue an enquire_link every minute. This will ensure the link stays active even when it is not in use. The messaging platform will automatically disconnect any link that has been inactive for more than 5 minutes.

Bindings and Throughput

Upon setting up an SMPP account for you, you will receive the maximum number of allowed binds and a designated maximum throughput. Typically, these values may be set to something like 3 binds and 50 messages per second.

It’s worth noting that these values are enforced on a per-server basis. In the example mentioned above, you can establish a total of nine binds and achieve a combined throughput of 150 messages per second when connecting to all servers.

Please be aware that, for maintenance purposes, we can only guarantee the availability of one server at any given time. Therefore, we strongly advise connecting to all servers to ensure uninterrupted service.

Bindings and Relaying

CPaaS Alerts employs a message relaying system that is connection and server-agnostic. This means that when you send an MT message via a submit_sm PDU on connection A, you may receive the corresponding DLR in the form of a deliver_sm on connection B, given that both connections are bound with the same username.

This holds true even if the connections are established with different servers. For example, if connection A is made to the SMPP01 server and connection B to the SMPP02 server, the scenario described above would still apply.

Submitting Messages

Submission Types

Messages may be submitted with either submit_sm or data_sm, using either the short_message or message_payload fields. The message length may not exceed the byte limit for the network that the message is being sent to (for example, 140 bytes on GSM networks).

The platform does not support submit_multi. If the same message has to be sent to multiple destinations, each message must be sent separately.

Concatenated messages are supported using the User Data Header (UDH), which is included in the message size byte limit.

Submit Responses

A positive response to a submit will contain an error code of zero and a non-null message reference.

A negative response will contain a vendor-specific error code. The complete set of SMPP error codes and their associated values are defined in the following table.

Error Number Error Name Error Description
0x00000000 ESME_ROK No Error
0x00000001 ESME_RINVMSGLEN Message too long
0x00000002 ESME_RINVCMDLEN Command length is invalid.
0x00000003 ESME_RINVCMDID Command ID is invalid or not supported.
0x00000004 ESME_RINVBNDSTS Incorrect binding status for the given command
0x00000005 ESME_RALYBND Already bound
0x00000006 ESME_RINVPRTFLG Invalid Priority Flag
0x00000007 ESME_RINVREGDLVFLG Invalid registered delivery flag
0x00000008 ESME_RSYSERR System error
0x0000000A ESME_RINVSRCADR Invalid source address
0x0000000B ESME_RINVDSTADR Invalid destination address
0x0000000C ESME_RINVMSGID Message ID is invalid.
0x0000000D ESME_RBINDFAIL Bind failed
0x0000000E ESME_RINVPASWD Invalid password
0x0000000F ESME_RINVSYSID Invalid System ID
0x00000011 ESME_RCANCELFAIL Cancellation message failed.
0x00000013 ESME_RREPLACEFAIL Message replacement failed
0x00000014 ESME_RMSSQFUL Message queue is full.
0x00000015 ESME_RINVSERTYP Invalid service type
0x00000033 ESME_RINVNUMDESTS Invalid number of destinations
0x00000034 ESME_RINVDLNAME Invalid distribution list name
0x00000040 ESME_RINVDESTFLAG Invalid destination flag
0x00000042 ESME_RINVSUBREP Invalid submit with replace request
0x00000043 ESME_RINVESMCLASS Invalid ESM class set
0x00000044 ESME_RCNTSUBDL Invalid submission to the distribution list
0x00000045 ESME_RSUBMITFAIL Submitting a message has failed.
0x00000048 ESME_RINVSRCTON Invalid source address type of number (TON)
0x00000049 ESME_RINVSRCNPI Invalid source address numbering plan (NPI)
0x00000050 ESME_RINVDSTTON Invalid destination address type of number (TON)
0x00000051 ESME_RINVDSTNPI Invalid destination address numbering plan (NPI)
0x00000053 ESME_RINVSYSTYP Invalid system type
0x00000054 ESME_RINVREPFLAG Invalid replace_if_present flag
0x00000055 ESME_RINVNUMMSGS Invalid number of messages
0x00000058 ESME_RTHROTTLED Throttling error
0x00000061 ESME_RINVSCHED Invalid scheduled delivery time
0x00000062 ESME_RINVEXPIRY Invalid validity period value
0x00000063 ESME_RINVDFTMSGID A predefined message was not found.
0x00000064 ESME_RX_T_APPN ESME Receiver temporary error
0x00000065 ESME_RX_P_APPN ESME Receiver permanent error
0x00000066 ESME_RX_R_APPN ESME Receiver reject message error
0x00000067 ESME_RQUERYFAIL Message query request failed.
0x000000C0 ESME_RINVTLVSTREAM Error in the optional part of the PDU body
0x000000C1 ESME_RTLVNOTALLWD TLV is not allowed.
0x000000C2 ESME_RINVTLVLEN Invalid parameter length
0x000000C3 ESME_RMISSINGTLV Expected TLV missing
0x000000C4 ESME_RINVTLVVAL Invalid TLV value
0x000000FE ESME_RDELIVERYFAILURE Transaction delivery failure
0x000000FF ESME_RUNKNOWNERR Unknown error
0x00000100 ESME_RSERTYPUNAUTH ESME is not authorised to use specified service types.
0x00000101 ESME_RPROHIBITED ESME is prohibited from using specified operations.
0x00000102 ESME_RSERTYPUNAVAIL A specified service type is unavailable.
0x00000103 ESME_RSERTYPDENIED A specified service type is denied.
0x00000104 ESME_RINVDCS Invalid data coding scheme
0x00000105 ESME_RINVSRCADDRSUBUNIT Invalid source address subunit
0x00000106 ESME_RINVSTDADDRSUBUNIR Invalid destination address subunit
0x0000040B ESME_RINVBALANCE Insufficient credits to send a message

Character Sets, Class, and Data Coding

The messaging platform supports the following two types of data coding schemes: GSM 03.38 Encoding (default) Latin 1 (ISO-8859-1) encoding

The default character set is GSM 338. Although for data_coding = 1, the character set GSM 03.38 is supported, it is not recommended, as it is known to cause problems with character encoding. Please set data_coding = 3 for ISO-8859-1 (if and only if told so explicitly) encoded messages and data_coding = 0 for GSM 03.38 encoded messages.

For Unicode messages, you have to set data_coding = 8, and the message is expected in UTF-16 Big Endean format.

Delivery Reports

The messaging platform will return a delivery report (intermediate and/or final, depending on the route) for a specific message to the client application when the registered_delivery field, while submitting the message, is set to 1. To retrieve the delivery report from our server, the client will have to connect to the messaging platform in the receiver or transceiver mode.

Error Codes

Status and error codes that can be returned by the messaging platform.

Note: The error codes and status may vary depending on the region and operator.

Code Status Status Description
000 DELIVRD Delivered to SIM.
001 INVALID-SUB Unidentified subscriber.
002 INVALID-SUB Illegal subscriber
003 ABSENT-SUB Unidentified subscriber.
004 HANDSET-ERR Illegal equipment
005 BARRED SMS is prohibited.
006 HANDSET-ERR MS does not support SMS.
007 HANDSET-ERR MS is receiving an error.
008 NET-ERR Facility not supported.
009 MEMEXEC Handset memory is full.
010 ABSENT-SUB Absent subscriber
011 FAILED SMSC system failure
012 NET-ERR Gateway mobile switching error
013 MOB-OFF Mobile handset switched off
014 FAILED SMS is undelivered due to roaming limitations.
015 INVALID-SUB Unidentified subscriber
016 HANDSET-BUSY Subscriber is busy.
017 NET-ERR Resources cannot be used at the GMSC level.
018 SERIES-BLK Series blocked
019 NET-ERR Submission error or invalid input data
020 BARRED CUG reject
021 EXPIRED SMS timeout
034 UNDELIV Unknown Error
045 FAILED Unknown Error
099 UNDELIV Unknown Error
400 SERIES-BLOCK Series has been temporarily or permanently blocked.
401 NO-CREDITS Credit exhausted.
402 NO-ACCOUNT Invalid account.
403 SERVER-ERR Unknown Error
404 INV-NUMBER Invalid destination number
405 SERVER-ERR ESME client error
406 SERVER-ERR ESME client error
407 SPAM Sent illegal content
408 DNDNUMB Number registered in the DND database.
430 SERVER-ERR Unknown Error
431 SERVER-ERR Unknown Error
432 SERVER-ERR Unknown Error
433 SERVER-ERR Unknown Error
450 BLACKLST Number blocklisted to receive messages
451 SNDR-BLOCK Sender ID has been blocked.
452 TEMPLATE-NOT-FOUND No matching templates
453 INV-TEMPLATE Message rejected as template not allotted for ESME
454 INV-SENDER Message rejected as sender ID not allotted for ESME
455 NOT-OPTIN Message rejected as number not in optin list
456 OPTOUT-REJ Rejected as a number optout to receive messages
457 PROMO-TMOUT Promotional time exceeded
458 REJECTED Unknown Error
459 NOTALLOWED Country is not allowed to send SMS.
460 DUPLICATE Same content was sent.
461 UNDELIV Unknown Error
462 FAILED Unknown Error
463 THROTTLED Maximum Sent Limit is Reached
778 REJ-MULTIPART All message parts are not delivered to the handset.
777 DLT-REJECTED Invalid sender ID or invalid template
780 DLT-INV-TMID Invalid DLT Telemarketer ID
781 DLT-INV-ENTITY Invalid Entity DLT ID
782 DLT-INV-TM-ID Invalid DLT Template ID
783 DLT-TM-VAR-EXECEED Template variable exceeded 30 characters.
784 DLT-ENTITY-NOT-FOUND Entity ID not found
785 DLT-TM-BLACKLST Template ID is blacklisted.
786 DLT-ENTITY-BLACKLST Entity ID is blacklisted.
787 DLT-HEADER-INACTIVE Sender Inactive
788 DLT-TM-INACTIVE Template is inactive.
789 DLT-SENDER-NOT-REG-TM Sender is not registered for the template.
790 INV-PROVISION Sender Invalid Provision
791 INV-SERVICE Invalid Service Type
792 INV-SCHEDULE Invalid Schedule

Note: Subscribe here to get SMPP messages and DLRS through Webhook; refer to Subscription.

Overview

RCS Messaging is the evolution of SMS, enabling enterprises and individuals to exchange rich media like images, videos, and interactive content with the same ease as SMS.

Features of RCS messaging:

  • Verified messages

  • Sending rich card messages like images and audio/video files

  • Rich card carousels

  • Message with a suggested action list

  • Message with a suggested reply set

  • Two-way messaging

  • Message revoking for undelivered SMS

Status Info

Name Description
queued A message has been received and queued.
dispatched A message has been dispatched.
sent A message has been sent to the end user.
delivered The message has been successfully delivered to the end user.
read The message has been read by the end user.
deleted A message has been deleted or expired in the application.
failed The message has failed.
blacklist The sender block is listed.
offline The device is offline.
rejected The device rejects the message.
expired Unable to reach end device

Template

View All Templates

This endpoint makes an HTTP GET request to retrieve a list of RCS templates created under your account. The response will include information about the RCS templates, such as their names, IDs, and other relevant details.

Note: Kindly replace the token with your respective access_token and other parameters.

Authorizations:
bearerAuth
query Parameters
filter[id]
string

ID of the template.

filter[name]
string

Name of the template.

filter[type]
string
Enum: "text" "media"

Type of the template.

filter[status]
string
Enum: "0" "1" "2"

Status of the template. (1 is approved), (2 is pending), and (0 is draft).

Responses

Response samples

Content type
application/json
{
  • "status": "OK",
  • "code": 200,
  • "message": "Templates List",
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Create Template

This API provides various options for creating RCS templates.

Templates can be created as required using the methods provided below:

Method Description
Text message This API enables the creation of templates using text as the primary content type.
Text message with suggestion Enhance user engagement by providing suggested responses within text messages, streamlining interactions and improving user experience.
Rich card with button image Present visually appealing rich cards featuring images and interactive buttons, providing users with rich content experiences.
Rich card with button video Incorporate videos into rich card messages, allowing for dynamic and engaging multimedia content.
Rich card with button document Share documents and files effortlessly through rich cards featuring actionable buttons, streamlining the exchange of information and resources.
Carousel template The Carousel Template API provides a versatile solution for creating interactive carousels with rich multimedia content, facilitating engaging user experiences across messaging platforms.
Authorizations:
bearerAuth
Request Body schema: application/json
One of
category
required
string
Value: "text_message"

The category of the template.

is_conversation
required
boolean
Enum: "true" "false"

Indicates whether the template is service or non-service template.

language
required
string
Enum: "eu" "en_US"

The language of the template.

name
required
string

The name of the template.

number
required
string

Mobile number without country code

required
object

The payload of the template

type
required
string
Value: "template"

The type of the template.

Responses

Request samples

Content type
application/json
Example
{
  • "category": "text_message",
  • "is_conversation": false,
  • "language": "en",
  • "name": "vi_text",
  • "number": "73xxxxxxxx",
  • "payload": {
    },
  • "type": "template"
}

Response samples

Content type
application/json
Example
{
  • "code": 200,
  • "data": {
    },
  • "message": "Template created successfully.",
  • "status": "OK"
}

View Template by ID

This endpoint makes an HTTP GET request to retrieve details of a specific template by providing its ID in the URL. The response will include the status of the request, a code indicating the result, a message, and the data related to the template.

Note:

  • Few elements in the endpoint may change from service to service.
  • Replace the {id} in the endpoint with the actual ID of the template you want to see.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{template_id}}

Name of the template.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Templates List",
  • "status": "OK"
}

Edit Template

This endpoint allows you to update an existing RCS template by sending an HTTP PUT request under your account.

Note:

  • Replace the {id} in the endpoint with the actual ID of the template you want to edit.
  • Few elements in the endpoint may change from service to service.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{template_id}}

Name of the template.

Request Body schema: application/json
category
required
string

Category of the template.

language
required
string

Indicates the language of the template.

name
required
string

Enter the name of the template that you want to refer to.

number
required
string

Receivers mobile number

required
object

The payload of the template

type
required
string
Enum: "text" "interactive" "media"

The type of template.

Responses

Request samples

Content type
application/json
{
  • "type": "text",
  • "name": "text_template",
  • "language": "en",
  • "category": "PAYMENT_UPDATE",
  • "number": "73xxxxxxxx",
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Template Updated Successfully",
  • "status": "OK"
}

Delete Template

This endpoint sends an HTTP DELETE request to delete an RCS template by its ID under your account.

Note:

  • Replace the {id} in the endpoint with the actual ID of the template you want to delete.
  • Few elements in the endpoint may change from service to service.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{template_id}}

Name of the template.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": 1,
  • "message": "Template deleted successfully",
  • "status": "OK"
}

Unsubscriber

View All Unsubscribers

This endpoint makes an HTTP GET request to retrieve a list of unsubscribers from the RCS suppressions. The response will contain the details of the unsubscribed phone numbers.

Note:

  • Kindly replace the token with your respective access_token and other parameters.
  • Few elements in the endpoint may change from service to service.
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "Unsubscribers list",
  • "meta": {
    },
  • "status": "OK"
}

Create Unsubscriber

This endpoint allows you to add an unsubscriber to the list of unsubscribers for RCS communications.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth
Request Body schema: application/json
receiver
required
string

Enter the receiver that you want to add.

type
string
Enum: "tag" "product" "sender" "all"

Type of the receiver

value
string

Enter the value of the type.

Responses

Request samples

Content type
application/json
{
  • "receiver": "9176xxxxxxxx",
  • "type": "tag",
  • "value": "tag1"
}

Response samples

Content type
application/json
Example
{
  • "code": 200,
  • "data": {
    },
  • "message": "Receiver added successfully",
  • "status": "OK"
}

Clean Unsubscribers

This HTTP DELETE request is used to remove all unsubscribers from the RCS suppression list.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "message": "Deleted Successfully",
  • "status": "OK"
}

View Unsubscriber by ID

This endpoint retrieves information about a specific RCS unsubscriber by ID. The response will include details such as the ID, ISO country code, receiver number, type, value, and the creation timestamp of the unsubscriber.

Note:

  • Kindly replace the token with your respective access_token.
  • Few elements in the endpoint may change from service to service.
  • Replace the {id} in the endpoint with the actual ID of the unsubscriber you want to see.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{rcs_optout_id}}

The RCS unsubscription ID.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Unsubscribers data",
  • "status": "OK"
}

Edit Unsubscriber

This endpoint allows you to update the details of an unsubscriber by making an HTTP PUT request to the specified endpoint.

Note:

  • Few elements in the endpoint may change from service to service.
  • Replace the {id} in the endpoint with the actual ID of the unsubscriber you want to edit.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{rcs_optout_id}}

The RCS unsubscription ID.

Request Body schema: application/json
receiver
required
string

Enter the receiver that you want to edit.

type
string
Enum: "tag" "product" "sender" "all"

Type of the receiver

value
string

Enter the value of the type.

Responses

Request samples

Content type
application/json
{
  • "receiver": "9176xxxxxxxx",
  • "type": "tag",
  • "value": ""
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Receiver update successfully",
  • "status": "OK"
}

Delete Unsubscriber

This API endpoint sends an HTTP DELETE request to remove a specific unsubscriber from the list of RCS suppressions.

Note:

  • Replace the {id} in the endpoint with the actual ID of the unsubscriber you want to delete.
  • Few elements in the endpoint may change from service to service.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{rcs_optout_id}}

The RCS unsubscription ID.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "message": "Deleted Successfully",
  • "status": "OK"
}

Import Unsubscriber

This API endpoint allows you to import unsubscribers for RCS suppression by uploading a file.

Note: Few elements in the endpoint may change from service to service.

Request Parameter

Parameter Description Limit Required
file File containing unsubscriber numbers. (Supported file types: txt, csv, xls, xlsx) 100 MB Yes
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "message": "Receivers accepted for import",
  • "status": "OK"
}

Send RCS

Send Non-Template Message

This API provides various options available for sending non-template RCS message. You can send the non-template RCS message in the below-mentioned ways:

Option Description
Sending text message This API enables seamless transmission of text messages
Sending image message With this API, you can effortlessly send images, enriching user experiences and enhancing visual communication.
Sending video message You can utilize this API to transmit video messages, enabling the seamless sharing of dynamic visual content.
Sending carousel message You can create multiple cards and interactive carousels, allowing users to swipe through diverse content like images, videos, or text.
Sending interactive message Enhance user interaction with interactive messages featuring clickable buttons.
Sending card message This API empowers developers to transmit structured card-based messages, providing concise and visually appealing content delivery to users.

Note:

  • Few elements in the endpoint may change from service to service.
  • The recipient block inside the channel is related to a particular communication channel, and it is optional. The outside recipient channel contains common recipients for every channel.
Authorizations:
bearerAuth
Request Body schema: application/json
One of
required
Array of objects

Specifies the channels through which the message will be sent.

object

Specifies the message details.

required
object

Specifies the recipient of the message.

Responses

Request samples

Content type
application/json
Example
{
  • "channels": [
    ],
  • "message": {
    },
  • "recipient": {
    }
}

Response samples

Content type
application/json
Example
{
  • "data": [
    ],
  • "message": "Messages queued successfully",
  • "status": "OK"
}

Send Template Message

This API endpoint makes an HTTP POST request to send a RCS message using a template. You can send messages using the template alias name or template id of the predefined template created in your account to specified recipients.

Example Template:

Dear {{name}}, Thanks for registering with us. Your details as follows {{email}}, {{phone}}.

Note: When sending a message, ensure that the data is passed into the data payload. Then the content will be automatically replaced within the template.

Output Message:

Dear Demo, Thanks for regisitering with us. Your details as follows demoxxxx@gmail.com, 9189XXXXXXXX.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth
Request Body schema: application/json
alias
required
string

An alias of the registered template. (Required if id is not present)

id
required
string

ID of the registered template. (Required if alias is not present)

required
object

Variable values for replacing in template content.

object

Additional metadata for the RCS.

required
object

This block contains contact information.

Responses

Request samples

Content type
application/json
{
  • "alias": "template-name",
  • "data": {
    },
  • "recipient": {
    },
  • "meta": {
    }
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "message": "Message(s) Queued successfully",
  • "status": 200
}

DLR Status

Pull DLR Status

This endpoint makes an HTTP GET request to retrieve the status of a specific RCS message using its ID.

You can pass any of the query parameters to get a DLR response.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth
query Parameters
id
string
Example: id={{message_id}}

ID of the RCS message.

mobile
string

Mobile number with country code

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "message": "OK",
  • "status": "OK"
}

Pricing

View Pricing

This endpoint allows you to retrieve the pricing information for sending RCS messages. By making a GET request, you can obtain the pricing details for different destinations and message types and view all country-wise pricing lists.

Note:

  • Few elements in the endpoint may change from service to service.
  • Kindly replace the token with your respective access_token and other parameters.
Authorizations:
bearerAuth
query Parameters
filter[iso]
string

The ISO code of the country. (e.g., IN, AF, etc.)

filter[service]
string

The short code of the service name. Refer to Products/Services

filter[subservice]
string

The short code of the service name. Refer to Products/Services.

filter[status]
number
Enum: "0" "1"

Status of the RCS messages.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "Pricing List",
  • "meta": {
    },
  • "status": "OK"
}

View Smart Link Visits

This endpoint retrieves the visit details for a specific URL identified by the provided ID. It sends an HTTP GET request to the specified endpoint.

Note:

  • Few elements in the endpoint may change from service to service.
  • Kindly replace the token with your respective access_token and other parameters.
  • Replace the {id} in the endpoint with the actual ID of the smart link you want to retrieve the visit details.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{smartlink_id}}

The unique identifier of the URL for which visit details are to be retrieved.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "Visits",
  • "meta": {
    },
  • "status": "OK"
}

Replaceable Variables

We generate some of the variables in flow process, those can used to pass the information your system.

Note: Studio flow is applicable when utilizing the flow builder.

Varibles consist of alphanumeric characters and underscores, should always start with a letter, and do not have any kind of leading sigil (that is, they look like var_name, not $var_name). Also variables should not consist of backslash(’') as our application treats the backslash as an escape character by default.

All variables should be enclosed between a set of double curly braces {{}} braces. ex: @{{to}} You can access the Array of the variables with . dot notation.

FLOW VARIABLES

Name Scope Description
id global Sms unique id
text global Sms send by the customer
from global Sms from number with country code
to global Sms to number with country code
date global Current time in YYYY-MM-DD h:i:s format

Advanced output: Filters

Output markup can take filters, which modify the result of the output statement. You can invoke filters by following the output statement’s main expression with:

  • A pipe character (|)
  • The name of the filter
  • Optionally, a colon (:) and a comma-separated list of additional parameters to the filter. Each additional parameter must be a valid expression, and each filter pre-defines the parameters it accepts and the order in which they must be passed.

Filters can also be chained together by adding additional filter statements (starting with another pipe character). The output of the previous filter will be the input for the next one.

{{mobile|slice:-10 }}
{{date|date_format:'d/m/y'}}
Name Description
append Append a string, e.g., {{ 'foo' | append:'bar' }} #=> 'foobar'
ceil Rounds a number up to the nearest integer, e.g., {{ 4.6 | ceil }} #=> 5
date_format Reformat a date {{start_at | date_format:'d/m/Y'}}
default Returns the given variable unless it is null or an empty string, when it will return the given value, e.g., {{ undefined_variable | default: Default value }} #=> Default value
divided_by Integer division, e.g., {{ 10 | divided_by:3 }} #=> 3
downcase Convert an input string to lowercase
escape HTML escapes a string
first Get the first element of the passed in array
floor Rounds a number down to the nearest integer, e.g., {{ 4.6 | floor }} #=> 4
lstrip Strips all whitespace from the beginning of a string
minus Subtraction, e.g., {{ 4 | minus:2 }} #=> 2
modulo Remainder, e.g., {{ 3 | modulo:2 }} #=> 1
plus Addition, e.g., {{ '1' | plus:'1' }} #=> 2, {{ 1 | plus:1 }} #=> 2
prepend Prepend a string, e.g., {{ 'bar' | prepend:'foo' }} #=> 'foobar'
round Rounds input to the nearest integer or specified number of decimals, e.g., {{ 4.5612 | round: 2 }} #=> 4.56
rstrip Strips all whitespace from the end of a string
size Return the size of an array or string
slice Slice a string. Takes an offset and length, e.g., {{ “hello” | slice: -3, 3 }} #=> llo
split Split a string on a matching pattern e.g., {{ a~b | split:~ }} #=> ['a','b']
strip Strips all whitespace from both ends of the string.
times Multiplication, e.g., {{ 5 | times:4 }} #=> 20
upcase Convert an input string to uppercase
url_encode URL encodes a string

Strings. Literal strings must be surrounded by double quotes or single quotes (“my string” or ‘my string’). There is no difference; neither style allows variable interpolation.

Integers. Integers must not be quoted.

Booleans and nil. The literal values true, false, and nil.

Other variable within variable

Sometimes you want to use the other variable value with in variable to get the right value

[] can used to pass the variable with in other variable. ex: {{questions.[jump].name}}

Here we are using jump variable to get the original value of question.

it will be question.0.name, question.1.name, question.2.name

Overview

Thundersms voice APIs empower businesses to revolutionize their communication strategies with seamless voice integration.

From basic functionalities like making and receiving calls to advanced features such as call recording, interactive voice response (IVR), and creating sound files, Thundersms Voice APIs provide a versatile platform to build customized voice solutions tailored to your unique requirements.

Call Status

The table below provides descriptions for various call statuses returned by Thundersms voice APIs:

Name Description
ANSWER The call is answered. A successful dial. The caller reached the callee.
BUSY Busy signal. The dial command reached its number, but the number is busy.
NOANSWER The dial command reached its number; the number rang for too long, then the dial timed out.
CANCEL The call is cancelled. The dial command reached its number, but the caller hung up before the callee picked up.
CONGESTION This status is usually a sign that the dialled number is not recognised.
CHANUNAVAIL Channel unavailable. On SIP, peers may not be registered.
RECEIVED A call was received in the IVR system, but no call forward happened.
MISSED A call was received in the IVR system, but no call forward happened.
COMPLETED The second leg is answered.

Call Strategies

The table below outlines various call strategies available for optimizing agent allocation and handling within Thundersms voice APIs:

Name Description
parallel Call all available agents until one answers.
sequential Take turns calling each available agents.
random Call random agents who are available.
fewest Call the one with the fewest completed calls.

These call strategies offer flexibility in how calls are distributed among agents, allowing businesses to optimize their call handling processes based on factors such as agent availability, workload distribution, and efficiency.

Replaceable Variables

We generate some of the variables in the flow process, and those can be used to pass the information to your system.

Varibles consist of alphanumeric characters and underscores, should always start with a letter, and do not have any kind of leading sigil (that is, they look like var_name, not $var_name).

All variables should be enclosed between a set of double curly braces {{}} braces. ex: @{{to}} You can access the array of variables with . dot notation. Example: If you want to access the caller name information from the caller object {{caller.name}}

Flow Variables

The table below presents the flow variables available within Thundersms voice APIs:

Name Scope Description
id global Unique identifier for the call.
from global Caller's number including country code.
to global Number being called including country code.
bridge global DID (Direct Inward Dialing) number with country code.
start_at global Time when the call started in YYYY-MM-DD h:i:s format.
end_at global Time when the call ended in YYYY-MM-DD h:i:s format.
date global Current time in YYYY-MM-DD h:i:s format.
unixtime global Current time in unixtime format.
caller.country global Two-letter country code of the caller (e.g., IN for India).
caller.provider global Two-letter operator code of the caller (e.g., RJ for Reliance JIO).
caller.region global Two-letter region code of the caller (e.g., KA for Karnataka).
caller.name global Caller's name if available in contacts.
caller.email global Caller's email if available in contacts.
outgoing.id step Unique identifier for outgoing calls.
outgoing.parent_id step Parent ID for outgoing calls.
outgoing.from step Caller's number with country code for outgoing calls.
outgoing.to step Number being called with country code for outgoing calls.
outgoing.caller_id step Caller ID set for this outgoing call.
outgoing.start_at step Start time of the outgoing call in YYYY-MM-DD h:i:s format.
outgoing.end_at step End time of the outgoing call in YYYY-MM-DD h:i:s format.
outgoing.country step Prefix of the calling country for outgoing calls.
outgoing.duration step Duration of the call including ring time for outgoing calls.
outgoing.billing step Billable duration of the call for outgoing calls.
outgoing.status step Status of the outgoing call.
outgoing.hangup_by step Identification of who disconnected the call first (e.g., agent).

Advanced Output/Filters

Output markup can take filters, which modify the result of the output statement. You can invoke filters by following the output statement’s main expression with:

  • A pipe character (|)
  • The name of the filter
  • Optionally, a colon (:) and a comma-separated list of additional parameters are added to the filter. Each additional parameter must be a valid expression, and each filter pre-defines the parameters it accepts and the order in which they must be passed.

Filters can also be chained together by adding additional filter statements (starting with another pipe character). The output of the previous filter will be the input for the next one.

{{mobile|slice:-10 }}
{{caller.name|upper}}
{{date|date_format:'d/m/y'}}
Name Description
append Append a string, e.g., {{ 'foo' | append:'bar' }} #=> 'foobar'
ceil Rounds a number up to the nearest integer, e.g., {{ 4.6 | ceil }} #=> 5
date_format Reformat a date {{start_at | date_format:'d/m/Y'}}
default Returns the given variable unless it is null or an empty string, when it will return the given value, e.g., {{ undefined_variable | default: Default value }} #=> Default value
divided_by Integer division, e.g., {{ 10 | divided_by:3 }} #=> 3
downcase Convert an input string to lowercase
escape HTML escapes a string
first Get the first element of the passed in array
floor Rounds a number down to the nearest integer, e.g., {{ 4.6 | floor }} #=> 4
lstrip Strips all whitespace from the beginning of a string
minus Subtraction, e.g., {{ 4 | minus:2 }} #=> 2
modulo Remainder, e.g., {{ 3 | modulo:2 }} #=> 1
plus Addition, e.g., {{ '1' | plus:'1' }} #=> 2, {{ 1 | plus:1 }} #=> 2
prepend Prepend a string, e.g., {{ 'bar' | prepend:'foo' }} #=> 'foobar'
round Rounds input to the nearest integer or specified number of decimals, e.g., {{ 4.5612 | round: 2 }} #=> 4.56
rstrip Strips all whitespace from the end of a string
size Return the size of an array or string
slice Slice a string. Takes an offset and length, e.g., {{ “hello” | slice: -3, 3 }} #=> llo
split Split a string on a matching pattern e.g., {{ a~b | split:~ }} #=> ['a','b']
strip Strips all whitespace from both ends of the string.
times Multiplication, e.g., {{ 5 | times:4 }} #=> 20
upcase Convert an input string to uppercase
url_encode URL encodes a string

Variable Usage Guide

String

Literal strings must be surrounded by double quotes or single quotes (“my string” or ‘my string’). There is no difference; neither style allows variable interpolation.

Integer

Integers must not be quoted.

Boolean and nil

The literal values true, false, and nil.

Other Variable within Variable

Sometimes you want to use the other variable value with in variable to get the right value. [] can be used to pass the variable with in other variable. ex: {{questions.[jump].name}}. Here we are using a jump variable to get the original value of question. It will be a question.0.name, question.1.name, question.2.name.

Variables in Play

We can define how to treat the variables while playing.

  • digits we want to say as digits, we can use {{otp@digits}}

  • number we want to say as a number, we can use {{otp@number}}

  • play we want to download the mp3 file and play, we can use {{clip@play}}

  • sound to play in build sound files, we can use {{clip@sound}}

3-Way Calling

We can convert a 2-way call into a 3-way call.

  • Press # while you are on call. Then enter the receiver number.

  • After you are connected to the third person, press ** to convert the call into a conference.

VoiceId Options

The table below presents the VoiceId options supported by AWS Polly for text-to-speech:

VoiceId Language Gender
Aditi Hindi Female
Raveena English Female
Zeina Arabic Female
Hala Arabic (Gulf) Female
Arlet Catalan Female
Hiujin Chinese (Cantonese) Female
Zhiyu Chinese (Mandarin) Female
Naja Danish Female
Laura Dutch Female
Nicole English (Australian) Female
Amy English (British) Female
Aria English (New Zealand) Female
Ayanda English (South African) Female
Kendra English (US) Female
Geraint English (Welsh) Male
Suvi Finnish Female
Léa French Female
Chantal French (Canadian) Female
Marlene German Female
Hans German Male
Dóra/Dora Icelandic Female
Carla Italian Female
Mizuki Japanese Female
Seoyeon Korean Female
Liv Norwegian Female
Ewa Polish Female
Camila Portuguese (Brazilian) Female
Inês/Ines Portuguese (European) Female
Carmen Romanian Female
Tatyana Russian Female
Conchita Spanish (European) Female
Mia Spanish (Mexican) Female
Lupe Spanish (US) Female
Astrid Swedish Female
Filiz Turkish Female
Gwyneth Welsh Female

Unsubscriber

View All Unsubscribers

This endpoint makes an HTTP GET request to retrieve a list of unsubscribers from the Engage suppressions. The response will contain the details of the unsubscribed phone numbers.

Note:

  • Few elements in the endpoint may change from service to service.
  • Kindly replace the token with your respective access_token and other parameters.
Authorizations:
bearerAuth
query Parameters
filter[id]
string

The Engage unsubscription ID.

filter[iso]
string

The ISO code of the country. (e.g., IN, AF, etc.)

filter[receiver]
string

The unsubscribed mobile number.

filter[type]
string
Enum: "tag" "sender" "service"

Type of unsubscription

filter[value]
string

Value for any of the given type.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "Unsubscribers list",
  • "meta": {
    },
  • "status": "OK"
}

Create Unsubscriber

This endpoint allows you to add an unsubscriber to the list of unsubscribers.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth
Request Body schema: application/json
receiver
required
string

Enter the receiver that you want to add.

type
string
Enum: "tag" "product" "sender" "all"

Type of the receiver

value
string

The value associated with the unsubscription type.

Responses

Request samples

Content type
application/json
{
  • "receiver": "9176xxxxxxxx",
  • "type": "tag",
  • "value": "tag1"
}

Response samples

Content type
application/json
Example
{
  • "code": 200,
  • "data": {
    },
  • "message": "Receiver added successfully",
  • "status": "OK"
}

Clean Unsubscribers

This HTTP DELETE request is used to remove all unsubscribers from the Engage suppression list.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "message": "Deleted Successfully",
  • "status": "OK"
}

View Unsubscriber by ID

This endpoint retrieves information about a specific Engage unsubscriber by ID. The response will include details such as the ID, ISO country code, type, value, and receiver number of the unsubscriber.

Note:

  • Few elements in the endpoint may change from service to service.
  • Kindly replace the token with your respective access_token.
  • Replace the {id} in the endpoint with the actual ID of the unsubscriber you want to see.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{optout_id}}

The Engage unsubscription ID.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Unsubscribers data",
  • "status": "OK"
}

Edit Unsubscriber

This endpoint allows you to update the details of an unsubscriber by making an HTTP PUT request to the specified endpoint.

Note:

  • Few elements in the endpoint may change from service to service.
  • Replace the {id} in the endpoint with the actual ID of the unsubscriber you want to edit.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{optout_id}}

The Engage unsubscription ID.

Request Body schema: application/json
receiver
required
string

Enter the receiver that you want to edit.

type
string
Enum: "tag" "product" "sender" "all"

Type of the receiver

value
string

The value associated with the unsubscription type.

Responses

Request samples

Content type
application/json
{
  • "receiver": "9176xxxxxxxx",
  • "type": "tag",
  • "value": ""
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Receiver update successfully",
  • "status": "OK"
}

Delete Unsubscriber

This API endpoint sends an HTTP DELETE request to remove a specific unsubscriber from the list of Engage suppressions.

Note:

  • Replace the {id} in the endpoint with the actual ID of the unsubscriber you want to delete.
  • Few elements in the endpoint may change from service to service.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{optout_id}}

The Engage unsubscription ID.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "message": "Deleted Successfully",
  • "status": "OK"
}

Import Unsubscriber

This API endpoint allows you to import unsubscribers for Engage suppression by uploading a file.

Note: Few elements in the endpoint may change from service to service.

Request Parameter

Parameter Description Limit Required
file File containing unsubscriber numbers. (Supported file types: txt, csv, xls, xlsx) 100 MB Yes
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "message": "Receivers accepted for import",
  • "status": "OK"
}

Engage

Create Outgoing Call

This API provides various options for creating outgoing calls.

Outgoing calls can be created as required using the methods provided below:

Method Description
Create outgoing call with IVR ID This API enables the initiation of outgoing calls integrated with an Interactive Voice Response (IVR) system identified by its unique IVR ID. It allows you to programmatically trigger calls that are seamlessly connected to an IVR, enabling automated interactions with callers through recorded prompts and menu options.
Create outgoing call with audio file With this API, you can create outgoing calls incorporating audio files. You can specify the audio file to be played during the call, allowing for customized messages, announcements, or prompts to be delivered to recipients dynamically.
Create outgoing call with audio ID This API facilitates the creation of outgoing calls using pre-existing audio files identified by their unique audio IDs. It provides a convenient method for incorporating previously uploaded or predefined audio content into outgoing calls, streamlining the call initiation process.
Create outgoing call with IVR ID and variables This API extends the functionality of the create outgoing call with IVR ID by allowing the inclusion of additional variables during call initiation. You can pass custom variables along with the IVR ID, enabling personalized interactions and dynamic content delivery based on specific caller attributes or contextual information.

Note:

  • Few elements in the endpoint may change from service to service.

  • When creating outgoing call with IVR ID and variables, IVR journey created should have a play widget with text-to-speech containing variables as follows:

    Hello {Name}, your otp for login is {otp}

    The above message contains two variables; these varaible values will replace the API parameters when the customer answers the outgoing call.

Authorizations:
bearerAuth
Request Body schema: application/json
One of
bridge
required
string

Bridge number for call initiation.

flow_id
required
string

ID of the IVR flow created in your voice account.

Note: Create a IVR Journey in Engage>Studio section of the Thundersms website and then utilize it here.

name
string

Name of the campaign

to
required
string

Phone number with a country code to which the call has to connect.

interval
number
Default: 0
Enum: 5 15 30 45 60

Retry interval time in minutes.

webhook_id
string

ID of the webhook created in the Webhook section Create Webhook. Instead of passing webhook_id every time in the payload, refer to Create Subscription.

Responses

Request samples

Content type
application/json
Example
{
  • "bridge": "{{bridge_num}}",
  • "flow_id": "{{engage_flow_id}}",
  • "name": "obd_api_call",
  • "to": "{{receiver}}",
  • "interval": 5,
  • "webhook_id": "{{webhook_Id}}"
}

Response samples

Content type
application/json
Example
{
  • "data": [
    ],
  • "message": "Calls queued successfully",
  • "status": "OK"
}

Create Bulk Outgoing Calls

This API provides various options available for creating bulk outgoing calls. You can create bulk outgoing calls in the below-mentioned ways:

Option Description
Bulk calls with same audio file This API allows you to create bulk outgoing calls to a list of mobile numbers using a same audio file. Provide the caller number, audio file URL, flow ID, and recipient numbers to initiate calls efficiently.
Bulk calls with different audio file This API facilitates creating bulk outgoing calls with different audio files for each recipient. Specify the caller number and an array of objects containing the recipient's number and the corresponding audio file URL. This allows for personalized message delivery to each recipient.
Bulk calls with flow ID and variables This API facilitates creating bulk outgoing calls with flow ID and variables. Specify the caller number and an array of objects containing the recipient's number and the corresponding variables. This allows for personalized message delivery to each recipient.
Authorizations:
bearerAuth
Request Body schema: application/json
One of
bridge
required
string

Bridge number for call initiation.

audio
required
string

URL of the audio file to be played during calls if flow_id parameter is not available.

Note:

  • Upload the audio file in Reach>Sounds section of the Thundersms website and then utilize it here.
  • Accepts publicly accessible audio file location and must start with either http or https.
flow_id
required
number

ID of the IVR flow created in your voice account if the audio parameter is not available.

Note: Create a IVR Journey in Engage>Studio section of the Thundersms website and then utilize it here.

name
string

Name of the campaign

webhook_id
string

ID of the webhook created in the Webhook section Create Webhook. Instead of passing webhook_id every time in the payload, refer to Create Subscription.

required
object

An array containing objects that specify the details of the outbound call recipients.

Responses

Request samples

Content type
application/json
Example
{
  • "bridge": "9170xxxxxxxx",
  • "name": "obd_api_call",
  • "webhook_id": "{{webhook_Id}}",
  • "payload": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "OK",
  • "code": 200,
  • "message": "3 numbers queued successfully.",
  • "group_id": "cb610308-e82e-4c82-83ce-1fba6b3ec86f",
  • "total": 3,
  • "data": [
    ]
}

Create Text To Speech

The Text-to-speech API can trigger a call using text as input, and that text will be played as a voice message once the recipient answers the call. This API provides various options for creating text to speech.

Text-to-speech can be created as required using the methods provided below:

Method Description
Text to speech with voice ID This feature allows you to customize the voice used for converting text to speech, allowing for a personalized user experience. Users can select from a range of available voices to suit their preferences. Refer to VoiceID Options
Text to speech with break in text attribute This feature allows you to gain granular control over speech synthesis by inserting breaks at designated points within the text. These breaks serve to pace the delivery of information, enhancing comprehension and naturalness.
Text to speech iteration tries to text This feature enables optimal accuracy and clarity in speech synthesis by allowing multiple iterations of text-to-speech conversion. It enhances the quality and effectiveness of the speech output, ensuring clear and natural-sounding messages even in challenging scenarios.
Text to speech with customized voice This feature enables you to customize the voice used for converting text to speech, allowing for a personalized user experience. Users can select the gender and language to suit their preferences.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth
Request Body schema: application/json
One of
bridge
required
string

Bridge number for call initiation.

object

Additional settings for the text-to-speech conversion.

text
required
string

Message text you want to send, which will be played as speech once the call is answered.

to
required
string

Phone number with a country code to which the call has to connect.

Responses

Request samples

Content type
application/json
Example
{
  • "bridge": "{{bridge_num}}",
  • "options": {
    },
  • "text": "A wish for you on your birthday, whatever you ask may you receive, whatever you seek may you find, whatever you wish may it be fulfilled on your birthday and always. Happy birthday!",
  • "to": "{{receiver}}"
}

Response samples

Content type
application/json
Example
{
  • "data": [
    ],
  • "message": "Calls queued successfully",
  • "status": "OK"
}

Click2Call

This API provides various options available for Click2Call.

You can use Click2Call in the below-mentioned ways:

Method Description
Click2Call with flow ID This API enables the initiation of click-to-call functionality using a predefined flow ID, allowing for automated calls based on specific call flows or workflows.
Click2Call with mobile number This API facilitates click-to-call functionality directly to a specified mobile number, streamlining the process of initiating outbound calls from applications.
Click2Call with flow ID and variables This API combines the functionality of initiating calls using a flow ID while also allowing for the passing of dynamic variables, enabling personalized interactions during the call process.

Note:

  • Few elements in the endpoint may change from service to service.

  • When making click to call with flow ID and variables, IVR journey created should have a play widget with text-to-speech containing variables as follows:

    Hello {Name}, your otp for login is {otp}

    The above message contains two variables; these varaible values will replace the API parameters when the customer answers the click2call.

Authorizations:
bearerAuth
Request Body schema: application/json
One of
bridge
required
string

DID number for call initiation.

from
required
string

The number to whom the call will connect first, along with the country code.

record
string
Default: "0"
Enum: "0" "1"

Record this conversation

attempts
number <= 2
Default: 2

Number of redial attempts on unanswered calls.

mid
string

Message ID, a unique identifier for the call message.

webhook_id
string

Webhook ID for pushing the call data once the call completed. Instead of passing webhook_id every time in the payload, refer to Create Subscription.

duration
string
Default: "none"

Limit the call duration in minutes.

to
required
string

IVR flow to which call has to connect.

Note: Create a IVR Journey in Engage>Studio section of the Thundersms website and then utilize it here.

Responses

Request samples

Content type
application/json
Example
{
  • "bridge": "{{bridge_num}}",
  • "from": "{{from}}",
  • "to": "{{receiver}}",
  • "record": "1",
  • "attempts": 2,
  • "mid": 1234,
  • "webhook_id": "{{webhook_Id}}",
  • "duration": "5"
}

Response samples

Content type
application/json
Example
{
  • "callId": "5ab42ecb-bed4-47b6-93e0-525cbaa209ad",
  • "message": "call initiated successfully",
  • "status": 200
}

Call Logs Report

This endpoint makes an HTTP GET request to retrieve a list of voice call data within a specified date range. The response includes a status message, an array of call data objects, links for pagination, and metadata about the current page and total number of calls.

Note:

  • Few elements in the endpoint may change from service to service.
  • Kindly replace the token with your respective access_token and other parameters.
Authorizations:
bearerAuth
query Parameters
datetime[end_at]
string
Example: datetime[end_at]=Apr 01, 2021 - Apr 12, 2021

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "OK",
  • "meta": {
    },
  • "status": "OK"
}

Call Recordings Report

This endpoint makes an HTTP GET request to retrieve voice recordings based on the specified datetime range. The response includes a status, code, message, an empty data array, and links for pagination. The meta section provides information about the current page, total records, and pagination links.

Note:

  • Few elements in the endpoint may change from service to service.
  • Kindly replace the token with your respective access_token and other parameters.
Authorizations:
bearerAuth
query Parameters
datetime[r.created_at]
string
Example: datetime[r.created_at]=Apr 01, 2021 - Apr 12, 2021

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "links": {
    },
  • "message": "OK",
  • "meta": {
    },
  • "status": "OK"
}

Call Status

This endpoint makes an HTTP GET request to retrieve the status of an outgoing call by providing the outcall_id as a query parameter.

You can retrieve the status of an outgoing call with the query parameters.

Authorizations:
bearerAuth
query Parameters
id
string
Example: id={{outcall_id}}

ID of the call that was initiated through the API

cid
string

Your custom ID

date
string

Valid date

mobile
string

Valid mobile number with a country code

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "message": "OK",
  • "status": 200
}

Create Sound File

This HTTP POST request is used to upload a sound file to the specified endpoint. The request should include the name and audio of the sound file to be uploaded.

Request Parameters

Parameter Optional/Mandatory Description
audio Mandatory Sound file that you want to upload
name Optional Name of the sound file for your response.

Note:

  • Few elements in the endpoint may change from service to service.
  • The id parameter in response can be used for outgoing campaign purposes as an audio source.
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Sound uploaded successfully",
  • "status": "OK"
}

Pricing

View Pricing

This endpoint makes an HTTP GET request to retrieve the pricing information for Engage services. The response will contain details about the pricing for various Engage services.

Note:

  • Few elements in the endpoint may change from service to service.
  • Kindly replace the token with your respective access_token and other parameters.
Authorizations:
bearerAuth
query Parameters
filter[iso]
string

The ISO code of the country. (e.g., IN, AF, etc.)

filter[service]
string

The short code of the service name. Refer to Products/Services.

filter[subservice]
string

The short code of the service name. Refer to Products/Services.

filter[status]
string
Enum: "0" "1"

Status of the WhatsApp messages.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "Pricing List",
  • "meta": {
    },
  • "status": "OK"
}

Overview

The Verify API allows you to implement two-factor authentication by verifying mobile phone numbers.

This functionality is beneficial for the following purposes:

  • Protection against spam: preventing spammers from creating multiple accounts.

  • Monitoring suspicious activity: verifying ownership of a phone number to detect any unusual behaviour.

  • Ensuring effective communication: having the correct phone number on record to reach users reliably.

To initiate the verification process for a recipient, simply create a new Verify object through the API. We will handle the generation of a token and ensure that the verification message is successfully delivered to the user’s mobile device.

Thundersms offers versatile OTP delivery solutions to meet different communication needs. Our APIs ensure secure OTP verification through two distinct methods: Omnichannel and Direct Channel.

Direct Channel

This API provides straightforward OTP delivery through a single communication path. This approach also includes failover mechanisms across all channels, automatically switching to an alternate channel if the primary channel fails.

Omnichannel

The omnichannel API orchestrates seamless communication across multiple channels, including SMS, WhatsApp, and Viber. Hosted on the Thundersms platform, it utilizes a customizable failover profile that delineates the sequence and timing between channels. The process begins with the initial channel and, if unsuccessful, automatically progresses through the specified channels until the One Time Password (OTP) delivery is confirmed.

Manage Omnichannel Profile

View All Profiles

This endpoint makes an HTTP GET request to retrieve all profiles created under your account.

Authorizations:
bearerAuth
query Parameters
filter[id]
string

ID of the profile.

filter[name]
string

Name of the profile.

filter[status]
string
Enum: "1" "0"

Status of the profile. (1 is active), (0 is inactive).

Responses

Response samples

Content type
application/json
{
  • "status": "OK",
  • "code": 200,
  • "message": "Profiles List",
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Create Profile

This endpoint allows you to create a new profile using the POST method.

Authorizations:
bearerAuth
Request Body schema: application/json
name
required
string

The name of the profile, which should consist of alphanumeric characters only.

status
string
Default: "1"
Enum: "1" "0"

The status of the profile. (0 for inactive, 1 for active)

Responses

Request samples

Content type
application/json
{
  • "name": "profileName",
  • "status": "1"
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Profile Created Successfully",
  • "status": "OK"
}

View Profile by ID

This endpoint makes an HTTP GET request to retrieve the profile information for a specific ID. The response includes the profile ID, name, status, and a list of channels associated with the profile. Each channel in the response contains its ID, wait time, ordering, status, and template information.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{profile_id}}

ID of the profile.

Responses

Response samples

Content type
application/json
{
  • "status": "OK",
  • "code": 200,
  • "message": "Profile List",
  • "data": [
    ]
}

Edit Profile

This endpoint allows the user to update a specific profile by sending an HTTP PUT request to the specified URL.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{profile_id}}

ID of the profile.

Request Body schema: application/json
name
required
string

The name of the profile, which should consist of alphanumeric characters only.

status
string
Default: "1"
Enum: "1" "0"

The status of the profile. (0 for inactive, 1 for active)

Responses

Request samples

Content type
application/json
{
  • "name": "profileName",
  • "status": "0"
}

Response samples

Content type
application/json
{
  • "status": "OK",
  • "code": 200,
  • "message": "Profile Updated Successfully",
  • "data": {
    }
}

Delete Profile

This endpoint is used to delete a specific profile by providing the profile ID in the URL.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{profile_id}}

ID of the profile.

Responses

Response samples

Content type
application/json
{
  • "status": "OK",
  • "code": 200,
  • "message": "Profile Deleted Successfully",
  • "data": {
    }
}

Manage Omnichannel Profile Channel

Add Channels to Profile

This endpoint makes an HTTP POST request to add channels to the profile.

Note:

  • Users can set up profiles based on their preferences without following a specific order or being restricted by the number of channels.
  • After adding the voice channel to the profile, ensure that the next channel has a minimum wait time of 60 seconds.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{profile_id}}

ID of the profile.

Request Body schema: application/json
Array of SMS (object) or WhatsApp (object) or Text to Speech (object) or Viber (object)

Represents a communication channel used to send messages with specific properties.

Responses

Request samples

Content type
application/json
{
  • "channels": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "code": 200,
  • "data": {
    },
  • "message": "Channel Added Successfully",
  • "status": "OK"
}

Edit Profile Channels

This endpoint makes an HTTP PUT request to update the channels for a specific profile. The request body should contain an array of channels with their respective details such as name, from, template, order, and wait.

Note: Users can set up profiles based on their preferences without following a specific order or being restricted by the number of channels.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{profile_id}}

ID of the profile.

Request Body schema: application/json
Array of SMS (object) or WhatsApp (object) or Text to Speech (object) or Viber (object)

Represents a communication channel used to send messages with specific properties.

Responses

Request samples

Content type
application/json
{
  • "channels": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "OK",
  • "code": 200,
  • "message": "Channel Updated Successfully",
  • "data": {
    }
}

Delete Channel from Profile

The DELETE request is used to delete a specific channel associated with a profile.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{profile_id}}

The profile ID of the channel to be deleted.

channel_name
required
string
Example: {{channel_name}}

The name of the channel to be deleted.

Responses

Response samples

Content type
application/json
{
  • "status": "OK",
  • "code": 200,
  • "message": "Channel Deleted Successfully",
  • "data": {
    }
}

OTP Delivery APIs

Send Direct OTP

This API provides various options available for sending one-time password (OTP).

You can send the OTP in the below-mentioned ways:

Option Description
Send WhatsApp OTP This API allows you to send a OTPs via WhatsApp.
Send SMS OTP With this API, you can deliver OTPs via SMS.
Send Engage OTP This API allows you to send OTPs via voice.
Send Viber OTP This API empowers you to send OTPs through the Viber.
Send RCS OTP With this API, you can deliver OTPs via RCS.
Failover for all channels This API handles the failover process when sending OTPs across various channels. In case of failure to deliver the OTP through the first channel, this API ensures that the OTP is sent through the second channel. If the second channel fails, it will go to the next channel until it succeeds.

Note:

  • Few elements in the endpoint may change from service to service.
  • Users should create a configuration in the Verify>Configuration Setup section of the Thundersms to send an OTP.
Authorizations:
bearerAuth
Request Body schema: application/json
One of
required
Array of objects

An array of objects containing the details of the channels to send the verification message.

object

Details of the verification payload.

Responses

Request samples

Content type
application/json
Example
{
  • "channels": [
    ],
  • "payload": {
    }
}

Response samples

Content type
application/json
Example
{
  • "id": "165c6d56-c767-4f1b-bce2-6562001876c0",
  • "status": "sent",
  • "to": null,
  • "foreign_id": null,
  • "created_at": "2022-11-25 08:59:52",
  • "expire_at": "2022-11-25 09:01:32"
}

Send OTP using Omnichannel

This endpoint makes an HTTP POST request to send the OTP using omnichannel.

Note: Before sending OTPs using this API, ensure you have created an omnichannel profile and added channels to the profile. This profile configuration determines the channels through which the OTP will be sent. Refer to Create Omnichannel Profile and Add Channels to Omnichannel Profile APIs.

Authorizations:
bearerAuth
Request Body schema: application/json
profile
required
string

Specifies the sender's profile. Visit Create Profile to create a profile.

required
object

Details of the recipient.

object

Details of the verification payload.

Responses

Request samples

Content type
application/json
{
  • "profile": "Demo",
  • "recipient": {
    },
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "id": "0c7ef79d-b7d8-4e27-b799-35ef07889a5e",
  • "status": "sent",
  • "foreign_id": "123456",
  • "created_at": "2024-05-16 16:13:40",
  • "expire_at": "2024-05-16 16:14:10"
}

OTP Token Management

Verify OTP

This endpoint makes an HTTP GET request to verify the status of a token associated with a specific ID. The request should include the ID and token as part of the URL parameters. This API allows you to verify the status of a token sent through SMS, WhatsApp, Engage, and Viber.

To verify a sent verification token, follow these steps:

  • Send the verification code provided by your user along with the corresponding id from the initial verification request.
  • Check the status of the response to verify if the code provided by the user matches the one sent by CPaaS Alerts.

Note:

  • This process can only be performed once for each token, ensuring the integrity of the verification system.
  • Few elements in the endpoint may change from service to service.

Failure Codes

Code Status Description
401 Unauthenticated Authentication Error
200 failed When you passed an invalid id value
200 expired token expired
200 invalid When you passed the wrong token for verification
200 OTP already verified When you have already verified the OTP.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{otp_id}}

Created OTP ID from send OTP.

token
required
string
Example: {{token}}

The verification code entered by your user.

Responses

Response samples

Content type
application/json
Example
{
  • "id": "9f6eb820-5580-4f5f-a7d3-2389ed09f87f",
  • "status": "success"
}

Search OTP Token

This endpoint makes an HTTP GET request to verify and search for a specific ID sent through SMS, WhatsApp, Engage, and Viber.

To check the status of past or current verification requests:

  • Send a Verify Search request containing the id of the verification requests you are interested in.

  • Check the status of the response to determine if the code the user supplied matches the one sent by CPaaS Alerts.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{otp_id}}

The verify request to check. The id you received in response to the verify request.

Responses

Response samples

Content type
application/json
Example
{
  • "id": "b452fe89-b6b1-4f51-8490-7502440bf08f",
  • "to": null,
  • "reference": null,
  • "status": "success",
  • "created_at": "2022-11-25 09:03:18",
  • "expire_at": "2022-11-25 09:04:58",
  • "channels": [
    ]
}

Cancel OTP Token

This endpoint makes an HTTP GET request to cancel a existing verify request for a specific ID.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{otp_id}}

The verify request to check. The id you received in response to the verify request.

Responses

Response samples

Content type
application/json
Example
{
  • "id": "757db49e-78ee-4ded-898a-8e538aa7c1c9",
  • "status": "success"
}

Overview

Create engaging one-to-one interactions on your customers favourite messaging application with images, video, and file sharing for a convenient and memorable experience.

The Viber business messages API allows you to send verified transactional and promotional messages to users from your business account.

Supported Viber versions for users: To receive a business message, a user must have the following versions (or higher) of Viber installed:

  1. Android 5.4
  2. iOS 5.3

Template Message

Template messages are transactional messages sent by a service based on a predefined message structure. Currently, templates are open to Russia, Ukraine, and Belarus only. When a service sends messages in any country that supports templates, a transactional rate will be applied only when all of the following conditions are met:

  • The message is sent according to a structure that was approved by the Viber team for the specific service, and the template is in active status. The template approval process is done through the Commercial Account Management Portal (CAMP).
  • One of the template message types (301, 303, or 304) is used in the message request. Sending with these types triggers a matching mechanism, which checks the message text to match a template out of the templates that were uploaded for the service ID.

Template Matching

The Viber template matching process uses official regex libraries and follows official regex rules. There are a few exceptions that relate to the cleaning process, which we added to improve the template matching performance. In the event of an exception, the algorithm will mark the template as invalid and won’t upload it to the system.

Note: Templates for Belarus, Ukraine, and Russia need to be pre-approved by Viber.

Status Info

Name Description
queued A message has been received and queued by the Our Viber API.
sent A message has been sent by Viber to the end user
delivered A message has been successfully delivered to the end user by Viber.
read A message has been read by the end user in the Viber application.
expired A message has been deleted or expired in the application.
failed A message has failed.

Template

View All Templates

This endpoint makes an HTTP GET request to retrieve Viber templates created under your account. The response will include the details of the Viber templates available.

Authorizations:
bearerAuth
query Parameters
filter[id]
string

ID of the template.

filter[name]
string

Name of the template.

filter[type]
string
Value: "text"

Type of the template.

filter[status]
string
Enum: "1" "2" "3"

Status of the template. (1 is approved), (2 is pending), and (3 is rejected).

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "Templates List",
  • "meta": {
    },
  • "status": "OK"
}

Create Template

This API provides various options for creating Viber templates.

Templates can be created as required using the methods provided below:

Method Description
Transaction text This API allows you to create a template for transactional text messages.
Transaction file With this API, you can generate a template for transactional messages containing files.
Session text This API enables the creation of a template for text-based session messages, ensuring adherence to predefined structures for consistent session communication.
Session file You can use this API to generate a template for session messages containing file attachments, ensuring standardized and verified session-based interactions.
Session image This API facilitates the creation of templates for session messages containing image attachments, ensuring structured and verified session-based communication.
Promotional video You can utilize this API to create templates for promotional messages containing video content, ensuring consistent and verified promotional communication.
Promotional image This API allows you to generate templates for promotional messages containing image content, ensuring structured and verified promotional communication.
Promotional image text button You can use this API to create templates for promotional messages containing images and text buttons.
Promotional video text This API enables you to generate templates for promotional messages containing video content and text.
Promotional text button You can utilize this API to create templates for promotional messages containing text buttons.
Promotional video text button This API allows you to generate templates for promotional messages containing video content and text buttons.
Authorizations:
bearerAuth
Request Body schema: application/json
One of
One of
name
required
string

Template name without space.

category
required
string
Value: "transactional"

The category of the template.

required
object

Contains message information

Responses

Request samples

Content type
application/json
Example
{
  • "category": "transactional",
  • "message": {
    },
  • "name": "transactional_text_msg"
}

Response samples

Content type
application/json
Example
{
  • "status": "OK",
  • "code": 200,
  • "message": "Template created successfully.",
  • "data": {
    }
}

View Template by ID

This endpoint makes an HTTP GET request to retrieve details of a specific Viber template by its ID. The response will include the ID, name, alias, type, category, payload, status, creation timestamp, and last update timestamp of the template.

Note:

  • Kindly replace the token with your respective access_token.
  • Few elements in the endpoint may change from service to service.
  • Replace the {id} in the endpoint with the actual ID of the template you want to see.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{viber_template_id}}

ID of the template.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Templates List",
  • "status": "OK"
}

Edit Template

This endpoint allows the you to edit a Viber template by sending an HTTP PUT request to the specified endpoint.

Note:

  • Replace the {id} in the endpoint with the actual ID of the template you want to edit.
  • Few elements in the endpoint may change from service to service.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{viber_template_id}}

ID of the template.

Request Body schema: application/json
category
required
string
Enum: "transactional" "promotional" "session"

The category of the template.

required
object

Contains message information.

name
required
string

The template name that has been created (unchangeable).

Responses

Request samples

Content type
application/json
{
  • "category": "transactional",
  • "message": {
    },
  • "name": "video_text_button_msg_5"
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Template updated successfully.",
  • "status": "OK"
}

Delete Template

This endpoint sends an HTTP DELETE request to delete a Viber template with the specified ID.

Note:

  • Replace the {id} in the endpoint with the actual ID of the template you want to delete.
  • Few elements in the endpoint may change from service to service.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{viber_template_id}}

ID of the template.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "message": "Template Successfully Deleted",
  • "status": "OK"
}

Unsubscriber

View All Unsubscribers

This endpoint makes an HTTP GET request to retrieve a list of unsubscribers from the Viber suppressions. The response will contain the details of the unsubscribed phone numbers.

Note:

  • Kindly replace the token with your respective access_token and other parameters.
  • Few elements in the endpoint may change from service to service.
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "Unsubscribers list",
  • "meta": {
    },
  • "status": "OK"
}

Create Unsubscriber

This endpoint allows you to add an unsubscriber to the list of unsubscribers for Viber communications.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth
Request Body schema: application/json
receiver
required
string

Enter the receiver that you want to add.

type
string
Enum: "tag" "category" "account" "all"

Type of the receiver

value
string

Enter the value of the type.

Responses

Request samples

Content type
application/json
{
  • "receiver": "9176xxxxxxxx",
  • "type": "tag",
  • "value": "tag1"
}

Response samples

Content type
application/json
Example
{
  • "code": 200,
  • "data": {
    },
  • "message": "Receiver added successfully",
  • "status": "OK"
}

Clean Unsubscribers

This HTTP DELETE request is used to remove all unsubscribers from the Viber suppression list.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "message": "Deleted Successfully",
  • "status": "OK"
}

View Unsubscriber by ID

This endpoint retrieves information about a specific Viber unsubscriber by ID. The response will include the ID, country ISO code, receiver number, type, value, and the creation timestamp of the unsubscriber data.

Note:

  • Kindly replace the token with your respective access_token.
  • Few elements in the endpoint may change from service to service.
  • Replace the {id} in the endpoint with the actual ID of the unsubscriber you want to see.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{viber_optout_id}}

The Viber unsubscription ID.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Unsubscribers data",
  • "status": "OK"
}

Edit Unsubscriber

This endpoint allows you to update the details of an unsubscriber by making an HTTP PUT request to the specified endpoint.

Note:

  • Few elements in the endpoint may change from service to service.
  • Replace the {id} in the endpoint with the actual ID of the unsubscriber you want to edit.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{viber_optout_id}}

The Viber unsubscription ID.

Request Body schema: application/json
receiver
required
string

Enter the receiver that you want to edit.

type
string
Enum: "tag" "category" "account" "all"

Type of the receiver

value
string

Enter the value of the type.

Responses

Request samples

Content type
application/json
{
  • "receiver": "9176xxxxxxxx",
  • "type": "tag",
  • "value": ""
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Receiver update successfully",
  • "status": "OK"
}

Delete Unsubscriber

This API endpoint sends an HTTP DELETE request to remove a specific unsubscriber from the list of Viber suppressions.

Note:

  • Few elements in the endpoint may change from service to service.
  • Replace the {id} in the endpoint with the actual ID of the unsubscriber you want to delete.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{viber_optout_id}}

The Viber unsubscription ID.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "message": "Deleted Successfully",
  • "status": "OK"
}

Import Unsubscriber

This API endpoint allows you to import unsubscribers for Viber suppression by uploading a file.

Note: Few elements in the endpoint may change from service to service.

Request Parameter

Parameter Description Limit Required
file File containing unsubscriber numbers. (Supported file types: txt, csv, xls, xlsx) 100 MB Yes
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "message": "Receivers accepted for import",
  • "status": "OK"
}

Send Viber Message

Send Non-Template Message

This API provides various options available for sending non-template Viber message. You can send the non-template Viber message in the below-mentioned ways:

Option Description
Send text message This API enables you to send simple text messages.
Send video message This API empowers you to send video messages seamlessly, allowing for rich multimedia communication.
Send image message With this API, you can send image messages effortlessly, facilitating visual communication.
Send file message This API allows you to send a document that has a valid MIME type as an attachment. So anything not an image, audio, or video will be transmitted as a document message.
Send image with text and button message You can send comprehensive messages comprising images, text, and actionable buttons using this API, enhancing engagement and interaction.
Send image with text message This API allows you to send messages containing both images and accompanying text.
Send text with button message With this API, you can send text messages along with interactive buttons, facilitating user engagement and response.
Send video with text and button message This API empowers you to send multimedia messages containing videos, text, and actionable buttons, enabling dynamic communication.
Send video with text message You can use this API to send messages combining videos and text, enabling rich multimedia communication experiences.
Send session text message You can use this API to send text messages within a session context, maintaining continuity and coherence in conversations.
Send session image message This API enables the sending of image messages within a session, enhancing the visual aspect of ongoing conversations.

Note:

  • Few elements in the endpoint may change from service to service.
  • The recipient block inside the channel is related to a particular communication channel, and it is optional. The outside recipient channel contains common recipients for every channel.
Authorizations:
bearerAuth
Request Body schema: application/json
One of
required
Array of objects

Specifies the communication channel through which the message will be sent.

object

The message details.

required
object

Specifies the recipient of the message

Responses

Request samples

Content type
application/json
Example
{
  • "channels": [
    ],
  • "message": {
    },
  • "recipient": {
    }
}

Response samples

Content type
application/json
Example
{
  • "data": [
    ],
  • "message": "Messages queued successfully",
  • "status": "OK"
}

Send Template Message

This API endpoint makes an HTTP POST request to send a Viber message using a template. You can send messages using the template alias name or template id of the predefined template created in your account to specified recipients.

Example Template:

Dear {{name}}, Thanks for registering with us. Your details as follows {{email}}, {{phone}}.

Note: When sending a message, ensure that the data is passed into the data payload. Then the content will be automatically replaced within the template.

Output Message:

Dear Demo, Thanks for regisitering with us. Your details as follows demoxxxx@gmail.com, 9189XXXXXXXX.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth
Request Body schema: application/json
alias
required
string

An alias of the registered template. (Required if id is not present)

id
required
string

ID of the registered template. (Required if alias is not present)

required
object

Variable values for replacing in template content.

required
object

Additional metadata for the Viber message.

required
object

This block contains contact information.

Responses

Request samples

Content type
application/json
{
  • "alias": "template-name",
  • "recipient": {
    },
  • "data": {
    },
  • "meta": {
    }
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "message": "Messages queued successfully",
  • "status": "OK"
}

DLR Status

Pull DLR Status

This endpoint allows you to retrieve the status of a Viber message by providing the Viber ID as a query parameter.

you can pass any of the query parameters to get the DLR response.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth
query Parameters
id
string
Example: id={{message_id}}

Message ID we have given in response

mobile
string

Mobile number with country code

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "message": "OK",
  • "status": "OK"
}

Pricing

View Pricing

This endpoint makes an HTTP GET request to retrieve the pricing information for Viber services. The response will contain details about the pricing for various Viber services and all country-wise pricing lists.

Note:

  • Few elements in the endpoint may change from service to service.
  • Kindly replace the token with your respective access_token and other parameters.
Authorizations:
bearerAuth
query Parameters
filter[iso]
string

The ISO code of the country. (e.g., IN, AF, etc.)

filter[service]
string

The short code of the service name. Refer to Products/Services

filter[subservice]
string

The short code of the service name. Refer to Products/Services

filter[status]
number
Enum: "0" "1"

Status of the Viber messages.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "Pricing List",
  • "meta": {
    },
  • "status": "OK"
}

Overview

To get started with WhatsApp, please first review the WhatsApp commerce policy, which determines which businesses are allowed onto the WhatsApp Business Platform.

Status Info

Name Description
queued A message has been received and queued by our WhatsApp API.
dispatched A message has been dispatched by our WhatsApp API to WhatsApp servers.
sent A message has been sent by WhatsApp to the end user.
delivered A message has been successfully delivered to the end-user by WhatsApp.
read A message has been read by the end-user in the WhatsApp application.
deleted A message has been deleted or expired in the application.
failed The message has failed.

Template

View All Templates

This endpoint makes an HTTP GET request to retrieve a list of WhatsApp templates available. The response will include information about the templates, such as their names, IDs, and other relevant details.

Note: Kindly replace the token with your respective access_token and other parameters.

Authorizations:
bearerAuth
query Parameters
filter[id]
string

ID of the template.

filter[name]
string

Name of the template.

filter[type]
string
Enum: "text" "JSON" "media" "template"

Type of the template.

filter[status]
string
Enum: "1" "2" "3"

Status of the template. (1 is approved), (2 is pending), and (3 is rejected).

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "Templates List",
  • "meta": {
    },
  • "status": "OK"
}

Create Template

This API provides various options for creating WhatsApp templates. You can create a template for service and non-service.

Type Description
Service (is_conversation=true) Approval is not required from Meta (operator).
Non-service (is_conversation=false) Approval is required from Meta (operator).

Templates can be created as required using the methods provided below:

Method Type Description
Create template with type text Service This API enables the creation of templates using text as the primary content type.
Create template with type JSON Service This API facilitates the creation of templates using the JSON (JavaScript Object Notation) format.
Create media type with image Service This API allows you to create WhatsApp templates enriched with image media.
Create media type with video Service This API enables the creation of WhatsApp templates featuring video content.
Create media type with audio Service This API facilitates the creation of WhatsApp templates that include audio media.
Create media type with document Service This API enables the integration of document files into WhatsApp templates.
Create template with button type text Non-service This API enables the creation of WhatsApp templates that include text content along with interactive buttons. You can design messages that incorporate clickable buttons alongside text.
Create template with reply type text Non-service This API allows you to generate WhatsApp templates that prompt recipients to respond with text messages.
Create template with image button Non-service This API facilitates the creation of WhatsApp templates incorporating both images and interactive buttons. You can design messages that combine visually engaging images with clickable buttons.
Create template with reply type image Non-service This API allows you to create WhatsApp templates that prompt recipients to reply using images.
Create template with video button Non-service This API allows you to generate WhatsApp templates featuring video content along with interactive buttons. You can design messages that combine engaging video content with clickable buttons.
Create template with reply type video Non-service This API allows you to create WhatsApp templates that prompt recipients to respond using videos.
Create template with document button Non-service This API allows you to generate WhatsApp templates that include document files alongside interactive buttons. Users can design messages that combine informative document content with clickable buttons.
Create template with reply type document Non-service This API facilitates the creation of WhatsApp templates that prompt recipients to respond with documents.
Create template with authentication type copy code Non-service This API enables you to design WhatsApp templates with authentication functionality using a copy-code method. It allows users to generate messages that prompt recipients to copy a unique authentication code.

Note: Pass variables in {{}}. Variable names should be different; for example, {{name}}, {{email}}

Authorizations:
bearerAuth
Request Body schema: application/json
One of
One of
category
required
string
Enum: "marketing" "utility"

The category of the template.

is_conversation
required
boolean
Value: "true"

The type of template (service or non-service).

language
required
string
Enum: "en" "en_US"

The language of the template.

name
required
string <template_name>

Name of the template without space.

number
required
string

Business number with a country code prefix.

object

Payload of the template.

type
required
string
Value: "text"

The type of the template.

Responses

Request samples

Content type
application/json
Example
{
  • "category": "marketing",
  • "is_conversation": true,
  • "language": "en",
  • "name": "text_template_msg_var",
  • "number": "{{from}}",
  • "payload": {
    },
  • "type": "text"
}

Response samples

Content type
application/json
Example
{
  • "code": 200,
  • "data": {
    },
  • "message": "Template created successfully.",
  • "status": "OK"
}

Delete Template

This endpoint sends an HTTP DELETE request to delete a specific WhatsApp template by ID.

Note: Replace the {id} in the endpoint with the actual ID of the template you want to delete.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{whatsap_Istemplate_id}}

ID of the template.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "message": "Template Successfully Deleted",
  • "status": "OK"
}

Unsubscriber

View All Unsubscribers

This endpoint makes an HTTP GET request to retrieve a list of unsubscribers for WhatsApp suppressions.

Note:

  • Few elements in the endpoint may change from service to service.
  • Kindly replace the token with your respective access_token and other parameters.
Authorizations:
bearerAuth
query Parameters
filter[id]
string

The WhatsApp unsubscription ID.

filter[iso]
string

The ISO code of the country. (e.g., IN, AF, etc.)

filter[receiver]
string

The unsubscribed mobile number.

filter[type]
string
Enum: "tag" "sender" "service"

Type of unsubscription

filter[value]
string

Value for any of the given type.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "Unsubscribers list",
  • "meta": {
    },
  • "status": "OK"
}

Create Unsubscriber

This endpoint allows you to add an unsubscriber to the list of unsubscribers for WhatsApp notifications.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth
Request Body schema: application/json
receiver
required
string

Enter the receiver that you want to add.

type
string
Enum: "tag" "product" "sender" "all"

Type of the receiver

value
string

Enter the value of the type.

Responses

Request samples

Content type
application/json
{
  • "receiver": "9176xxxxxxxx",
  • "type": "tag",
  • "value": "tag1"
}

Response samples

Content type
application/json
Example
{
  • "code": 200,
  • "data": {
    },
  • "message": "Receiver added successfully",
  • "status": "OK"
}

Clean Unsubscribers

This HTTP DELETE request is used to remove all unsubscribers from the WhatsApp suppression list.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "message": "Deleted Successfully",
  • "status": "OK"
}

View Unsubscriber by ID

This endpoint retrieves the details of a specific WhatsApp unsubscriber by ID. The response will include the ID, ISO country code, receiver phone number, type, value, and the creation timestamp of the unsubscriber data.

Note:

  • Few elements in the endpoint may change from service to service.
  • Kindly replace the token with your respective access_token.
  • Replace the {id} in the endpoint with the actual ID of the unsubscriber you want to see.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{sms_optout_id}}

The WhatsApp unsubscription ID.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Unsubscribers data",
  • "status": "OK"
}

Edit Unsubscriber

This endpoint allows you to update the details of an unsubscriber by making an HTTP PUT request to the specified endpoint.

Note:

  • Few elements in the endpoint may change from service to service.
  • Replace the {id} in the endpoint with the actual ID of the unsubscriber you want to edit.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{sms_optout_id}}

The WhatsApp unsubscription ID.

Request Body schema: application/json
receiver
required
string

Enter the receiver that you want to edit.

type
string
Enum: "tag" "product" "sender" "all"

Type of the receiver

value
string

Enter the value of the type.

Responses

Request samples

Content type
application/json
{
  • "receiver": "9176xxxxxxxx",
  • "type": "tag",
  • "value": ""
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Receiver update successfully",
  • "status": "OK"
}

Delete Unsubscriber

This HTTP DELETE request is used to remove a specific unsubscriber from the list of WhatsApp suppressions.

Note:

  • Few elements in the endpoint may change from service to service.
  • Replace the {id} in the endpoint with the actual ID of the unsubscriber you want to delete.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{sms_optout_id}}

The WhatsApp unsubscription ID.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "message": "Deleted Successfully",
  • "status": "OK"
}

Import Unsubscriber

This API endpoint allows you to import unsubscribers for WhatsApp suppression by uploading a file.

Note: Few elements in the endpoint may change from service to service.

Request Parameter

Parameter Description Limit Required
file File containing unsubscriber numbers. (Supported file types: txt, csv, xls, xlsx) 100 MB Yes
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "message": "Receivers accepted for import",
  • "status": "OK"
}

Send Whatsapp Message

Send Template Message - Service

This API endpoint makes an HTTP POST request to send a WhatsApp message using a service template. You can send messages using the template alias name or template id of the predefined template created in your account to specified recipients.

Note:

  • For sending a service template message, approval is not required from Meta (operator).
  • Few elements in the endpoint may change from service to service.

Example Template:

Dear {{name}}, Thanks for registering with us. Your details as follows {{email}}, {{phone}}.

Note: When sending a message, ensure that the data is passed into the data payload. Then the content will be automatically replaced within the template.

Output Message:

Dear Demo, Thanks for regisitering with us. Your details as follows demoxxxx@gmail.com, 9176XXXXXXXX.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth
Request Body schema: application/json
alias
required
string

An alias of the registered template. (Required if id is not present)

id
required
string

ID of the registered template. (Required if alias is not present)

object

Additional metadata for the WhatsApp message.

required
object

Variable values for replacing in template content.

required
object

This block contains contact information.

Responses

Request samples

Content type
application/json
{
  • "alias": "funny_video_2",
  • "meta": {
    },
  • "recipient": {
    },
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "message": "Messages queued successfully",
  • "status": "OK"
}

Message Sending Options

This API provides various options available for sending WhatsApp messages and allows you to send a WhatsApp message using a non-service template through its endpoint.

You can send the WhatsApp messages in the below-mentioned ways:

Option Type Description
Send text message Service This API enables you to send text messages through WhatsApp.
Send template message Non-service This API enables you to send template-based messages through WhatsApp. For sending a non - service template message, approval is required from Meta (operator).
Send document message Service This API allows you to send a document that has a valid MIME type as an attachment. So anything not an image, audio, or video will be transmitted as a document message. Max file size: 100MB.
Send image message Service This API enables you to send images through the WhatsApp messaging platform effortlessly. Max file size: 5MB. Supported formats: jpg, jpeg, png.
Send audio message Service This API enables you to send audio files seamlessly through the WhatsApp messaging platform. Max file size: 16MB. Supported formats: audio/aac, audio/mp4, audio/amr, audio/mpeg, codecs=opus. (The base audio/ogg type is not supported.)
Send video message Service This API allows you to effortlessly share video content through the WhatsApp messaging platform. Max file size: 16MB. Supported formats: video/mp4, video/3gpp (only H.264 video codec and AAC audio codec is supported).
Send interactive choice list Service This API enables you to create and send interactive choice lists through the WhatsApp messaging platform, enabling engaging and dynamic conversations with recipients.
Send interactive choice buttons Service This API facilitates the creation and delivery of interactive choice buttons through the WhatsApp messaging platform, empowering you to engage recipients in dynamic conversations and prompt them to make selections based on predefined options.
Send location message Service This API empowers you to send location-based messages through the WhatsApp messaging platform, enabling the sharing of geographic coordinates, addresses, and other location-related information with recipients.
Send contact message Service This API enables you to share contact details through the WhatsApp messaging platform.
Send authentication template message Non-service This API serves as a template for generating authentication messages through the WhatsApp channel. It provides a structured framework to create and send authentication messages.
Send template message with document header and body replacement Non-service This API facilitates the creation and sending of structured messages through the WhatsApp channel. Specifically, it serves as a template for constructing messages that contain a header with document information and a customizable body.
Send template message with image header and body replacement Non-service This API facilitates the creation and sending of structured messages through the WhatsApp channel. It provides a predefined message template that includes sections for both the header and body sections, allowing for dynamic replacement of content, particularly images.
Send template message with text header and body replacement Non-service This API is designed to facilitate the dynamic creation and sharing of structured messages. It provides a template that consists of sections for both the header and the body of the message, allowing for personalized content insertion.
Send template message with video header and body replacement Non-service This API facilitates the dynamic creation and sending of video messages through WhatsApp. It provides a predefined template with sections for both the header and the body, allowing for easy replacement of placeholders with personalized content.
Send non-variable template message Non-service This API enables a straightforward method to send template messages through WhatsApp without the need for variable replacement. It provides a predefined template structure that remains constant across multiple message instances.

Note:

  • Few elements in the endpoint may change from service to service.
  • The recipient block inside the channel is related to a particular communication channel, and it is optional. The outside recipient channel contains common recipients for every channel.
  • If you have included any variables in both the body and header during template creation, ensure that you include the corresponding body_params and header_params when sending the WhatsApp non-service template message.
Authorizations:
bearerAuth
Request Body schema: application/json
One of
One of
required
Array of objects

Specifies the communication channel through which the message will be sent.

object

The message details.

required
object

Specifies the recipient of the message.

Responses

Request samples

Content type
application/json
Example
{
  • "channels": [
    ],
  • "message": {
    },
  • "recipient": {
    }
}

Response samples

Content type
application/json
Example
{
  • "data": [
    ],
  • "message": "Messages queued successfully",
  • "status": "OK"
}

DLR Status

Pull DLR Status

This endpoint allows you to retrieve the status of a WhatsApp message by providing the WhatsApp ID as a query parameter.

you can pass any of the query parameters to get the DLR response.

Note: Few elements in the endpoint may change from service to service.

Authorizations:
bearerAuth
query Parameters
id
string
Example: id={{whatsapp_id}}

Message ID we have given in response

mobile
string

Mobile number with country code

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "message": "OK",
  • "status": "OK"
}

Pricing

View Pricing

This endpoint makes an HTTP GET request to retrieve the pricing information for WhatsApp services. The response will contain details about the pricing for various WhatsApp services and all country-wise pricing lists.

Note:

  • Few elements in the endpoint may change from service to service.
  • Kindly replace the token with your respective access_token and other parameters.
Authorizations:
bearerAuth
query Parameters
filter[iso]
string

The ISO code of the country. (e.g., IN, AF, etc.)

filter[service]
string

The short code of the service name. Refer to Products/Services.

filter[subservice]
string

The short code of the service name. Refer to Products/Services.

filter[status]
string
Enum: "0" "1"

Status of the WhatsApp messages.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "Pricing List",
  • "meta": {
    },
  • "status": "OK"
}

Overview

Account management APIs enable you to check your account balance and add credits to your profile, facilitating seamless management of financial resources within the platform.

Account

Check Account Balance

This endpoint makes an HTTP GET request to retrieve the current balance for the finance account.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "OK",
  • "status": "OK"
}

Add Credits to Customer

This API allows you to add credits to your account balance, allowing you to keep using Thundersms services.

Authorizations:
bearerAuth
Request Body schema: application/json
credits
required
string

Indicates the amount of credit that needs to be added to the user's account.

service
string

The short code of the service name. Refer to Products/Services.

username
required
string

The unique identifier for the user.

Responses

Request samples

Content type
application/json
{
  • "credits": "2.34",
  • "service": "",
  • "username": "reseller"
}

Response samples

Content type
application/json
{
  • "status": "OK",
  • "message": "Balance added Successfully"
}

Overview

Contacts are the lifeblood of the Thundersms API ecosystem, managing contacts efficiently is paramount to delivering effective communication services. This chapter provides a comprehensive guide to navigating various aspects of contact management within the Thundersms platform.

Subscribers

Get All Contacts

This HTTP GET request retrieves a list of contacts from the specified endpoint. The response will include the details of the contacts, such as their names, contact information, and any other relevant information.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "meta": {
    },
  • "status": "OK",
  • "message": "OK"
}

Create Contact

This endpoint allows you to create a new contact by providing the contact details such as identity, email, phone, postal code, birth date, first name, last name, gender, attributes, and tags.

Authorizations:
bearerAuth
Request Body schema: application/json
object

Additional attributes of the contact.

birth_date
string <yyyy-mm-dd>

The birth date of the contact.

email
string

The email address of the contact.

first_name
string

The first name of the contact.

gender
string
Enum: "male" "female"

The gender of the contact.

identity
required
string

Enter the contact's identity without spaces.

last_name
string

The last name of the contact.

company
string

The company of the contact.

country
string

Country of the contact.

region
string

Region of the contact.

city
string

City of the contact.

locality
string

Locality of the contact.

phone
required
string

The phone number of the contact.

postal_code
string

The postal code of the contact.

tags
Array of strings

Tags associated with the contact.

Responses

Request samples

Content type
application/json
{
  • "identity": "Fayek",
  • "email": "madhu@gmail.com",
  • "phone": "+6590296448",
  • "postal_code": "547008",
  • "birth_date": "1994-03-16",
  • "first_name": "madhu",
  • "last_name": "BS",
  • "gender": "female",
  • "company": "",
  • "country": "ABC",
  • "city": "ABC",
  • "region": "ABC",
  • "locality": "",
  • "attributes": {
    },
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Subscriber created successfully",
  • "status": "OK"
}

View Contact by ID

This API endpoint retrieves the details of a specific contact identified by the provided ID. The request should be made using the HTTP GET method to the specified endpoint.

Note:

  • Few elements in the endpoint may change from service to service.
  • Replace the {id} in the endpoint with the actual ID of the contact you want to see.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{contact_id}}

ID received upon contact creation.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "OK",
  • "status": "OK"
}

Edit Contact

This endpoint allows you to update contact information for a specific contact identified by the provided ID.

Note:

  • Few elements in the endpoint may change from service to service.
  • Replace the {id} in the endpoint with the actual ID of the contact you want to edit.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{contact_id}}

ID received upon contact creation.

Request Body schema: application/json
object

Additional attributes of the contact.

first_name
string

The first name of the contact.

last_name
string

The last name of the contact.

company
string

Company of the contact.

country
string

Country of the contact.

region
string

Region of the contact.

city
string

City of the contact.

locality
string

Locality of the contact.

postal_code
string

Postal code of the contact.

tags
Array of strings

Tags associated with the contact.

Responses

Request samples

Content type
application/json
{
  • "first_name": "ABC",
  • "last_name": "B S",
  • "company": "ABC",
  • "country": "ABC",
  • "region": "ABC",
  • "city": "ABC",
  • "locality": "abc",
  • "postal_code": "123",
  • "attributes": {
    },
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Subscriber updated successfully",
  • "status": "OK"
}

Delete Contact

This HTTP DELETE request is used to delete a specific contact by its ID.

Note:

  • Replace the {id} in the endpoint with the actual ID of the contact you want to delete.
  • Few elements in the endpoint may change from service to service.
Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{contact_id}}

ID received upon contact creation.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "message": "Subscriber deleted successfully",
  • "status": "OK"
}

Get All Contact Identifiers

This endpoint makes an HTTP GET request to retrieve the identifiers associated with a specific contact ID. The response includes a status, code, message, data array containing identifier details such as ID, type, value, creation and update timestamps, links for pagination, and metadata providing information about the current page, total number of identifiers, and pagination links.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{contact_id}}

ID of the contact.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "OK",
  • "meta": {
    },
  • "status": "OK"
}

Add Identifier to an Existing Contact

This endpoint allows you to add identifiers for a specific contact by making an HTTP POST request to the specified URL.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{contact_id}}

ID of the contact.

Request Body schema: application/json
type
required
string

The type of identifier.

value
required
string

The value of the identifier.

Responses

Request samples

Content type
application/json
{
  • "type": "phone",
  • "value": "hello123@gmail.com"
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "OK",
  • "status": "OK"
}

Get Specific Identifier of a Contact

This endpoint retrieves the details of a specific identifier for a contact. It makes an HTTP GET request to the specified endpoint with the contact ID and identifier ID as parameters.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{contact_id}}

ID of the contact

iId
required
string
Example: {{identifier_id}}

ID of the identifier

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "OK",
  • "status": "OK"
}

Edit Identifier

This endpoint allows you to update the identifier for a specific contact.

Authorizations:
bearerAuth
path Parameters
cId
required
string
Example: {{contact_id}}

The ID of the contact.

iId
required
string
Example: {{Em_identifier_id}}

The ID of the identifier to be updated.

Request Body schema: application/json
type
required
string

The type of the identifier.

value
required
string

The new value for the identifier.

Responses

Request samples

Content type
application/json
{
  • "type": "email",
  • "value": "hey126@gmail.com"
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Identifier updated successfully",
  • "status": "OK"
}

Delete Identifier from Contact

This endpoint sends an HTTP DELETE request to delete a specific identifier associated with a contact.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{contact_id}}

The unique identifier of the contact.

Iid
required
string
Example: {{Em_identifier_id}}

The unique identifier of the contact's identifier.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "message": "Identifier deleted successfully",
  • "status": "OK"
}

Tags

Get All Tags

This endpoint makes an HTTP GET request to retrieve the tags associated with contacts.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "OK",
  • "meta": {
    },
  • "status": "OK"
}

Create Tag

This endpoint is used to create a new tag for contacts.

Authorizations:
bearerAuth
Request Body schema: application/json
name
required
string

The name of the tag to be added.

Responses

Request samples

Content type
application/json
{
  • "name": "premium 1"
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Tag created successfully",
  • "status": "OK"
}

Get Tag by ID

This endpoint retrieves the details of a specific contact tag identified by the provided ID.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{tag_id}}

ID of the tag

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "OK",
  • "status": "OK"
}

Edit Tag

This endpoint allows you to update a specific contact tag by providing the tag ID.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{tag_id}}

ID of the tag

Request Body schema: application/json
name
required
string

The new name for the contact tag.

Responses

Request samples

Content type
application/json
{
  • "name": "tag11"
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Tag updated successfully",
  • "status": "OK"
}

Delete Tag

This endpoint allows the deletion of a specific contact tag identified by the provided ID.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{tag_id}}

ID of the tag

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "message": "Tag deleted successfully",
  • "status": "OK"
}

Segments

Get All Segments

This endpoint makes an HTTP GET request to retrieve a list of contact segments.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "message": "OK",
  • "status": 200
}

Create Segment

This endpoint allows you to create a new contact segment by sending an HTTP POST method.

Authorizations:
bearerAuth
Request Body schema: application/json
name
required
string

The name of the contact segment.

Responses

Request samples

Content type
application/json
{
  • "name": "segment1"
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Segment created successfully",
  • "status": "OK"
}

Get Segment by ID

This endpoint makes an HTTP GET request to retrieve the details of a specific contact segment based on the provided ID.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{segment_id}}

The ID of the contact segment.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "OK",
  • "status": "OK"
}

Edit Segment

This endpoint allows you to update a specific contact segment details by making an HTTP PUT request to the specified endpoint.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{segment_id}}

The ID of the contact segment.

Request Body schema: application/json
name
required
string

The name of the contact segment.

negative_tags
required
Array of strings

List of negative tags.

negative_tags_operator
required
string

The operator for negative tags.

positive_tags
required
Array of strings

List of positive tags.

positive_tags_operator
required
string

The operator for positive tags.

Responses

Request samples

Content type
application/json
{
  • "name": "segment1",
  • "negative_tags": [
    ],
  • "negative_tags_operator": "any",
  • "positive_tags": [
    ],
  • "positive_tags_operator": "any"
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "Segment updated successfully",
  • "status": "OK"
}

Delete Segment

This endpoint sends an HTTP DELETE request to delete a specific contact segment.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{segment_id}}

The ID of the contact segment.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "message": "Segment deleted successfully",
  • "status": "OK"
}

Get Segment Subscribers

This endpoint makes an HTTP GET request to retrieve the subscribers of a specific segment identified by the provided ID.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{segment_id}}

The unique identifier of the segment.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "Subscription is 100 % of the total of 2 subscribers",
  • "meta": {
    },
  • "status": "OK"
}

Bulk Import

Get All Subscriber Imports

This endpoint makes an HTTP GET request to retrieve the imported subscribers information.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "OK",
  • "meta": {
    },
  • "status": "OK"
}

Import Subscribers

This endpoint allows you to import subscribers into the contacts list.

Request Parameter

Parameter Description Limit Required
file File containing subscriber numbers. (Supported file types: txt, csv, xls, xlsx) 5 MB Yes
Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
Example
{
  • "code": 200,
  • "data": {
    },
  • "message": "2 subscriber(s) imported successfully",
  • "status": "OK"
}

Get Subscriber Import by ID

This endpoint is used to retrieve the details of imported subscribers for a specific contact.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{import_sub_id}}

The ID of the imported subscribers.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "message": "OK",
  • "status": "OK"
}

Delete Import Entry

This endpoint is used to delete a specific subscriber from a contact import.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: {{import_sub_id}}

The ID of the imported subscribers.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [ ],
  • "message": "Import record deleted successfully",
  • "status": "OK"
}

Identifiers

Get All Identifiers

This endpoint makes an HTTP GET request to retrieve a list of contact identifiers.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": [
    ],
  • "links": {
    },
  • "message": "OK",
  • "meta": {
    },
  • "status": "OK"
}

Plugins

Third-party integrations help you integrate your business service with another resource through an API. This enables you to use the third-party service on your network application.

You can integrate Thundersms services with the following plugins:

  • Opencart
  • Magento
  • Wordpress
  • Woocommerce
  • Excel

Requirements for Integrating the Plugins

Mandatory Parameters

All plugins should use the below parameters in the process of integrations with us.

Name Descriptions
sender_id Specify the sender_id through which you want to send the SMS.
access_token The access_token that is generated under your account.

Optional Parameters

Few plugins, like Woocommerce and Wordpress, use the below parameters in the process of integrations with us.

Name Descriptions
Service type Specify the service type through which you would like to send SMS.
Provider Kindly select Thundersms under the provider list in order to integrate.

For further queries on the integrations, kindly contact our support team.

Excel Plugin

An Excel add-in allows you to extend Excel application functionality across multiple platforms, including Office for Windows, Office Online, Office for Mac, and Office for iPad. Use Excel add-ins within a workbook to: interact with Excel objects; read and write Excel data.

Purpose

With the Excel Plugin, you may send SMS to your customers whose data is stored on your Excel sheet. It can help you personalize message content and target specific customers.

Features

  • Send SMS directly from the Excel page.
  • Ease of use and handling a lot of numbers at once
  • Get to know the status of the SMS sent on the same page using Excel tools.

Configuration Process

Step 1: Download and extract the zip file.

Step 2: Double-click the file and attempt to install it.

alt text

Step 3: click Run anyway.

alt text

Step 4: Click Next, then Finish, and finally Done to complete the installation.

alt text alt text

Step 5: Open Excel, and you will see integrated plugin in the menu bar, and click on it.

alt text

Step 6: Click on the Basic account and enter your account's token address and username.

alt text alt text

Step 7: Once Thundersms appears in your menu bar and you've finished the previous steps, you're ready to send SMS.

Step 8: To send a quick SMS and perform a quick test, click on the Thundersms menu and then select the Quick send.

alt text

Step 9: To send customized SMS, click on the Thundersms menu and proceed with the following steps.

alt text

Step 10: Click sms/dlr.

alt text alt text

Step 11: You'll find the table headers. Fill in the table with your data according to these headers.

alt text

Step 12: After filling in the data, click on Thundersms to customize the SMS.

alt text

Step 13: You will see the status on the same page.

alt text

For further assistance with integration regarding our application, please reach out to our support team.

WordPress Plugin

Initiate effective automation with WordPress integration with us.Make your business communication simpler.

Purpose

By using WordPress SSMS,you can add the ability to send SMS to your WordPress product. So you can send SMS to your newsletter subscribers or your users and get their attention to your site and products.

Features

Using WordPress SMS, you can enjoy as many features as you want.

  • Send SMS to either your users’ numbers or specific numbers.
  • Get your users’ mobile numbers when they subscribe to your newsletters.
  • Send SMS automatically to users and admins in different situations.
  • Increase the security by two-step verification.
  • Log in with your mobile number in case you forget your password.
  • Sending activation codes to subscribers when a new post is published and also when subscribers are completing their subscription process.

Configuration Process

Step 1: Upload wp-sms to the /wp-content/plugins directory.

Step 2: Activate the plugin through the Plugins menu in WordPress and specify your details, like sender_id and token.

Step 3: To display the SMS newsletter form, navigate to Themes, then Widgets, and include a Subscribe form.

Step 4: Please specify our name in the gateway name.

Step 5: Please select all the details requested by them, as shown in the below screenshot.

alt text

Reference

  • For additional information, visit the WordPress website.

  • For any further help on integration with respect to our application kindly contact our support team.

Magento Plugin

With the Magento plugin, send your subscribers the best offers, discounts, delivery status, and transaction details via SMS and keep them engaged.

Purpose

This is a bundle of powerful yet flexible modules and plugins that are tailor made for online-to-offline retailers.

Features

Using WooCommerce SMS, you can enjoy many features.

  • Notify customers via SMS about their activities, such as order placement or cancellation, invoice generation, etc., in the Magento store.
  • Input the mobile number of the admin in the backend to get SMS notifications for customers various activities.
  • Configure API settings by registering with our SMS gateway to get the sender ID, API key, and URL, and then select the message type to be sent to the customers.
  • Set custom SMS text for various notifications, such as order placement, order invoice, order cancellation, order shipment, credit memo generation, contact inquiries, and website registrations.
  • Make use of system variables like order_id, first_name, and many others to prepare custom SMS notification texts.
  • Use of default Magento registration and guest checkout forms to collect mobile numbers of customers to send SMS notifications.
  • As soon as the mobile number is registered with the Magento store, an SMS notification is sent for each store and order activity.
  • Build trust and improve the user experience by sending quicker SMS notifications to customers.

Configuration Process

Step 1: Unzip the zip file and place its contents (app, var, vendor) into the project's root folder.

Step 2: Log in to the admin panel, navigate to System, then User Roles, click on Administrators, and finally click the Save Role button.

Step 3: Navigate to System, then Cache Management, select All, and flush the Magento cache.

Step 4: Run the command `php bin/magento indexer:reindex`` to refresh the indexing.

Step 5: Access the Thundersms SMS menu from the left sidebar, then go to Configuration to adjust the settings.

For any further help with integration with respect to our application, kindly contact our support team.

WooCommerce Plugin

Install this plugin and configure your account to send messaging campaigns. Customize your messages and stay connected with your users.

Purpose

WC-APG SMS notifications adds to your WooCommerce store the possibility of sending SMS notifications to customers every time the order status changes. Also notifies the owner, if you desire, when the store has a new order.

Features

Using WooCommerce SMS, you can enjoy many features.

  • Possibility to inform the owner about the new orders in the store.
  • Possibility to send, or not send, international SMS.
  • Possibility to notify the shipping phone number if it’s different from the billing phone number.
  • 100% compatible with WPML.
  • Support for custom order status.
  • Support for custom order numbers comes from the WooCommerce Sequential Order Numbers Pro plugin.
  • Automatically inset the international prefix number, if it’s necessary, into the customer’s phone number.
  • Also notified by SMS are the customer notes.
  • All messages are customizable.
  • You can choose which messages to send.
  • You can set the timer every X hours for on-hold orders.
  • You can add your own custom variables.
  • Has an apg_sms_message filter to facilitate the customization of SMS messages from our plugins.
  • Has apg_sms_phone_process and apg_sms_phone_return filters to facilitate the phone number process from our plugins.
  • Possibility to notify multiple phone numbers via filter apg_sms_phone_return.
  • Once setup is fully automated.

Configuration Process

Step 1: Upload the woocommerce-apg-sms-notifications folder to /wp-content/plugins directory via FTP.

Step 2: Upload the entire ZIP file through Plugins, select Add New, and then Upload on your WordPress Administration Panel.

Step 3: Select Thundersms under SMS Gateway drop down and proceed further.

Step 4: Search for WC-APG SMS notifications in the search engine provided on Plugins, navigate to Add New, and click the Install Now button.

Step 5: Activate the plugin through the Plugins menu on the WordPress administration panel.

Step 6: Configure the plugin on WooCommerce either under SMS Notifications or by clicking the Settings button.

alt text

Reference

  • For additional information, visit the WooCommerce website.

  • For any further help with integration with respect to our application, kindly contact our support team.

Opencart Plugin

Integrate your account with the Opencart plugin to send order status and shipment details to your customers. Keep your admin informed on checkouts, new registrations, and orders via SMS.

Purpose

When an order is placed, shipped, or status changes in OpenCart, you can confirm with your customer and/or store admin via a text message sent directly to their mobile phone.

Features

  • Send SMS to customers and admins on new orders.
  • Send SMS to customers and admins on status updates.
  • Send SMS using your brand or domain as the sender ID (messages appear from YourCompany).
  • Update store admin when a customer registers or checkouts.

Configuration Process

Step 1: Download the opencart_plugin, and place all the subfolders from opencart folder to the root folder's upload folder.

Step 2: Log in as an administrator, then go to the Extension, and select the Modules page.

alt text

Step 3: Select the Install option next to our SMS module.

Step 4: After installation, select Edit next to our SMS module.

Step 5: In the API Information tab, enter the sender ID and token details.

alt text

Step 6: In the New Orders tab, compose a message to be sent to the customer upon placing a new order. You can customize your SMS using variable parameters within {{1}}.

Step 7: In the Orders Status tab, create messages to be sent to the customer for each status change. You can customize your SMS using variable parameters within {{2}}.

Step 8: In the Additional Options tab, choose whether to send a message to the store admin, specify the admin's number, and set the conditions for when it should be sent.

Step 9: Click Save.

Flow

  • Whenever a new order is placed from the store, the customer and admin (if configured) receive an SMS with the current status.
  • Also, on every status change, customers and admins, if configured, receive an SMS.
  • On configuration, admin will also receive an SMS when a new customer is registered or customers checkout.
  • To view the status of the SMS sent, login to our SMS panel, check the sent items tab for the last 3 days, and download reports for the date beyond.

Reference

  • For additional information, visit the Opencart website.

  • For any further help with integration with respect to our application, kindly contact our support team.

Freshdesk Plugin

Thundersms integration with Freshdesk enables customers to receive SMS notifications on ticket updates. Here are the key features and a step-by-step guide for setting up the integration:

Key Features:

  • SMS notification on ticket creation

  • SMS notification on ticket status changes

  • SMS notification on new reply or public notes on a ticket

  • Easy configuration through API

Integration Guide

Step 1: Obtain access token

  1. Follow the guide for obtaining your access token: Generate Access Token

Step 2: Installation

  1. Go to your Freshdesk settings and navigate to the Apps section.

  2. In the Apps section, search for Thundersms and click on Install.

  3. Fill in the required details as prompted.

alt text alt text
  1. Click Install.

Replaceble variables

You can use replaceable variables in your messages. For example:

Dear customer, your ticket id is {id}

The {id} will be replaced by the corresponding ticket ID.

Available variables include:

  • id
  • subject
  • description_text
  • status
  • priority

Zoho Plugin

The Zoho plugin allows you to send SMS without leaving the Zoho panel. You can send SMS to both leads and contacts. Follow these steps to learn how to use it:

Step 1: Obtain access token

Follow the guide for generating your access token: Generate Access Token

Step 2: Setup

After installation, you’ll be prompted to enter the access token you obtained in the previous step.

alt text

Step 3: Sending SMS

  1. Click on the Thundersms SMS button on the lead page.
alt text alt text
  1. To send bulk SMS, select the leads and click on the Thundersms SMS button.
alt text
  1. You can follow the same steps to send SMS to contacts.

Step 4: Reports

View recent messages from the Thundersms tab located in the top navigation.

alt text

Integrations

Webengage SMS Integration

Step 1: Set up your account with the required credentials in Update Account Info.

alt text

Step 2: Select Integrate SDK and click Integrate Email/SMS Service Provider.

alt text

Step 3: Select SMS under Channels, then click on ADD SSP.

alt text

Step 4: Select Thundersms from the SSP list.

alt text

Step 5: Enter the configuration name, API key (generated from the Thundersms Panel), and PE ID (derived from the DLT portal).

Note: The sender ID and template configuration must have been completed in DLT and Thundersms panel.

alt text

Step 6: To run a campaign, make sure you have user data pre-uploaded through Upload Data under Data Platform.

alt text

Step 7: Procedure for Running a Campaign:

  • Navigate to Channel section.
  • Click SMS on the left sidebar.
  • Click +New.
  • Select the Campaign Type (One time, Recurring, Transactional).
  • Choose the content type, audience type, and other necessary details based on the requirements, then save your settings.
  • Select SSP as Thundersms and enter SMS details, including Sender ID, SMS Content, and DLT Template ID.
alt text
  • Add conversion tracking and test Campaign details (if applicable).
  • Preview the launch and execute the campaign.
alt text alt text
  • You can view the running campaign in the List of Campaigns.
alt text

Clevertap SMS Integration

Steps to Integrate Send SMS

To integrate Clevertap as an SMS provider, follow these steps:

  1. Log in to CleverTap account.
  2. Navigate to Settings
  3. Click on Engage.
  4. Select Channels and choose SMS.
  5. Click +Add Provider.
  6. Choose Other (Generic) under Provider.
  7. Select the POST method and specify the following API as the provider's endpoint.
http://portal.thundersms.com/api/v2/sms/clevertap/send
  1. Under Authentication, choose No Authentication.
  2. Select Headers to include any HTTP headers that will be appended to the HTTP request sent to the API endpoint.
alt text
  1. Enter key and value pairs.
Key value
Accept application/json
Authorization Bearer 7160f04c05870ee**
Content-Type application/x-www-form-urlencoded
  1. Select Parameters and choose x-www-form-urlencoded to pass key and value pairs.
alt text
Key value Descriptions
sender TXTSMS The registered and approved sender ID
to 8074** Phone number to send with a country prefix. (Multiple numbers can be separated by a comma.)
message welcome to CPaaS The content of the SMS
service T Determines whether the SMS to be sent is transactional, promotional, or other.

System Dynamic Replacements

For Clevertap dynamic variables check here

Optional Parameters

Parameter Description
entity_id Principal Entity registered in the DLT portal
template_id Template ID registered in the DLT portal
webhook_id The ID of the webhook created in the webhook section for which the SMS response to be sent after the delivery report from the operator. Read more
time Schedule the time (in format, i.e., yyyy-mm-dd hh:mm:ss) at which the SMS has to be sent.
type The SMS to be sent is Unicode, Normal, or Auto-detect. (value: U, N, or A)
flash This parameter can be used to send flash SMS via API (values 1 or 0).
custom Your own unique_id parameters
port Port number to which SMS has to be delivered

Send SMS via JSON

  1. Select the POST method and specify the following API as a provider endpoint.
http://portal.thundersms.com/api/v2/sms/clevertap/json
alt text
  1. Select Headers to pass any HTTP headers that will be included in the request sent to the API endpoint.

  2. Enter key and value pairs.

Key Value
Authorization Bearer 7160f04c05870ee**
Content-Type application/json
  1. Choose Parameters and select JSON to pass a JSON object as shown below.
{
    "root": {
        "type": "A",
        "flash": 0,
        "sender": "TXTSMS",
        "message": "welcome to CPaas Alerts,
        "service": "T"
    },
    "nodes": [
        {
            "to": "919492******",
            "sender": "TXTSMS",
            "message": "Message from & json api node 1"
        },
        {
            "to": "918074******"
        }
    ]
}

Moengage SMS Integration

Steps to configure Custom Connector

To integrate Thundersms as your SMS provider, follow these steps:

  1. Log in to MoEngage account.

  2. Navigate to Settings

  3. Click on Channels.

  4. Select SMS & Connector.

  5. Click the SMS Connector Config tab.

  6. In Custom Connecters, click CREATE.

Field Description
Connecter Name Type the name to identify the custom connector.
Sender Name Type the sender ID.
  1. Select the POST method and specify the following API as a provider endpoint.
http://portal.thundersms.com/api/v2/sms/moengage/send
  1. Provide headers as shown below.
alt text
  1. Enter key and value pairs.
Key Value
Accept application/json
Authorization Bearer 7160f04c05870ee******
Content-Type application/x-www-form-urlencoded
  1. Select form as the body type to pass data as key-value pairs.
alt text
Key Value
sender TXTSMS
to Moesms_destination
message Moesms_message
service T
alt text

Optional Parameters

Name Description
entity_id Principal Entity registered in the DLT portal
template_id Template ID registered in the DLT portal
webhook_id The ID of the webhook created in the webhook section for which the SMS response to be sent after the delivery report from the operator. Read more
time Schedule the time (in format, i.e., yyyy-mm-dd hh:mm:ss) at which the SMS has to be sent.
type The SMS to be sent is Unicode, Normal, or Auto-detect. (values: U, N, or A)
flash This parameter can be used to send flash SMS via API (values 1 or 0).
custom Your own unique_id parameters
port Port number to which SMS has to be delivered

Zoho Integration

Our platform allows you to seemingly integrate Zoho CRM. Follow the steps below for the integration guide:

Step 1: Create client

To integrate Zoho CRM with our system, you need to create a client app in the Zoho panel.

  1. Visit Zoho Developer Console to create a client.
alt text
  1. Fill in the following details:

    • Client Name : myclient

    • Client Domain: mydomain.com

    • Authorized redirect URL: http://portal.thundersms.com/api/v2/integration/zoho/code

alt text
  1. Click the Create button.
alt text
  1. You’ll receive client_id and client_secret.

Step 2: Obtain grant token code

Follow these steps to obtain the grant token code:

  1. Open your web browser.

  2. Enter the following URL in the address bar:

https://accounts.zoho.com/oauth/v2/auth?scope=ZohoCRM.modules.all&client_id=(client_id)&response_type=code&access_type=offline&redirect_uri=http://127.0.0.1:8022/api/v2/integration/zoho/code&prompt=consent

  1. Replace (client_id) with the client ID you obtained earlier.

  2. Hit the Enter key to navigate to the URL.

  3. You will be prompted to give consent and then receive the grant token code.

Step 3: Generate refresh token

To generate a refresh token, proceed as follows:

  1. Make a POST request to the following URL:

https://accounts.zoho.com/oauth/v2/token

Request Parameters

Name Description
grant_type Enter the value as authorization_code.
client_id Specify the client ID obtained from the connected app.
client_secret Specify the client secret obtained from the connected app.
redirect_uri http://portal.thundersms.com/api/v2/integration/zoho/code
code Enter the grant token generated from the previous step.
  1. You’ll receive refresh_token.

Step 4: Setting flow in Thundersms

alt text
  1. Fill in the details you obtained in the previous steps.

  2. Click Save

alt text

HubSpot SMS Integration

Our platform allows you to seemingly integrate HubSpot CRM. Follow the steps below for the integration guide:

Step 1: Create client

To integrate HubSpot CRM with our system, create a client app from the HubSpot panel.

  1. Visit HubSpot to create a client.

  2. Fill in the following details:

    • App Name : AppName

    • Authorized redirect URL: http://portal.thundersms.com/integration/oauth/hubspot

  3. Click on Save button.

  4. You’ll receive App_idclient_id, and client_secret.

Step 2: Obtain grant token code

Follow these steps to obtain the grant token code:

  1. Open your web browser.

  2. Enter the following URL in the address bar:

https://app.hubspot.com/oauth/authorize?client_id=(client_id)&scope=contacts&access_type=offline&response_type=code&approval_prompt=auto&redirect_uri=http://127.0.0.1:8022/integration/oauth/hubspot/

  1. Replace (client_id) with the client ID you obtained earlier.

  2. Hit the Enter key to navigate to the URL.

  3. You will be prompted to give consent and then receive the grant token code.

Step 3: Generate refresh token

To generate a refresh token, proceed as follows:

  1. Make a POST request to the following URL:

https://api.hubapi.com/oauth/v1/token

Request Parameters

Name Description
grant_type Enter the value as authorization_code
client_id Specify client ID obtained from the connected app.
client_secret Specify client secret obtained from the connected app.
redirect_uri http://portal.thundersms.com/integration/oauth/hubspot
code Enter the grant token generated from previous step.
  1. You’ll receive refresh_token.

Step 4: Create card API for SMS plugin

  1. Once you have created an app in your HubSpot developer account, you will receive an APP_Id and Developer_api_key.

  2. Use the following URL for the POST request, replacing (app_id) and (developer_api_key) with your actual values:

https://api.hubapi.com/crm/v3/extensions/cards/(app_id)hapikey=(developer_api_key)

  1. This card will create your HubSpot account.
`['fetch' => 
    ['objectTypes' =>  [0 => 
        [ 'name' => 'contacts',
            'propertiesToSend' => 
            [                                
            ],
        ],
    ],
    'targetUrl' => (target_url),
    ],
    'display' => (object)[ ],
    'title' => 'Thundersms SMS',
    'actions' => (object)[ ],
]
`    
  1. Set the targetUrl to: http://portal.thundersms.com/api/v2/integration/hubspot/targeturl

  2. This TargetUrl will call the primary action function.

`'primaryAction' => 
array (
'type' => 'IFRAME',
'width' => 890,
'height' => 748,
'uri' => "(iframe_uri)",
'label' => 'Send SMS',
'associatedObjectProperties' => 
array ('phone', 'firstname', 'lastname', 'email', 'hs_object_id'),
)`
  1. Configure the iframe_uri to: http://portal.thundersms.com/iframe/hubspot/

  2. The primary action will open an iframe option displaying the user's phone number, name, and email.

Step 4: Setting flow in Thundersms

  1. Access your CPaaS account using your login credentials.

  2. Click on the Developers option in the navbar.

  3. From the dropdown, select Integrations.

  4. On the right side of the screen, click the Create button.

  5. Choose Hubspot Card from the options provided.

  6. Follow the prompt to select the HubSpot account where you want to install the integration.

  7. Once the installation is complete, you will see the CPaaS SMS Card in your HubSpot account.

Zoho Desk Integration

Our platform allows you to seemingly integrate Zoho Desk. Follow the steps below for integration guide:

Step 1: Create client

To integrate Zoho CRM with our system, create a client app from the Zoho panel.

  1. Visit Zoho to create a client and select Server-based Applications.
alt text
  1. Fill in the following details:

    • Client Name : myclient

    • Client Domain: mydomain.com

    • Authorized redirect URL: http://portal.thundersms.com/api/v2/integration/zoho/code

alt text
  1. Cick the Create button.
alt text
  1. You’ll receive client_id and client_secret.

Step 2: Obtain grant token code

Follow these steps to obtain the grant token code:

  1. Open your web browser.

  2. Enter the following URL in the address bar:

https://accounts.zoho.com/oauth/v2/auth?response_type=code&client_id=(client_id)&scope=Desk.settings.READ,Desk.basic.READ,Desk.tickets.UPDATE,Desk.contacts.UPDATE,Desk.contacts.CREATE,Desk.search.READ,Desk.tickets.READ,Desk.tickets.CREATE,Desk.basic.READ,Desk.contacts.READ&redirect_uri={doman}/api/v2/integration/zoho/code&access_type=offline&prompt=consent

  1. Replace (client_id) with the client ID you obtained earlier.

  2. Hit the Enter key to navigate to the URL.

  3. You will be prompted to give consent and then receive the grant token code.

Step 3: Generate refresh token

To generate a refresh token, proceed as follows:

  1. Make a POST request to the following URL:

https://accounts.zoho.com/oauth/v2/token

Request Parameters

Name Descriptions
grant_type Enter the value as authorization_code
client_id Specify client ID obtained from the connected app.
client_secret Specify client secret obtained from the connected app.
redirect_uri http://portal.thundersms.com/api/v2/integration/zoho/code
code Enter the grant token generated from previous step.
  1. You’ll receive refresh_token.

Step 4: Setting flow in Thundersms

alt text
  1. Fill in the details you obtained in the previous steps.

  2. Click Save.

alt text

Limitations

Thundersms platform has its own set of limitations that you should be aware of to ensure effective utilization and management.

SMS Channel

File Upload Limits

Campaign: Maximum of 200 MB.

Global Other than Campaign Manager: Maximum of 100 MB.

Impact of Exceeding Limit: Exceeding the file upload limits may result in rejection of the file, leading to delays in campaign deployment or file processing failures.

Workaround: Consider compressing files or breaking them down into smaller segments before uploading.

Campaign Limits

Quick Campaign: Up to 50,000 messages.

Bulk Upload: Maximum of 500,000 messages. Campaigns exceeding this limit may face delays or failures.

Impact of Exceeding Limit: Campaigns exceeding the message limits may experience delays in delivery or complete failure of campaign execution.

Workaround: Divide the campaign into smaller segments or batches and send them sequentially.

API Rate Limits

Status API: Up to 1000 requests per minute.

Balance API: Up to 1000 requests per minute.

Impact of Exceeding Limit: Exceeding API rate limits may result in request throttling or blocking, preventing further access to API functionalities from the affected API.

Opt-out Tags

Maximum of 3 opt-out tags can be applied per outbound campaign.

Impact of Exceeding Limit: Applying more than 3 opt-out tags may lead to incomplete opt-out management, potentially resulting in unwanted messages being sent to recipients who have opted out.

Campaign Schedule Period

Must be less than 3 months and more than 5 minutes.

Impact of Exceeding Limit: Scheduling campaigns beyond the specified period may result in scheduling errors or failure to execute campaigns as intended.

Split Schedule Limits

Batch Size: 1000 to 500,000 numbers.

Time Interval: 5 minutes to 1 hour.

Impact of Exceeding Limit: Splitting schedules beyond the specified batch size or time interval may lead to scheduling conflicts or errors in campaign execution.

Maximum of 10 requests in 5 minutes per IP.

Impact of Exceeding Limit: Exceeding the smart link request limit may result in IP-based throttling or blocking, preventing further access to smart link functionalities from the affected IP address.

Authentication

  • Password reset and 2FA requests are limited to 3 attempts within a 5-minute window.

  • New user activation is limited to 3 requests within a 2-minute window.

  • API tokens, once lost, cannot be retrieved, and must be recreated.

Impact of Exceeding Limit: Exceeding authentication attempt limits may temporarily lock users out of their accounts or disrupt API access until new tokens are generated.

Data Retention and Report Requests

  • Campaign and media link data retention varies by region and is detailed in the policy.

  • Requested reports are available for the last 3 months and are archived thereafter.

Impact of Exceeding Limit: Attempting to access archived reports or data beyond the specified retention period may result in unavailability or loss of access to historical campaign data and reports.

Operational Limitations

  • Ongoing campaigns cannot be aborted or cancelled.

  • No reseller limit within the application.

  • Customers cannot transfer credits between transactional and promotional or other services.

  • Deleted content is irretrievable.

Impact of Exceeding Limit: Violating operational limitations may lead to disruptions in operations, loss of data, or failure to manage account settings as intended.

SMS Delivery: Loop Protection and Fraud Prevention

Message Repetition

  • To prevent spam and potential scams, a limit is placed on the number of identical SMS messages sent from the same sender (a-nr) to the same recipient (b-nr) within a specified timeframe (x minutes).

  • No identical messages with the same content can be sent from the same a-nr to the same b-nr within x minutes (where x is a specific time period defined by the service provider).

  • This rule targets individuals or programs attempting to bombard recipients with repetitive messages.

  • It allows for legitimate communication while protecting users from unwanted spam.

Impact of Exceeding Limit: Violating the message repetition rule may trigger anti-spam mechanisms, resulting in message blocking or account suspension.

Voice Channel

Data Retention

Voice files, including call logs and recordings, are retained for 60 days before archival.

Impact of Exceeding Limit: Exceeding the data retention period may result in loss of access to voice files, call logs, or recordings beyond the specified retention period.

Sticky Agent

Limited to a 2-hour duration.

Impact of Exceeding Limit: Exceeding the sticky agent duration may result in loss of agent assignments or disruptions in call routing.

Bulk Upload

Maximum of 50,000 limits.

Impact of Exceeding Limit: Attempting to upload bulk data exceeding the specified limit may result in rejection of the upload request or processing errors.

Voice Recording URL Validity

Webhook URLs for recordings are valid for 2 hours only.

Impact of Exceeding Limit: Exceeding the recording URL validity period may lead to expired URLs, preventing access to call recordings or triggering errors in webhook processing and can be achieved the same URL from recordings API.

VMN Messaging Logs

Retained for 60 days.

Impact of Exceeding Limit: Accessing messaging logs beyond the specified retention period may result in unavailability or loss of access to historical messaging data.

WhatsApp/RCS/Viber

Bulk Upload Limit

Maximum of 2,00,000 messages across these platforms.

Impact of Exceeding Limit: Exceeding the bulk upload limit may result in delay or failure in delivering the messages.

Help

Setting Custom Domain

App Setup

To configure your domain name and theme colors, please follow these steps:

  • Log in to the CPaaS panel.

  • Navigate to Partners and select Branding from the left side menu.

  • Enter your domain name in the URL field. Examplex: my.example.com

  • Enter the name of your website in the NAME YOUR WEBSITE field, this name will be used in all communication emails.

  • Enter the title of your website in the PAGE TITLE field, this will be displayed on browser window.

  • Click Create.

Note: Enable the IS SSL ENABLED? toggle button to enable secure sockets layer.

CNAME Setup

Login to your domain registrar and create a CNAME record for your domain, pointing to: [destination].

cname.txtsms.me

Have you setup your CNAME?

You can verify that your domain is correctly configured using the dig command:

dig @8.8.8.8 +short CNAME my.example.com

Upon successful configuration, you should see results similar to the following:

;; ANSWER SECTION:
my.example.com.	984	IN	CNAME	cname.txtsms.me.
cname.txtsms.me.	59	IN	A	52.76.163.53
cname.txtsms.me.	59	IN	A	52.221.80.168

Note: It may take up to 12 hours for some hosting providers to resolve the CNAME mapping.

Schedule Message

Our scheduling feature allows you to set up SMS messages to be sent at specific times to individual phone numbers or groups. This functionality is available in both our panel and API. By utilizing this feature, you can easily schedule campaigns in advance, freeing up your time for the following day.

We support scheduling for up to 30 days in the future. Additionally, you have the ability to cancel scheduled SMS messages up to 5 minutes before their execution.

With our scheduling feature, you can efficiently plan and manage your SMS campaigns, ensuring timely delivery and enabling you to focus on other tasks.

Batch Schedule

Scheduling SMS messages becomes effortless with our batch scheduling feature. This functionality allows you to upload a bulk list of contacts or multiple numbers and conveniently schedule each segment of the contact list at varying time intervals. The primary objective of this feature is to effectively manage high-volume traffic, ensuring the smooth execution of your campaigns.

By leveraging batch scheduling, you can avoid overwhelming the server with a sudden influx of messages. Instead, the system intelligently queues the messages, executing the campaign at the designated time intervals. This process ensures a controlled and uninterrupted flow without any disruptions or hiccups.

The batch scheduling feature is particularly valuable for large-scale messaging operations, granting you better control and management of message delivery. It significantly enhances the performance and stability of your messaging system, allowing for optimized efficiency in handling your campaigns.

API Schedule

As documented in our API, we have incorporated a feature that allows users to schedule SMS messages for single or multiple recipients at any given time. This functionality is readily available for utilization.

Customizing Smart URL Redirection

Use a single short URL in your SMS campaign, and based on your customer’s device details, route them to a different domain of yours.

Below are the replaceable parameters that can be used along with the URL to extract customer device/IP details.

Name Description Example
client_ip IP from which the URL was accessed 156.151.23.65
host Domain name of the URL Example.com
user_agent The user agent used by the URL Mozilla/5.0 (iPad; U; CPU OS 3_2_1 like Mac OS X; en-us) AppleWebKit/531.21.10
browser Browser in which the URL was accessed msie
browser_version Version of the browser in which the URL was accessed 11.0
browser_lang Language of the operating system on which the URL was accessed English
browser_engine Browser engine in which the URL was accessed Trident
platform The operating system of the device on which the URL was accessed androidos
platform_name Code of the OS from which the URL was accessed (AN) for Android
platform_version Version of the operating system of the device on which the URL was accessed 5.0
device_type Type of device on which the URL was accessed phone
device_brand The brand of the device on which the URL was accessed Motorola
device_version Version number of the device on which the URL was accessed XT1068
device_model The model name of the device on which the URL was accessed HTC Dream
touch_enabled Whether or not the device from which the URL was accessed is touch-enabled or not yes
country_code Country from where the URL was accessed IN
country Country from where the URL was accessed india
region State from where the URL was accessed Karnataka
city The city from where the URL was accessed Bangalore
created_at requested time in unixtimestamp 1426243175
mobile Short URL recipient mobile number 9999999999

Webhook

The concept of Webhook is quite simple. A Webhook acts as an HTTP callback, specifically an HTTP GET request, which is triggered when a certain event occurs. It serves as a straightforward means of event notification through an HTTP `GET``.

In our implementation, we will send a curl request to your server, including the specified replaceable variables. You have the option to store these details in your CRM or take any desired action based on the received data.

Sender ID

The Sender ID serves as your identity when sending messages. According to TRAI regulations, all application-to-people SMSs should be sent using a sender ID rather than a number. The SMS Sender ID is the name that appears as the sender of your outgoing transactional SMS messages. It provides an excellent opportunity to reinforce your brand identity with your customers.

Similar to how you receive general SMS messages from your friends with their names displayed, the sender ID chosen on the panel or provided to you serves as your identity when sending messages.

While the chosen sender ID will be used as frequently as possible, it’s important to note that a significant portion of traffic will still be overwritten to ensure successful delivery. Recent regulation changes require the alpha sender ID to be prefixed with two letters, depending on the carrier used for delivering the SMS to the final operator. In some cases, a random number may be added as well. For example, the registered sender ID “MD” may appear as “MD-XXXXXX” (where XXXXXX represents the registered sender ID).

Sender ID Format

Promotional SMS

The sender ID is numeric and predetermined by the operator. For example, it could be 777777.

Transactional SMS

The sender ID consists of six alphabetic characters. For example, it could be NOTIFY or TXTSMS.

Don’ts:

  • Do not choose commonly used English words or phrases like “COFFEE” or “SMSFRU”

  • Do not use other company names or brands like “AIRTEL” or “LENOVO”

  • Do not violate someone else’s trademark.

  • Avoid using numbers unless it is necessary and supported (as it looks spammy). For example, avoid “BUY431”.

Do’s:

  • It must be six characters long (mandated by TRAI)

  • It is always capitalized

  • It must be reflective of your brand name and/or trademark.

  • It must tie in well with the content in the SMS. It could be campaign specific.

Let’s say, for some reason, you entered a sender ID while purchasing a number, and now you want to change it. Here’s what you need to do:

  • You can’t make any changes to the existing sender ID.

  • You have to apply for a new sender ID.

  • For this, you have to create a new sender ID from your respective SMS panel. Log in to your account, go to Manage Items, select Sender ID, and then choose Create Sender ID.

  • After applying, you’ll get approval from our support team.

Regulations and Restrictions for SMS Messaging

Several restrictions are in place regarding SMS messaging in India, particularly when it comes to the country’s National Do Not Call (NDNC) list (see more in the table below). There are other restrictions in place regarding sending times and volumes, which you can also see below.

Alternatively, read more at the Telecom Regulatory Authority of India.

National Do Not Call List (NDNC)

A substantial portion of mobile numbers are registered on the NDNC, and if you send marketing or promotional messages to these numbers, your message will be blocked (you can still send transactional and manually approved messages to these numbers). It’s a good idea to check the NDNC by visiting http://www.nccptrai.gov.in/nccpregistry/search.misc to see if the number you want to send to is registered (remember to omit the international dialling prefix of 91 before searching).

Time Restriction

Promotional SMS messages may only be sent between 9 a.m. and 9 p.m. Standard India Time (STD). This means your messages could be blocked or delayed if you send them outside of these times, depending on the operator.

Volume Restriction

You may not send more than six messages per hour with the same content, from the same sender, to the same number.

Regulations on Opt-In Messages

  • No opt-in messages should be sent via transactional routes.

  • An opt-in message can be sent to the end user only if she/he has submitted a documented approval.

  • Web opt-ins are not accepted as approved opt-ins.

Restrictions on Social Invites

Any invitations related to social media, websites, or OTTs need to have their content confirmed and whitelisted prior to being sent via transactional accounts, and violating this can result in heavy fines.

  • The Customer Happiness Team endeavours to provide its customers with the best customer support services to ensure the best product experience. In case you or your authorized user(s) face any issues or have any questions in relation to our product, please contact our Customer Happiness Team between 8 a.m. to 8 p.m. on any day (Monday through Sunday).

  • We reserve the right to reject your sender ID request if we find it does not comply with these dos and don'ts. Having said that, we are here to make it easy for you to send your SMS, so we will give you our reasons and suggest alternatives.

  • We will respond to your query based on the severity of the issue faced with our product (hereinafter referred to as Level of Severity) set out in Table A and typically resolve it within the time frames set out in Table-A below.

Sender ID Approval Time
TAT 30 Minutes

We value our business association with you and aim to build it into a long-lasting relationship of trust. We hope you enjoy using our product as much as we love serving you! We reserve the right to review, revise, amend, modify, or re-enact our Support Services Policy, if we do so.

Sender ID Policies

Country Sender ID
Afghanistan Few Networks Dynamic Only
Albania Dynamic Sender ID
Algeria Dynamic Sender ID
Andorra Dynamic Sender ID
Angola Dynamic Sender ID
Anguilla Dynamic Sender ID
Antigua & Barbuda Dynamic Sender ID
Argentina Delivers via Numeric Sender
Armenia Dynamic Sender ID
Aruba Dynamic Sender ID
Australia Dynamic Sender ID
Austria Dynamic Sender ID
Azerbaijan Dynamic Sender ID
Bahrain Dynamic Sender ID
Bangladesh Dynamic Sender ID
Barbados Dynamic Sender ID
Belarus Dynamic Sender ID
Belgium Fixed short numeric
Belize Dynamic Sender ID
Benin Dynamic Sender ID
Bermuda Dynamic Sender ID
Bhutan Dynamic Sender ID
Bolivia Dynamic Sender ID
Bosnia & Herzegovina Registration Required
Botswana Dynamic Sender ID
Brazil Delivers via Numeric Sender
Brunei Darussalam Dynamic Sender ID
Bulgaria Dynamic Sender ID
Burkina Faso Dynamic Sender ID
Burundi Dynamic Sender ID
Cambodia Dynamic Sender ID
Cameroon Dynamic Sender ID
Canada Delivers via Numeric Sender
Cape Verde Dynamic Sender ID
Cayman Islands Dynamic Sender ID
Central African Republic Dynamic Sender ID
Chad Dynamic Sender ID
Chile Delivers via Numeric Sender
China Registration is required (the template needs registration).
Colombia Delivers via Numeric Sender
Comoros Dynamic Sender ID
Congo Dynamic Sender ID
Congo D.R. Dynamic Sender ID
Cook Islands Dynamic Sender ID
Costa Rica Delivers via Numeric Sender
Cote dIvoire Dynamic Sender ID
Croatia Registration Required
Cuba Registration Required
Cyprus Registration Required
Czech Republic Dynamic Sender ID
Denmark Dynamic Sender ID
Djibouti Dynamic (Alpha-supported)
Dominica Delivers via Numeric Sender
Dominican Republic Delivers via Numeric Sender
Ecuador Delivers via Numeric Sender
Egypt Registration Required
El Salvador Dynamic Sender ID
Equatorial Guinea Dynamic Sender ID
Estonia Dynamic Sender ID
Ethiopia Dynamic Sender ID
Fiji Dynamic Sender ID
Finland Dynamic Sender ID
France Delivers via Numeric Sender
French Guiana Delivers via Numeric Sender
French Polynesia Dynamic Sender ID
Gabon Dynamic Sender ID
Gambia Dynamic Sender ID
Georgia Registration Required
Germany Dynamic Sender ID
Ghana Dynamic Sender ID (only the Alpha sender ID is supported)
Gibraltar Dynamic Sender ID
Greece Dynamic Sender ID
Greenland Dynamic Sender ID
Grenada Dynamic Sender ID
Guatemala Dynamic Sender ID (Registration Required for Claro Network)
Guernsey Dynamic Sender ID
Guinea Dynamic Sender ID
Guinea-Bissau Dynamic Sender ID
Guyana Dynamic Sender ID
Haiti Dynamic Sender ID
Honduras Dynamic Sender ID
Hong Kong Dynamic Sender ID
Hungary Delivers via Numeric Sender
Iceland Dynamic Sender ID
Indonesia Registration Required
India Alphabetic (6 characters)
Iran Dynamic Sender ID
Iraq Registration Required
Ireland Dynamic Sender ID
Isle of Man Dynamic Sender ID
Israel Dynamic Sender ID
Italy Dynamic Sender ID
Jamaica Dynamic Sender ID
Japan Delivers via Numeric Sender
Jersey Dynamic Sender ID
Jordan Registration Required
Kazakhstan Registration Required
Kenya Registration Required
Kuwait Registration Required
Kyrgyzstan Dynamic (Alpha-supported)
Laos Dynamic Sender ID
Latvia Dynamic Sender ID
Lebanon Dynamic Sender ID
Lesotho Dynamic Sender ID
Liberia Dynamic Sender ID
Libya Dynamic Sender ID
Liechtenstein Dynamic Sender ID
Lithuania Dynamic Sender ID
Luxembourg Dynamic Sender ID
Macau Delivers via Numeric Sender
Macedonia Dynamic Sender ID
Madagascar Dynamic Sender ID
Malawi Dynamic Sender ID
Malaysia Delivers via Numeric Sender
Maldives Dynamic Sender ID
Mali Dynamic Sender ID
Malta Dynamic Sender ID
Martinique Delivers via Numeric Sender
Mauritania Dynamic Sender ID
Mauritius Dynamic Sender ID
Mayotte Dynamic Sender ID
Mexico Delivers via Numeric Sender
Moldova Delivers via Numeric Sender
Monaco Dynamic Sender ID
Mongolia Dynamic Sender ID
Montenegro Dynamic Sender ID
Montserrat Registration Required
Morocco Registration Required
Mozambique Dynamic Sender ID
Myanmar Dynamic Sender ID
Namibia Dynamic Sender ID
Nepal Registration Required
Netherlands Dynamic Sender ID
Netherlands Antilles Dynamic Sender ID
New Caledonia Dynamic Sender ID
New Zealand Delivers via Numeric Sender
Nicaragua Dynamic Sender ID
Niger Dynamic (Alpha supported )
Nigeria Registration Required
Norway Dynamic Sender ID
Oman Registration Required
Pakistan Delivers via generic sender ID
Palestinian Territory Dynamic Sender ID (Registration Required for Jawwal Network)
Panama Delivers via Numeric Sender
Papua New Guinea Dynamic Sender ID
Paraguay Dynamic Sender ID
Peru Delivers via generic sender ID
Philippines Registration Required
Poland Dynamic (Alpha-supported)
Portugal Dynamic (Alpha-supported)
Puerto Rico Dynamic Sender ID
Qatar Registration Required
Reunion Dynamic Sender ID
Romania Registration Required
Russia Registration Required
Rwanda Dynamic (Alpha-supported)
San Marino Dynamic Sender ID
Sao Tome & Principe Dynamic Sender ID
Saudi Arabia Registration Required
Senegal Dynamic Sender ID
Serbia Dynamic Sender ID
Seychelles Dynamic Sender ID
Sierra Leone Dynamic Sender ID
Singapore Dynamic Sender ID
Slovakia Registration Required
Slovenia Dynamic Sender ID
Somalia Dynamic Sender ID
South Africa Delivers via Numeric Sender
South Korea Delivers via Numeric Sender
South Sudan Dynamic Sender ID
Spain Dynamic Sender ID
Sri Lanka Registration is required (international senders are rejected and terminated via generic senders).
St. Kitts & Nevis Dynamic sender ID
St. Lucia Dynamic Sender ID
St Vincent & the Grenadines Dynamic Sender ID
Sudan Dynamic Sender ID
Suriname Dynamic Sender ID
Sweden Dynamic Sender ID
Switzerland Dynamic Sender ID
Syria Registration Required
Taiwan Delivers via Numeric Sender
Tajikistan Dynamic Sender ID
Tanzania Registration Required
Thailand Dynamic Sender ID
Timor-Leste Dynamic Sender ID
Togo Dynamic Sender ID
Tonga Dynamic Sender ID
Trinidad & Tobago Dynamic Sender ID
Tunisia Dynamic Sender ID
Turkey Dynamic Sender ID
Turkmenistan Dynamic Sender ID
Turks & Caicos Islands Dynamic Sender ID
Uganda MTN Network requires registration.
Ukraine Delivers via Numeric Sender
United Arab Emirates Registration Required
United Kingdom Dynamic Sender ID
United States Delivers via Numeric Sender
Uruguay Delivers via Numeric Sender
Uzbekistan Dynamic Sender ID
Vanuatu Dynamic Sender ID
Venezuela Dynamic Sender ID
Vietnam Delivers via Numeric Sender
Yemen Dynamic Sender ID
Zambia Dynamic Sender ID
Zimbabwe Dynamic Sender ID

Message Templates

Creating Message Templates

To ensure compliance with policies, your message templates will undergo a review process. Once approved, your business will have its own designated name where the message templates will reside.

When creating a message template, please make sure to include the following:

  1. Message Template Name: Provide a descriptive name for your message template.

  2. Translated Message Template in the correct format: Ensure that the message template is correctly formatted and includes appropriate translations if necessary.

Sample Templates

Creating a welcoming message under the Message Template named welcome with the following content:

"Welcome {{name}}. We look forward to serving you."

Creating an order confirmation notification within the Message Template named order_confirmation stating:

"Your order {{name}} for a total of {{amount}} is confirmed. The expected delivery is {{date}}."

Content Template Validations

  • Two or more spaces are not supposed to be used between two words, before or after a word.

  • All special characters (found on the keyboard) are allowed, except < and > symbols.

  • The variable format is {{var}}, which can have a defined name.

  • Variable can be inserted by clicking the radio button (insert variable) above text box.

  • Trans/Service category messages should have variables mandatorily.

  • Promo categories can have complete fixed content or variable parts.

  • There is no limitation on the number of variables per message.

  • Values like amount, date, a/c number, merchant names, OTP, codes, URL, customer names, card type, etc. need to be replaced with variables.

Transactional

Any message that contains an OTP and requires the customer to complete a banking transaction initiated by the bank customer will only be considered transactional. This is applicable to all banks (national, scheduled, private, government, and even MNCs).

  • An OTP message is required for completing a net-banking transaction.

  • An OTP message is required for completing credit or debit card transactions at a merchant location.

Service Implicit

Any message arising out of the customer's actions or his existing relationship with the enterprise that is not promotional will be considered as a service-implicit message.

  • Confirmation messages of net banking and credit/debit card transactions.

  • Product purchase confirmation, delivery status, etc. from e-commerce websites.

  • The customer makes payments through Payment Wallet over an e-commerce website or mobile app, and an OTP is sent to complete the transaction.

  • OTP's are required for e-commerce websites, app logins, social media apps, authentication/verification links, securities trading, demat account operations, KYC, e-wallet registration, etc.

  • Messages from TSP/ISP.

  • Periodic balance information, bill generation, bill dispatch, due date reminders, recharge confirmation (DTH, cable, prepaid electricity recharge, etc).

  • Delivery notifications, updates, and periodic upgrades.

  • Messages from retail stores related to the bill and warranty.

  • Messages from schools-attendance/transport alerts.

  • Messages from hospitals, clinics, pharmacies, radiologists, and pathologists about registration, appointments, discharge, etc.

  • Confirmatory messages from app-based services.

  • Govt/DOT/TRAI mandated messages.

  • Service updates from car workshops, repair shops, and gadget service centers.

  • Directory services like Justdial have yellow pages.

  • Day-end/month-end settlement alerts to securities and demat account holders.

Service Explicit

These messages necessitate explicit consent from the customer, which has been directly verified by the recipient in a reliable and verifiable manner. The consent is recorded by the consent registrar. These messages do not fall into the category of service-implicit messages.

Note: Additionally, the customer consent template needs to be linked to content templates in the service explicit category.

Messages to existing customers recommending or promoting their other products or services.

  • Choose a short name for a template that is relevant. This helps in choosing the right consent template while creating content templates in promotional or service-explicit categories.

  • The brand name should be relevant to the details mentioned in the scope of the content.

  • The scope of the content should be relevant to the brand mentioned and the intent of the consent to be mentioned.

  • If an entity wants to provide opt-out information, that needs to be provided completely. Example: To opt-out, send SMS as STOP to 1234567890.

  • Not to use generic names for templates like template 1 or template 2.

  • Not to mention invalid or irrelevant names under the brand. This will be treated as an invalid template.

  • Not to enter the actual message sent to the customer; no shot message like consent; SMS to customers; etc.

  • No variable to be used in the scope of consent, as variable applicable to content templates only.

  • Multiple consents are not required by the entity unless they are required by the enterprise, like the example mentioned in explaining the brand name field.

Promotional

Any message that aims to promote or sell a product, goods, or service, including messages that contain a mixture of service and promotional content, will be categorized as promotional. These messages will only be sent to customers after undergoing the preference and consent scrubbing process.

Note: Additionally, the customer consent template needs to be linked to the content templates in the service explicit category.

Do’s for Content Template

  • Use the promotional category for communications intended to be sent from a numerical sender ID only.

  • Transactional category to be used by banking enterprises only and for OTP messages during fund transfers; online payment; merchant txn only.

  • The service explicit category needs to link the consent template as well, without which the template gets rejected.

  • Choose a relevant or recognizable name for templates.

  • Use the message type “TEXT” for all general messages and “Unicode” for regional messages.

  • Variable {{date}}, {{amount}}, or any variable name insertion is required against values like date, amount, a/c number, OTP, names, etc.

  • Always use Notepad or Notepad++ to create templates to avoid additional spaces and invalid characters.

  • The minimum fixed character required in templates is 6 characters (applicable in pure OTP messages only).

  • Linking consent templates for content template categories “promotional” and “service-explicit” is optional (not mandatory).

Don’ts for Content Template

  • Not linking consent templates for content template categories “promotional” and “service-explicit”. Same content and template against multiple headers.

  • Header selection against irrelevant templates.

  • Selecting the “Transactional” category by non-banking enterprises.

  • No or invalid variable format in templates.

  • Using double spaces in templates (this can be pre-checked by verifying the template on Notepad++ before template submission).

  • Templates with less than 6 characters or variable insertion alone as a template.

  • Do not use external fonts or characters other than those that appear on the keyboard.

IP Whitelisting

IP whitelisting enables the creation of lists consisting of trusted IP addresses or IP ranges that have access to API tokens. This security feature is commonly employed to restrict and regulate access exclusively to trusted users.

Enable IP Whitelisting

IP whitelisting can be enabled while creating an access token for your account.

  • Step 1: Login to your account and click on Manage on your side bar.

  • Step 2: Click on the API keys option, and the API creation page will be opened for you.

  • Step 3: You have to click on create new token, and the token creation page opens where you will have to enter the IP address (multiples separated by ,)  which you would like to whitelist.

  • Step 4: Click on Create, and the IP whitelisting is done, and that access token works only at that IP address.

Example IPs:

127.0.0.1:8000

127.0.0.1:8000/0

Mobile Number Masking

Sometimes customers don’t want to display their full mobile number on the panel. In that case, we will hide the last four digits of the mobile number by enabling the below configuration.

In user options, we need to set mobile_secure to 1.

Hide Message

To hide complete messages in the panel and reports, we need to enable the following option:

In user options, we need to set hide_msg to 1.

Voice OTP

In some cases, customers want to trigger a voice call when a message is not being delivered at a specific time, like OTP messages. In order to work, we need to enable the following configurations at the service level (transactional, promotional, and scrub).

In meta, we need to enable the voice option as {"voice":{"bridge":918068057xxx,"access_token":"a19eb34810e672cxxxxxxxxxx","flow_id":191,"duration":30}}

Name Description Example
`bridge`` The bridge number belongs to the customer account. 918068057xxx
access_token API key of the customer a19eb34810e672cxxxxxxxxxx
flow_id Flow ID configured in the customer account 191
duration Duration for ending the call Defaults to 30 seconds

Voice Flow

The voice flow builder is used for creating IVR solutions by utilizing the steps available in the flow builder. Flow charts can be created based on the business requirements.

Voice Flow Steps

The following steps are available in flow builder.

Answer

This is the default step in the flow builder. Once the call connects, this step is being called, where we will have set the start time of the call and the temporary status of the call as connected.

Branch

This step is used for validating data from a remote API request. If the customer wants to validate an incoming mobile number with his database once the call is connected, he/she can use the Fetch Vars Step to send an API request to a remote URL, and it will receive a JSON response.

Now, using Branch Step, we can add different conditions with response data as follows:

  • Whether mobile is registered or not depends on the response status.

  • We can add location conditions.

  • We can add patterns for matching data, and we can useh conditional expressions like >, <, and =.

For each condition, we can add different actions according to the customer's requirements. Conditions can be combined to match an exact requirement.

Conference

This step is used to create a conference within the flow.

Date/Time

This step is used for mentioning the working days and timings of the agents. Using this step, if any incoming calls come in during working hours, they will be forwarded to agents, and if the call is not in working hours, we can directly announce to the customer by playing a voice clip that we are working from 7 AM to 9 PM, etc., and we can disconnect the call immediately.

Dial

This step connects calls to the agent or agents group. We offer three types of dial strategies:

  • Sequential:  A sequential call will connect to one after another agent available in the agent group; when any agent answers the call, the call will not connect further.

  • Parallel: A parallel call will connect to all the agents available in the agent group at a time; if any agent answers the call, others automatically get disconnected.

  • Random: A random call will connect to one of the agents available in the agent group randomly, if any agent answers the call, then it won't connect further.

End of Flow

This step is used to end the call. Whenever you want to terminate the call, you can add this step.

Fetch Variables

This step is used for sending an API request to a remote URL, and it receives a JSON response. The response will be saved. You can use it in future steps if required.

Fresh Desk

This step is used for creating FreshDesk tickets in the call flow using call details like call duration, agent name, call recording URL, and caller number.

Fresh Service

This step is used for creating a fresh service ticket in the call flow using call details like call duration, agent name, call recording URL, and caller number.

HTTP Request

This step is used for sending an asynchronous API request to a remote URL. It will save any response from a request; it just sends a request to a remote URL.

Jump

This step is used for jumping from one step to another in the same flow, or we can jump to any flow created in the same user account.

This step is used for taking input from customers. When a call connects to a business, you want to play with the options and expect the customer to select one option. Then you can use this step. Press 1 for products, 2 for services, 3 for account information, and so on.

Play

This is a step for playing a voice clip to the customer. We have the following options for playing a voice clip:

  • Text-to-Speech: You can enter text, and using Amazon Polly, we will convert text to speech. You can preview the voice-over text. 

  • Upload a new sound file.

  • Select a file from already uploaded sound files.

Record

This step is used for recording the call. We can also specify the recording time limit so that it will stop recording if the time limit reaches.

Send Email

This step is for sending email from the flow once the call is finished. We can send call details and caller details with the help of variables in the flow.

Send SMS

This step is for sending SMS from the flow once the call is finished. We can send call details and caller details with the help of variables in the flow.

Subscribe Group

This step is for saving the caller number to the contact group that is already created in the user account. We need to select the group to which the caller number needs to be added. 

Unsubscribe Group

This step is for removing the caller number from the contact group that is already saved in the user account. We need to select the group from which the caller number has to be deleted. 

Subscriber Exists

This step is for checking the caller number in the contact group that is already saved in the user account. We need to select the group for which the caller number has to be checked. It is mostly used in cases where customers want to block some numbers from connecting to agents. 

Wait

This step is used to hold the user for some time; time can be specified in the step.

Voice

This step is used to capture a voice response from the customer. The menu is used for capturing key press responses from customers, and in the voice step, we will capture responses from user voice. Using this step, we can setup a voice bot that automates the process by using the user's voice. It uses AI to process the captured voice response. 

Spy

This step is for spying calls in the agent group.

Interval

This step is used for identifying repeated callers. If we mention some time interval, then it will identify next time when a call comes in the same interval mentioned. We can block or forward to the next level.

Whatsapp

This step is used for sending WhatsApp notifications with call details from the flow after the call is finished.

RCS

This step is used for sending a RCS notification with call details from the flow after the call is finished.

Callback

This step is used for tracking specific calls and will be listed in the callback logs section. From callback logs, you can initiate a call to the customer whenever it is required. A callback step can be added according to the user's requirements.

Default Country Prefix

The “default country prefix” feature allows you to set a default country code for your profile. This feature simplifies communication by automatically adding the country code to all phone numbers associated with the user’s account.

It is particularly valuable for bulk campaigns, where users deal with a list of phone numbers from the same country, as it saves time, reduces errors, and ensures effective communication.

With our feature, you also have the flexibility to override the default country code when needed.

Note: Please provide the country code for the Philippines or set it as the default country on your profile for phone number validation on a campaign.

Distributed Ledger Technology

Insights on New TRAI SMS Regulation Implementation

Distributed ledger technology (DLT) is a digital system for keeping and managing the records of sender IDs and templates. Distributed ledger technology (DLT) is a digital system for keeping and managing the records of sender IDs and templates.

TRAI has introduced an advanced extension of the block chain DLT to prevent spam. Guidelines for Distributed Ledger Technology (DLT) for Enterprises.

Enterprises need to register with the operator’s DLT platform by submitting the necessary business documents. Enterprises need to select a Registered Telemarketer (RTM) and permit them to perform functions on their behalf.

Enterprises need to acquire consent from consumers (mobile subscribers) through SMS, web, or mobile apps and upload it to the DLT platform. It is mandatory for any entity that intends to send a communication through messaging and a voice gateway on the DLT platforms.

Telemarketers and end-users have to register on the DLT platforms separately. Header (Sender ID) registration: Messages are classified into promotional, transactional, service explicit, and service implicit, which are registered, and every header gets a unique header ID that is shared seamlessly across other DLT platforms. All headers and templates on the platform should be registered.

Content Template Registration

Entities are required to register all their templates on the DLT system. Every template gets a unique template ID that is shared uniformly across other DLT platforms.

You can go to the below operator DLT registration portals and select Sphere Edge Ltd.

(Affiliate of Thundersms): 1702157354248182157 (Unique Registration ID)

Regulation Changes

Pre DLT Post DLT Remarks
Customer Consent No Yes Verifiable digital records of all customer opt-ins are made available on the platform. Customers can also see all their consents on a single dashboard.
Customer Preferences Yes Yes Consumers can also select a specific day(s) and time band to block or  receive. Commercial communication in addition to the type of category, viz., only DND
Entity/Enterprise Registration No Yes The entity needs to register with the Originating Access Provider (OAP) on the platform.
Telemarketer Registration Yes Yes Telemarketers should now register with the OAP and no longer with TRAI.
Header Registration No Yes The entity should register all its SMS headers and voice CLIs on the platform.
Type of Messages Transactional Transactional Every template should be registered under one of these classifications: Promotional, Transactional, or Service (Implicit or Explicit)
Type of Messages Promotional Promotional n/a
Type of Messages Govt Service(Inferred Consent) Government messages are classified under the service category.
Type of Messages Service (explicit consent)
Scrubbing Yes (only DND Check for Promotional SMS) Yes (promotional and service explicit) Messages will be scrubbed against multiple parameters like consent, preference, header, template, and not just the DND list.
Complaint Management Yes Yes Telecom operators will now be responsible for complaint resolution.
Interoperability between telecom Service Providers No Yes Registration details for the entity, telemarketer, header, and template will be shared across the network to ensure a seamless view.
100% Traceability No Yes Everything is recorded and shared on the network using block chain technology.

Delivery Report

Pre DLT Post DLT Remarks
Promotional Traffic Yes No Delivery status for promotional messages will not be available post-DLT.
Transactional Traffic Yes Yes Delivery status for transactional messages will continue to be available post-DLT.

Onboarding

Based on this, the sales team requests account creation done with complete KYC documents on the internal portal.

  1. Telemarketers: no direct senders

  2. Direct Enterprise Clients.

Customers send sender IDs or templates (voice or SMS) for whitelisting. There is no uniqueness in the allocation of sender IDs.

Type of Messages

  • Transactional

  • Promotional

  • Govt

All entities, senders, and telemarketers need to register with the originating access provider (OAP) on their DLT platform.

The entity should register all its SMS headers and voice CLIs on the platform. The uniqueness check is enabled.

The entity should register all its templates (customer consent and content) on the platform.

Type of Messages

  • Transactional

  • Promotional

  • Service (Inferred Consent)

  • Service (Explicit Consent)

Note: All requests will be received at the operator, and post-KYC requests will be approved on DLT.

For any further queries, kindly contact us.

DLT Template Registration Process

The template registration process involves two parts:

Consent Registration

This involves the collection of consent from the end customer to send future communication to them regarding the services being enrolled in. This works like an opt-in message.

Content Registration

This template is for the messages that you intend to send out to your clients. This can be OTP, transactional, or marketing, depending on the content you intend on pushing.

Depending on the content of the message, the type of template should be selected at the time of uploading.

  1. Transactional/Service Implicit Templates
  2. Promotional Template/ Service Explicit Templates

Steps to Upload Transactional/Service Implicit Templates:

  • Log in to the portal with your credentials.

  • Navigate to the template section and choose the template type, either Transactional or Service Implicit.

  • Select all the sender IDs you wish to link with the specific template.

  • Enter a unique name for the template for your reference, and select the Template message type, Text or Unicode.

  • Input the template content, and utilize the Insert Variable button to incorporate variables (each variable can accommodate up to 30 characters; choose the required number of variables).

  • Save the template and submit it for approval to the DLT registrar.

Steps for uploading Promotional/Service Explicit templates:

  • Log in to the portal with your credentials.

  • Navigate to the consent template section, enter the necessary details, upload the consent template, and save it. Wait till it gets approved by the DLT registrar.

  • Proceed to the template section and specify the Template type, either Promotional or Service Explicit.

  • Select all the sender IDs that you wish to link with a specific template.

  • Select the approved consent template with which you want to link with a particular message content.

  • Enter a unique name for the template for your reference, and select the Template message type, Text or Unicode.

  • Provide the template content, and utilize the Insert Variable button to incorporate variables (each variable can accommodate up to 30 characters; choose the required number of variables).

  • Save the template and submit it for approval to the DLT registrar.

Based on the operator that you choose, you can follow the below detailed guides to register the consent and content templates on their websites.

DLT Registration With Ping Connect (Videocon)

Registration with Ping Connect (Videocon)

alt text
  • Click New DLT Registration.
alt text
  • If you represent an Indian or Overseas Company, please choose the appropriate option and follow the instructions provided below:
alt text
  • If you're registering on this website for the first time, choose New Entity. If you've previously registered on another website, select Enroll Entity.
alt text
  • Irrespective of the option selected, please fill in the details as shown and proceed.
alt text
  • If prompted for a payment amount during new registration, please input 00 and proceed.

  • A pop-up, as displayed below, may still appear. No need for concern, as the process is free of charge. Simply click OK and proceed.

alt text
  • After updating all the details and submitting the form, an OTP will initially be sent to verify the mobile number you provided during registration. Upon completion of this step, you will receive an acknowledgment similar to the one below:
alt text
  • Here's an example of the email received after completing the registration process at the registered email address:
alt text
  • Click on Click here to verify your email to confirm your email address. Your account will be activated within 24 to 48 hours.

Videocon’s Header/SenderID Registration Process

To ensure seamless message delivery, all customers must register sender IDs/headers with the operators.

  1. Begin by logging into the portal at https://pingconnect.in/

  2. After logging in, navigate to the Header option in the left navigation bar to access a detailed view of all headers. Select New header to add a new one.

alt text
  1. Click Single to create a new single header and select the other fields.

  2. click on Header Type to choose the header type from the provided list.

alt text
  1. Select the Category that most accurately represents your business, for which the header will be utilized.
alt text
  1. Enter the name of the header in the Header Name field.

  2. Click on Check Status to verify the availability of the applied header/sender ID.

  3. Choose the appropriate document for the requested header and initiate the OTP request. After verifying the OTP, proceed by clicking Submit.

alt text
  1. Upon submission, the header status will appear as Pending. The Registrar Team will review it, and if any documents are missing or discrepancies are found in the submitted header, you will receive an update via email or phone call.

  2. Once the header is approved, the status will change from Pending to Approved.

alt text

Videocon’s Content Template Registration Process

Templates are created for Commercial Communication, and according to TRAI guidelines, all Principle Entities must register their templates prior to dispatching Commercial Communication.

  1. In the Entity portal, navigate to the sidebar and select the Templates to access the page.

  2. On the Template page, click on the Add New Template button to initiate the creation of new templates.

alt text
  1. Enter a suitable template name based on the business requirements in the Template Name field.

  2. In the Communication Type dropdown, choose the type of communication from the following options:

    • SMS

    • Call

  3. In the Content Type dropdown, choose from any of the following options:

    • Transactional

    • Promotional

    • Service Explicit

    • Service Implicit

alt text
  1. In the Consent Template ID dropdown, choose the relevant Consent Template registered on DLT.

Note: Consent template ID is not mandatory for Transactional and Service Implicit commercial communications.

  1. In case the consent template is not created at the time of template creation then choose the given link to create and register the same.

  2. In the Content Category dropdown, choose any category that is appropriate for the template being created.

  3. In the Template Type field, the value will either be TEXT or UNICODE, and it will be automatically fetched based on the selected language for the content.

Note: Any language other than English will be taken as Unicode.

10.In the content creation section, choose between Copy/Paste Message or Create New Message (Type) based on the content creation requirement.

alt text
  1. If you select Copy/Paste Message option, copy any message and use it to create the required content for the template.

  2. If you select Create New Message option, enter the required content.

  3. In the Create New Message box, enter the required content. To add variables, utilize the options available on the panel.

  4. Messages in languages other than English can be created; such template types will be treated as Unicode. You can select the language from the dropdown list provided.

alt text
  1. Click the Get OTP link to receive the One-Time Password on your registered mobile and email ID. Once received, enter the same in the OTP field to authenticate the process.

  2. Click the Submit button to confirm and send the request for approval by the Operator.

alt text

Smart Delivery

Smart delivery helps to increase the success rate of delivery and minimise delivery failures and credits lost.

Steps to do the Smart Delivery campaign

Step 1: Please enable the Smart Delivery option while doing the campaign in the preview section.

Step 2: If you enable smart delivery, it will process after 15 minutes.

Smart Delivery Process

Step 1: Smart Delivery Campaign will randomly pick 10 mobile numbers for the campaign and send the message to those numbers.

Step 2: After receiving the DLR, the system will check if there is any DLT rejection status (DLT-REJECTED, INV-PEID, INV-TMID, INV-ENTITY, and INV-TEMPLATE) in those 10 messages.

Step 3: If any DLT rejection statuses are there, the campaign will automatically cancel and send an email to the corresponding account.

Step 4: If there is no DLT rejection, then the campaign will process successfully and will get a high delivery percentage.

Coupon

Variables

Variable Description
{{coupon.code}} Coupon code on successful allotment.
{{coupon.status}} Response status

Status Codes

Status codes can be obtained from {{coupon.status}}

On Allot

Status Code Description
COUPON_ALLOC_SUCCESS A coupon is successfully allocated to a number.
COUPON_LIMIT_REACHED The coupon allocation limit is reached for a number.

On Redeem

Status Code Description
COUPON_INVALID Invalid coupon
REDEEM_SUCCESS Redeem successfull

Advanced OBD

Advanced OBD functions similarly to custom SMS. It enables playing the name of the user and details of the respondent who answered the call.

Step 1: Prepare file

Create a file with columns containing user information. For example, mobile name, email address, etc.

Step 2: Configure audio

  • Create a voice flow and name it for further usage in step 3.

  • Add a play widget and configure the message you want to play.

Example:

Dear @{{name}}, your emailid is @{{emailid}} and address is @{{address}}.If it is correct, then press 1 to continue.

Note: Replace @{{name}} with the column name in the uploaded file.

Step 3: Initiate call

  • Upload the file prepared in step 1 to the Advanced OBD page.

  • Select the flow created in step 2.

Generate Access Token

Step 1: Login to the Portal:

Navigate to the portal and log in to your account.

Step 2: Go to Manage API Keys:

Go to the Manage section and select API Keys.

alt text

Step 3: Create a New Token:

Click on the Create new token button located at the top right corner.

alt text

Step 4: Generate the Access Token:

Click on the Create button to generate the access token. The token will be sent to you via email.

alt text

Webhook Verification

Our servers will dispatch a highly configurable HTTP request to your application endpoint, which is mentioned in the Webhooks section, containing many details about the messaging or any other communication channel.

Validating a Webhook

This procedure describes how to validate a webhook to ensure it is secure and capable of receiving messages from our servers.

  1. Create the Webhook

    Provide a validation key during the webhook creation process.

    Example:

    • Validation key: 9012XX

    • URL: yourdomain.com/receive/callback

  2. Verify the Webhook

    • Ensure that the URL you provided is capable of receiving messages from our servers.

    • The URL must point to a valid webhook endpoint.

  3. Initial Request from Server

    • After creating the webhook, our server sends an initial HTTP request to the webhook URL you provided.

    • This request includes a query parameter called token, which is the validation key you specified during the webhook creation.

Example Request:

curl -X POST \
  'yourdomain.com/receive/callback?token=9012XX' \
  -H 'authorization: Bearer 1233XXX'
  -H 'Content-Type: application/json' \
  -d '{
    "validation_key": "9012XXXX",
    "challenge": "a234qwe",
  }'
  1. Respond to the Request

    • Your webhook endpoint must respond with an HTTP status code 200.

    • The response body must be a JSON object containing the validation key.

Expected Response:

{
  "challenge": "a234qwe"
}
  1. Configure a Secret (Optional)

    You can configure a secret for each webhook. The secret will be sent as a Bearer token in the Authorization header of the webhook requests. This acts as a simple password system where you may check any requests for the correct token.

    Example:

    • Secret: 1233XXXX

    • URL: yourdomain.com/receive/callback

Example Request:

curl -X GET \
  'yourdomain.com/receive/callback' \
  -H 'authorization: Bearer 1233XXX' 
  1. Receive DLR Updates

    After successful verification, you will be able to receive DLR updates to your webhook in the following format:

curl -X POST \ 
  https://www.domain.com/ack/receive \
  -H 'content-type: application/json' \
  -d '{
      "id": "b34e35ad-fe34-4a8b-977c-b21cd76cd7d6:1",
      "mobile": "918921269xxx",
      "status": "DELIVRD",
      "credits": "2.0000",
      "units": 2,
      "deliv_time": "2021-04-09 16:27:51",
      "sent_time": "2021-04-09 16:27:35",
      "submit_time": "2021-04-09 16:27:39",
      "cid": "1234444XXXX",
      "custom": "9882XXXX",
      "custom1": "campaign-3344",
      "custom2": "new-campXXX",
      "location": "India",
      "region" : "Bangalore",
      "provider": "Jio",
      "location_code": "in",
      "region_code": "KA",
      "provider_code": "RJ",
    }

RCS Media Template Guidelines

Rich Card Standalone

To create a standalone rich card, please provide the following details:

Parameter Expected value
Image file Size 2 MB
Video file size 10 MB
Image format JPEG, JPG, PNG, or GIF
Video format MP4
Media thumbnail size 40 to 100 kB

Card Orientation

You can select the card orientation as Horizontal or Vertical.

Note:

  • If you select the Horizontal card orientation, then select the card alignment as LEFT or RIGHT.
  • If you select the Vertical card orientation, then select media height as SHORT or MEDIUM.

Horizontal Orientation

The Card Alignment should be LEFT or RIGHT and provide the following details:

Parameter Expected Value
Media aspect ratio 3:4
Media Resolution 768 x 1024 pixels
Thumbnail resolution (vertical) 250 x 330 pixels
Thumbnail resolution (horizontal) 770 x 335 pixels
Thumbnail aspect ratio 25:33

Vertical Orientation

The Card Height should be SHORT or MEDIUM.

  1. If you select Card Height asSHORT, provide the following details:
Parameter Expected Value
Media aspect ratio 3:1
Media Resolution 1440 x 480 pixels
Thumbnail resolution 770 x 257 pixels
Thumbnail aspect ratio 3:1
  1. If you select Card Height asMEDIUM, provide the following details:
Parameter Expected Value
Media aspect ratio 2:1
Media Resolution 1440 x 720 pixels
Thumbnail resolution 770 x 335 pixels
Thumbnail aspect ratio 7:3