HTTP API for SMS and Viber Campaigns

All requests must be sent to a URL of the form https://api.turbosms.ua/module/method.format, where the module/method corresponds to the API command available for invocation, and the format specifies the type of returned data. Currently, the response is only supported in JSON format. If you need a response in XML format or any other data format, please contact our support team, and we will add its support. Specifying the format is not mandatory, but we recommend always including it so that there won’t be any issues in the future if we change the default format. Currently, the default format is JSON.

Each request must include the authentication key. It can be passed in several ways:

• GET parameter token=AUTH_TOKEN;
• POST parameter token=AUTH_TOKEN if the Content-Type: application/x-www-form-urlencoded header is present;
• HTTP header Authorization: Basic AUTH_TOKEN;
• HTTP header Authorization: Bearer AUTH_TOKEN.

Data can also be sent in several ways:

• GET parameters (the total length of the URL cannot exceed 2000 characters);
• POST parameters if the Content-Type: application/x-www-form-urlencoded header is present;
• POST request containing JSON data and the Content-Type: application/json header;

Important! All JSON examples in this documentation are split into multiple lines for clarity, but in real interaction with the API, all JSON data must be in a single line. If you need to insert a line break in any value, use the \n character combination.

For any valid HTTP request, the API will always return an HTTP 200 status code. The overall response structure is as follows:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": null
}

• response_code – the numeric code for the request processing result, ranging from 0 to 999;
• response_status – the status of the request processing result, representing a brief description of the outcome;
• response_result – the response data, if provided by the method. It can be null, an object, or an array of objects.

Each module includes a ping method to test the API status, which returns the following response:

{
   "response_code": 1,
   "response_status": "PONG",
   "response_result": null
}

If you receive this response, it means the API is operating correctly and can be used.

Request Numbering

If you need a request to be executed only once, you can add the parameter sequence_id, which contains your unique request identifier. This parameter can contain up to 32 characters. If a request with the same identifier has already been executed within the last 14 days, the results of its execution will be returned, and the request will not be executed again. The response code will be FAILED_DUPLICATE_REQUEST. This parameter is not mandatory but is recommended for use when creating entity requests. Note that the request identifier is tied to a specific API method, meaning you can call another method with the same sequence_id.

Message Module

The module allows you to manage messages, such as creating campaigns, sending them, and checking delivery statuses. Its functionality will be expanded.

Method send

Example call address:
https://api.turbosms.ua/message/send.json

The method allows you to send SMS and Viber messages, as well as supports hybrid Viber sending (if the message is not delivered via Viber, it will automatically be sent via SMS).

General structure of the request body:

{
   "global_parameter_1": "value",
   "global_parameter_2": "value",
   ...
   "global_parameter_X": "value",
   "recipients": [
      "recipient_1",
      "recipient_2",
      ...
      "recipient_X"
   ],
   "viber": {
      "local_viber_parameter_1": "value",
      "local_viber_parameter_2": "value",
      ...
      "local_viber_parameter_X": "value"
   },
   "sms": {
      "local_sms_parameter_1": "value",
      "local_sms_parameter_2": "value",
      ...
      "local_sms_parameter_X": "value"
   }
}

Depending on the type of message you want to send, the request body should include parameters viber or sms, or both for hybrid sending. When creating a message, global parameter values are used first, but they can be overridden with local parameters if needed. For example, you can specify a global parameter text, and if both viber and sms parameters are present, its value will be used for both Viber and sms messages. If a different text value is specified in the sms parameter, it will be used for sms. Thus, if the parameter value is the same for both message types, it can be specified only in global parameters without duplicating it in local ones.

Available Parameters

Parameter	Usage	Data Type	Required	Description
sender	sms and viber	string(20)		The sender name from which the message will be sent (alpha name for SMS or sender for Viber). The sender must be activated in your account.
start_time	sms and viber	datetime		Deferred sending date and time, supports multiple ISO formats. The recommended format is YYYY-MM-DD HH:MM. The date should not exceed 14 days from the current moment. Do not pass this parameter if the message needs to be sent immediately.
start_date	sms and viber	datetime		A synonym for the start_time parameter, added for convenience.
text	sms and viber	string(1000)		Message text. For Viber, up to 1000 characters; for SMS, up to 1521 characters in Latin or 661 characters in Cyrillic text (10 segments). UTF-8 encoding is supported.
recipients	sms and viber	array		Message recipients in international format (380XXXXXXXXX). The parameter must always be passed as an array, even if there is only one recipient. No more than 5000 recipients are allowed in a single request.
is_flash	sms	boolean		Flag for flash messages (1 - yes, any other value or absence of this parameter - no).
ttl	viber	integer		Message lifespan, during which it will be delivered. If the message is not delivered within this time, it will be marked as undelivered. Specified in seconds, values between 60 and 86400 are allowed, with a default of 3600.
image_url	viber	string		The URL of the image that will be displayed in the message.
caption	viber	string		Text on the button in the message.
action	viber	string		The URL the recipient will be redirected to upon clicking the button.
file_id	viber	integer		ID of the file returned by the file/add method.
count_clicks	viber	boolean		Click-through statistics flag (1 - statistics will be kept, any other value or absence of this parameter - no).
is_transactional	viber	boolean		Transactional message flag (1 - yes, any other value or absence of this parameter - no). Sending transactional messages from a shared sender is prohibited.

If no delayed sending time is specified and the created distribution has no more than 5 recipients, the messages will be sent immediately. Viber messages are sent as promotional by default if the is_transactional parameter is not set.

Using the file_id parameter, you can send files to users, such as documents, invoices, and so on. To send a file, you need to pass the caption parameter together with file_id, where you can specify the file name, for example, "Invoice.pdf". This parameter can contain up to 25 Latin characters or up to 12 Cyrillic characters. The text, button, and image parameters must not be present.
The following file formats are supported: .doc, .docx, .rtf, .dot, .dotx, .odt ,odf, .fodt, .txt, .info, .pdf, .xps, .pdax, .eps, .xls, .xlsx, .ods, .fods, .csv, .xlsm, .xltx. Such messages are charged at the transactional rate.

You can also use file_id to send an image or a link on a button. For an image, simply specify the file_id of the corresponding image, in which case the image_url parameter will be ignored. If the caption parameter is specified and the action parameter is missing, the file will be sent as a link on a button. Such messages are charged at the promotional rate.

In response to a create message request, the server will return data with the following structure:

{
   "response_code": 802,
   "response_status": "SUCCESS_MESSAGE_PARTIAL_ACCEPTED",
   "response_result": [
      {
         "phone": "recipient_1",
         "response_code": 406,
         "message_id": null,
         "response_status": "NOT_ALLOWED_RECIPIENT_COUNTRY"
      },
      {
         "phone": "recipient_2",
         "response_code": 0,
         "message_id": "f83f8868-5e46-c6cf-e4fb-615e5a293754",
         "response_status": "OK"
      }
   ]
}

Here, the global parameters response_code and response_status contain the overall result of processing the request, and the response_result parameter returns an array of objects, each of which contains the result of processing a specific recipient from the request. The message_id parameter contains a unique identifier of the message by which you can retrieve the current delivery status. If it is impossible to send a message to that recipient, the message_id parameter will be null, and the response_code and response_status parameters will provide error information.

Examples of Message Sending Data

Sending an SMS, JSON POST request:

{
   "recipients": [
      "380678998668",
      "380503288668",
      "380638998668"
   ],
   "sms": {
      "sender": "TurboSMS",
      "text": "TurboSMS welcomes you!"
   }
}

The same data, GET request:

https://api.turbosms.ua/message/send.json?recipients[0]=380678998668&recipients[1]=380503288668&recipients[2]=380638998668&sms[sender]=TurboSMS&sms[text]=TurboSMS+welcomes+you%21&token=AUTH_TOKEN

Sending a Viber message:

{
   "recipients": [
      "380678998668",
      "380503288668",
      "380638998668"
   ],
   "viber": {
      "sender": "TurboSMS",
      "text": "TurboSMS welcomes you!"
   }
}

Hybrid sending of Viber:

{
   "recipients": [
      "380678998668",
      "380503288668",
      "380638998668"
   ],
   "viber": {
      "sender": "Viber TurboSMS",
      "text": "TurboSMS welcomes you on Viber!"
   },
   "sms": {
      "sender": "TurboSMS",
      "text": "TurboSMS welcomes you on SMS!"
   }
}

Sending an SMS at a specified time:

{
   "start_time": "2020-03-08 10:00",
   "recipients": [
      "380678998668"
   ],
   "sms": {
      "sender": "TurboSMS",
      "text": "Maksym, happy birthday!"
   }
}

Sending a file in Viber:

{
   "recipients": [
      "380678998668"
   ],
   "viber": {
      "sender": "TurboSMS",
      "file_id": 12345,
      "caption": "Contract.pdf"
   }
}

Sending a file as a link on a button in a Viber message:

{
   "recipients": [
      "380678998668"
   ],
   "viber": {
      "sender": "TurboSMS",
      "text": "An invoice of 1000 hryvnias has been issued for your order №12345.",
      "file_id": 23456,
      "caption": "Download Invoice"
   }
}

Method sendmulti

Example call address:
https://api.turbosms.ua/message/sendmulti.json

This method allows sending multiple send requests in a single HTTP request, saving the time spent on connecting to the API for each request. In other words, calling the sendmulti method with data for 100 requests will be faster than making 100 separate send requests.

General structure of the request body:

{
   "unique_key_for_request_1": {request_data_1},
   "unique_key_for_request_2": {request_data_2},
   ...
   "unique_key_for_request_X": {request_data_X}
}

The server response will return data in the following structure:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": {
      "unique_key_for_request_1": {response_data_for_request_1},
      "unique_key_for_request_2": {response_data_for_request_2},
      ...
      "unique_key_for_request_X": {response_data_for_request_X}
   }
}

The request and response data structures are identical to those of the send method.

Method details

Example call address:
https://api.turbosms.ua/message/details.json

This method allows retrieving details of created messages. To do so, you need to pass a list of message_id as an array.

General structure of the request body:

{
   "messages": [
      "2d80c1c0-5e3c-78c9-134b-2fc4fcbfa0ba",
      "f83f8868-5e46-c6cf-e4fb-615e5a293754",
      "c51f4301-5e3c-78c9-134b-d1ce1e56a9ff"
   ]
}

Response structure:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": [
      {
         "message_id": "2d80c1c0-5e3c-78c9-134b-2fc4fcbfa0ba",
         "sms": null,
         "viber": null,
         "response_code": 414,
         "response_status": "NOT_ALLOWED_MESSAGE_ID"
      },
      {
         "message_id": "f83f8868-5e46-c6cf-e4fb-615e5a293754",
         "sms": {
            "added": "2022-01-25 12:45:32",
            "start": null,
            "sent": "2022-01-25 12:45:32",
            "updated": "2022-01-25 12:45:37",
            "sender": "TurboSMS",
            "text": "TurboSMS welcomes you to SMS!",
            "recipient": "380678998668",
            "status": "Delivered",
            "price": 0.34,
            "segments": 1,
            "ttl": 86400
         },
         "viber": {
            "added": "2022-01-25 12:45:31",
            "start": null,
            "sent": "2022-01-25 12:45:31",
            "updated": "2022-01-25 12:45:32",
            "sender": "TurboSMS",
            "text": "TurboSMS welcomes you to Viber!",
            "recipient": "380678998668",
            "status": "Rejected",
            "rejected_status": "SRVC_NOT_VIBER_USER",
            "price": 0,
            "ttl": 3600,
            "caption": "",
            "action": "",
            "file_id": 0,
            "click_time": null,
            "is_transactional": 0
         },
         "response_code": 0,
         "response_status": "OK"
      },
      {
         "message_id": "c51f4301-5e3c-78c9-134b-d1ce1e56a9ff",
         "sms": null,
         "viber": {
            "added": "2022-01-27 17:13:50",
            "start": "2022-01-28 12:00:00",
            "sent": "2022-01-28 12:00:00",
            "updated": "2022-01-28 12:00:17",
            "sender": "TurboSMS",
            "text": "Maxim, happy birthday!",
            "recipient": "380678998668",
            "status": "Read",
            "rejected_status": "",
            "price": 0.36,
            "ttl": 100,
            "caption": "",
            "action": "",
            "file_id": 0,
            "click_time": null,
            "is_transactional": 1
         },
         "response_code": 0,
         "response_status": "OK"
      }
   ]
}

The response contains two objects: sms and viber, or null if the corresponding object is not found. The parameters of these objects correspond to the parameters of the message/send and message/status methods. The start parameter contains the scheduled sending time, if specified. The segments parameter indicates the number of sms segments, which affects the final cost of the message.

Method status

Sample call address:
https://api.turbosms.ua/message/status.json

This method allows you to retrieve message delivery status information by simply passing a list of message_id as an array.

General format of the request body:

{
   "messages": [
      "2d80c1c0-5e3c-78c9-134b-2fc4fcbfa0ba",
      "f83f8868-5e46-c6cf-e4fb-615e5a293754",
      "c51f4301-5e3c-78c9-134b-d1ce1e56a9ff"
   ]
}

Response structure:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": [
      {
         "message_id": "2d80c1c0-5e3c-78c9-134b-2fc4fcbfa0ba",
         "response_code": 414,
         "response_status": "NOT_ALLOWED_MESSAGE_ID"
      },
      {
         "message_id": "f83f8868-5e46-c6cf-e4fb-615e5a293754",
         "response_code": 0,
         "recipient": "recipient_2",
         "sent": "2020-01-29 10:19:21",
         "updated": "2020-01-29 10:21:32",
         "status": "Read",
         "type": "viber",
         "rejected_status": "",
         "click_time": "2020-01-29 10:22:54",
         "response_status": "OK"
      },
      {
         "message_id": "c51f4301-5e3c-78c9-134b-d1ce1e56a9ff",
         "response_code": 0,
         "recipient": "recipient_3",
         "sent": null,
         "updated": "2020-01-29 18:27:34",
         "status": "Queued",
         "type": "sms",
         "response_status": "OK"
      }
   ]
}

The sent parameter contains the time the message was actually sent. If its value is null, it means the message is still in the queue and will be sent later. The updated parameter reflects the time when the delivery status was updated. The type parameter indicates which channel was used to send the message. For Viber messages, the click_time parameter is also returned, containing the time the button in the message was clicked, or null if the button was not clicked.

Description of the status field values

Description of the rejected_status field values

If a Viber message could not be sent, this field will contain the reason. In the case of a successful send, this field will be an empty string.

chat Module

This module provides functionality for working with Viber chats.

Method senders

Sample call address:
https://api.turbosms.ua/chat/senders.json

This method returns an array of objects with the user's sender data. The request body is empty.

Response structure:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": [
      {
         "id": 1,
         "name": "TurboSMS",
         "status": "OK",
         "logo_url": "/user-files/viber-logo/0e1/ed0/eb7/5bed39ee1c676789700607.png",
         "start_date": "2020-01-01",
         "reserve": 8400,
         "spent": 1234.56,
         "balance": 7165.44,
         "paid_date": "2023-12-01",
         "2way": 1,
         "recipients": 34567,
         "unread_messages": 7,
         "last_message_date": "2022-10-01 15:34:18"
      },
      {
         "id": 2,
         "name": "Mobibon",
         "status": "OK",
         "logo_url": "/user-files/viber-logo/fc4/163/53a/7c193960f07a63ce553dbd6235bc0a80.png",
         "start_date": "2020-01-01",
         "reserve": 8400,
         "spent": 2345.67,
         "balance": 6054.33,
         "paid_date": "2099-01-01",
         "2way": 0,
         "recipients": 0,
         "unread_messages": 0,
         "last_message_date": ""
      }
   ]
}

Description of the Response Parameters

Method recipients

Example call address:
https://api.turbosms.ua/chat/recipients.json

This method returns an array of the sender's recipients. The sender can be specified either using the sender_id parameter with its ID or using the sender parameter with its name. Since there may be many recipients, there is an option to select a limited number of records with pagination support. Use the page parameter to pass the page number and rows for the number of records to return. By default, a set of 30 recipients is returned, with a maximum rows value of 500. Adding the new_only parameter will return only those recipients with unread messages, up to 30 per request.

Example requests:

{
   "sender_id": 1,
   "page": 10,
   "rows": 50
}

{
   "sender": "TurboSMS",
   "new_only": 1
}

Example response:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": [
      {
         "chat_id": 1234,
         "number": "380501234567",
         "contact_id": 2345,
         "name": "Vasiliy Pupkin",
         "total_messages": 123,
         "unread_messages": 3,
         "last_message_date": "2022-10-03 12:51:38"
      },
      {
         "chat_id": 2345,
         "number": "380672345678",
         "contact_id": 0,
         "name": "",
         "total_messages": 7,
         "unread_messages": 0,
         "last_message_date": "2022-10-02 16:14:41"
      }
   ]
}

Description of Response Parameter Values

Method sessions

Example call address:
https://api.turbosms.ua/chat/sessions.json

This method returns an array of session data. Parameters can include either the chat ID in chat_id or the session ID in session_id. The method also supports pagination parameters.

Example requests:

{
   "chat_id": 1234,
   "rows": 10
}

{
   "session_id": 123321
}

Example response:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": [
      {
         "id": 123456,
         "price": 0.88,
         "started": "2022-10-04 11:51:29",
         "ended": null,
         "sent_messages": 16,
         "unreplied_messages": 2
      },
      {
         "id": 123321,
         "price": 0.88,
         "started": "2022-10-03 09:12:41",
         "ended": "2022-10-04 09:12:41",
         "sent_messages": 31,
         "unreplied_messages": 0
      }
   ]
}

The response includes the session ID, its cost in the local currency (charged from the sender's or user's balance), start and end dates and times, as well as the number of sent and consecutively unreplied session messages. If the end time is null, the session is still active and session messages can be sent within it.

Method messages

Sample call address:
https://api.turbosms.ua/chat/messages.json

This method returns an array of chat messages. To retrieve the messages of a specific chat, you can pass its id in the chat_id parameter. This method also supports limiting the amount of data in the response with pagination, and messages are returned sorted by the time they were added, from newest to oldest. If the new_only parameter is specified, only unread messages will be returned; in this case, the pagination parameters are ignored, and the method returns all new messages of the specified chat. Please note that all unread messages returned by this method will automatically be marked as read by the system. You can also pass a message id in the last_message_id parameter, in which case an array of messages following that id will be returned, sorted from oldest to newest.

Request examples:

{
   "chat_id": 1234,
   "page": 2,
   "rows": 15
}

{
   "chat_id": 1234,
   "last_message_id": 1000
}

{
   "chat_id": 2345,
   "new_only": 1
}

Sample response:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": [
      {
         "id": 1391,
         "chat_id": 1234,
         "added": "2022-10-03 09:18:52",
         "type": "Outbox",
         "message": "Your order has been shipped, tracking number 1234567890",
         "status": "Delivered",
         "file_id": 0,
         "file_url": "https://turbosms.ua/user-files/f46/ce1/91b/123456.pdf",
         "file_source": "",
         "button_caption": "",
         "button_action": "",
         "session_id": 123456
      },
      {
         "id": 1248,
         "chat_id": 1234,
         "added": "2022-10-02 18:51:38",
         "type": "Inbox",
         "message": "",
         "status": "Read",
         "file_id": 12387,
         "file_url": "https://turbosms.ua/user-files/f46/ce1/91b/123456.pdf",
         "file_name": "scan.pdf",
         "button_caption": "",
         "button_action": "",
         "session_id": 123456
      },
      {
         "id": 1234,
         "chat_id": 1234,
         "added": "2022-10-02 18:37:12",
         "type": "Outbox",
         "message": "The item is reserved, please download the invoice and send a scan of its payment.",
         "status": "Read",
         "file_id": 0,
         "file_url": "",
         "file_name": "",
         "button_caption": "Download the invoice",
         "button_action": "https://turbosms.ua/user-files/f46/ce1/91b/123110.pdf",
         "session_id": 0
      }
   ]
}

Description of the Response Parameters

Method send

Example call address:
https://api.turbosms.ua/chat/send.json

This method sends a session message to the chat specified in the chat_id parameter. Messages can contain either text in the message parameter or a file. The data scheme of the file can be passed in the file_data parameter, with the file_name parameter specifying the file name visible to the recipient. Alternatively, a file's URL can be provided in the file_url parameter instead of the data scheme.

Example requests:

{
   "chat_id": 1234,
   "message": "Your payment has been received. Please wait for shipping information."
}

{
   "chat_id": 1234,
   "file_name": "Presentation.pdf",
   "file_data": "data:application/pdf;base64,JVBERi0xLjMKJcTl8uXrp/Og0M....lRU9GCg=="
}

Example response:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": {
      "message_id": 17693
   }
}

User Module

The module provides functionality for managing user account data.

Method balance

Example call address:
https://api.turbosms.ua/user/balance.json

This method returns the user's account balance. The request body is empty.

Response structure:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": {
      "balance": 12345.67
   }
}

File Module

The module provides functionality for managing user files.

Method add

Example call address:
https://api.turbosms.ua/file/add.json

This method allows uploading a file to our server. The file can be provided either as a URL, from which it will be downloaded, or directly in the request body in the data parameter. This parameter should contain the file content in data scheme format according to RFC 2397 (details). The data scheme can include the file content either as a base64 string or in an unencoded format.

Note that when sending a request via the GET method, you may encounter a URL length limitation of 2KB. To avoid this, send the request using the POST method when including the file in the data parameter.

Example requests:

{
   "url": "https://turbosms.ua/files/news/http-api.png"
}

{
   "data": "data:image/gif;base64,R0lGODlhEgASAIIAAHqIltvp9/L4/+nz/+by/5imtN7s+gAAACH5BAAAAAAALAAAAAASABIAAAhxAAsIHEiwIEEBCBMqXChAIMOHCR1CfChwgIGLGDNmHFBRo0eMHAtYxAgAAEmTF0OOvFjSZEuQHTO2LLkxpkyaNUVqnIkypU0DL1/61Hmy6NCVH3MSSOqRgEACAQxEnSq1alSnBaAG2Mq1K1esBsMSDAgAOw=="
}

Response structure:

{
   "response_code": 0,
   "response_status": "OK",
   "response_result": {
       "id": 32895,
       "link": "https://turbosms.ua/public/4ce/14a/c31/32895.jpg",
       "source": "https://turbosms.ua/files/news/http-api.png",
       "size": 12555,
       "created": "2021-01-21 18:00:09"
   }
}

The id value can be used in Viber campaigns. The link parameter contains a public link to the file, which can be accessed directly. The source parameter indicates the original file source specified during upload. The size parameter shows the file size in bytes, and the created parameter provides the date the file was saved to our server.

It is worth noting that when a file is uploaded, it is checked for duplicates. If the file has already been uploaded previously, the details of the existing file will be returned.

Method details

Sample call address:
https://api.turbosms.ua/file/details.json

This method returns file details for the passed id.

Sample request:

{
   "id": 32895
}

The response of this method is completely identical to the response of the file adding method.

Description of Request Processing Result Codes