BICS 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

https://eu.cpaas.bics.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
ENT SMS A2P Enterprise
BNK SMS A2P Banking
MKT SMS A2P Marketing
GMS Global mobile number (SMS)
A2P SMS A2P
DIR SMS A2P Direct
IBN Cloud Numbers
SIPT Outbound voice
ITFS International Freephone
GMN Global mobile number (Voice)
WAP Whatsapp 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, BICS 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 BICS sends HTTP POST requests to and subscribe it to specific event types. When a Webhook is triggered, BICS sends information about the affected object to your application. For example, when an end user receives an email message, BICS 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.
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, 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 BICS 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 BICS 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": [ ]
}

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 BICS 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 BICS 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 BICS 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 BICS 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 BICS 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
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.

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",
  • "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.

service
string

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

Responses

Request samples

Content type
application/json
{
  • "country_code": "IN",
  • "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.

type
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}}",
  • "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.

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

The type of template.

Responses

Request samples

Content type
application/json
{
  • "body": "temp12",
  • "is_english": "1",
  • "name": "SENDER",
  • "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
required
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
url 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.

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.

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": "SEN765",
  • "to": [
    ],
  • "message": "Your OTP is 123456",
  • "service": "ENT",
  • "time": "2024-03-10 14:06:10",
  • "type": "A",
  • "flash": 1,
  • "custom": "12345",
  • "port": "3908",
  • "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
{
  • "data": [
    ],
  • "message": "Message(s) Queued successfully",
  • "status": 200
}

Send Text Message

This API endpoint makes an HTTP POST request to send a text message.

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
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
{
  • "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.

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
{
  • "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.eu.cpaas.bics.com 3634 3635
smpp2.eu.cpaas.bics.com 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.

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.

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

BICS 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, BICS 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 BICS 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 BICS 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 BICS 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 BICS 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 BICS 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 BICS 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": [
    ],
  • "messa