BICS API (1.0.0)

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

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:

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.

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

HTTP Status Codes

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.

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:

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.

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.

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}}

6. Choose the HTTP method for the Webhook request from the methods dropdown. By default, the GET method is selected.

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

8. Add the required headers and their values in the Headers tab by clicking the + icon. For example, authorization headers or custom headers.

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

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

11. 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:

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

Unicode 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 Æ æ ß É ! “ # ¤ % & ’ ( ) * + , - . / : ; < = > ? ¡ ? Ö Ñ Ü § ¿ ö ñ ü à ä Ä \ { } ~ [ ]