TurboSMS HTTP API

https://turbosms.ua/en/api.html
Admin
TurboSMS provides an HTTP API for developers to programmatically send SMS and Viber messages, manage...
Tokens:30,512
Snippets:73
Trust Score:9.7
Update:11 months ago
Show doc for...
Tokens:
Raw
### TurboSMS API Message Details Response Example

Source: https://turbosms.ua/en/api.html/index

This example shows the structure of a successful response from the TurboSMS API when requesting message details. It includes message ID, status, and specific details for SMS and Viber messages, such as sender, text, recipient, and price.

```json
{
   "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",
            "message_type": "promotional",
            "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!",
            "message_type": "transactional",
            "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"
      },
      {
         "message_id": "c51f4301-5e3c-78c9-134b-d1ce1e56afd4",
         "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": "Super Shop",
            "recipient": "380678998668",
            "message_type": "carousel",
            "text": "You haven\'t ordered anything in a long time, we miss you and are giving you a 10% discount 🤗",
            "carousel": [
               {
                 "image_url": "https://turbosms.ua/user-files/a67/71c/91b/1545256.jpg",
                 "file_id": 13572,
                 "title": "Bowl with avocado and salmon",
                 "button_caption": "I want it!",
                 "button_url": "https://super-shop.com/cart/add/bowl-avocado-salmon.html",
                 "link_caption": "More details",
                 "link_url": "https://super-shop.com/items/bowl-avocado-salmon.html"
               },
               {
                 "image_url": "https://turbosms.ua/user-files/4ba/fc5/91d/15223508.png",
                 "file_id": 123456,
                 "title": "Tempura vegetables with shrimp",
                 "button_caption": "Or this!",
                 "button_url": "https://super-shop.com/cart/add/birthday/tempura-vegetables-shrimps.html",
                 "link_caption": "More details",
                 "link_url": "https://super-shop.com/items/tempura-vegetables-shrimps.html"
               },
               {
                 "image_url": "https://turbosms.ua/user-files/f46/ce1/91b/123110.jpg",
                 "file_id": 234567,
                 "title": "Dragon Roll Platter",
                 "button_caption": "Definitely",
                 "button_url": "https://super-shop.com/cart/add/birthday/set-dragon-rolls.html",
                 "link_caption": "More details",
                 "link_url": "https://super-shop.com/items/set-dragon-rolls.html"
               }
            ],
            "status": "Read",
            "rejected_status": ""
         },
         "response_code": 0,
         "response_status": "OK"
      }
   ]
}
```

--------------------------------

### TurboSMS API Sessions Method: Example JSON Requests

Source: https://turbosms.ua/en/api.html/index

Demonstrates different ways to call the TurboSMS API sessions method using JSON payloads. These examples show how to filter sessions by chat ID, session ID, or sender and recipient information. The 'rows' parameter is included for pagination.

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

```json
{
   "session_id": 123321
}
```

```json
{
   "sender": "TurboSMS",
   "recipients": [
      "380678998668",
      "380503288668",
      "380638998668"
   ]
}
```

--------------------------------

### TurboSMS API: Fetch Chat Messages (JSON Request Examples)

Source: https://turbosms.ua/en/api.html/index

Examples of JSON payloads to request chat messages from the TurboSMS API. These demonstrate filtering by chat ID, pagination, retrieving only new messages, or specifying sender and recipients.

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

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

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

```json
{
   "sender": "TurboSMS",
   "recipients": [
      "380678998668",
      "380503288668",
      "380638998668"
   ]
}
```

--------------------------------

### Send SMS via GET Request

Source: https://turbosms.ua/en/api.html/index

Illustrates sending an SMS message using a GET request with URL-encoded parameters. This method is an alternative to POST for simpler requests. Note that sensitive data like authentication tokens should be handled with care when using GET.

```url
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
```

--------------------------------

### GET /message/send.json (SMS - Query Parameters)

Source: https://turbosms.ua/en/api.html/index

Sends a standard SMS message using query parameters in a GET request. This method is less common for sending messages compared to POST.

```APIDOC
## GET /message/send.json (SMS - Query Parameters)

### Description
Sends a standard SMS message using query parameters in a GET request. This method is less common for sending messages compared to POST.

### Method
GET

### Endpoint
/message/send.json

### Parameters
#### Query Parameters
- **recipients[index]** (string) - Required - Phone numbers of recipients (e.g., `recipients[0]=380678998668`).
- **sms[sender]** (string) - Required - The sender ID of the message.
- **sms[text]** (string) - Required - The content of the SMS message (URL encoded).
- **token** (string) - Required - Your authentication token.

### Request Example
```
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
```

### Response
#### Success Response (200)
- **response_code** (integer) - Status code of the response.
- **response_status** (string) - Status message of the response.
- **response_result** (object) - Result of the operation. (Structure is similar to POST /message/send)

#### Response Example
```json
{
  "response_code": 0,
  "response_status": "OK",
  "response_result": {
    "message_id": "1234567891",
    "balance": 99.00,
    "message": {
      "text": "TurboSMS welcomes you!",
      "sender": "TurboSMS",
      "recipient": "380678998668",
      "status": "Delivered",
      "status_code": 1
    }
  }
}
```
```

--------------------------------

### Get Message Details using TurboSMS API

Source: https://turbosms.ua/en/api.html/index

This snippet demonstrates how to request message details from the TurboSMS API. It requires a list of message IDs in the request body. The response contains detailed information for each message, including delivery status and pricing.

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

--------------------------------

### Send SMS and Viber Messages using TurboSMS API

Source: https://turbosms.ua/en/api.html/index

This example demonstrates how to send SMS, Viber, or hybrid messages using the TurboSMS API's 'send' method. It shows the general structure of the request body, including global parameters, recipients, and optional 'viber' and 'sms' specific parameters. The 'sequence_id' parameter can be added for idempotency.

```json
{
   "sequence_id": "your_unique_request_identifier_123",
   "recipients": [
      "+1234567890",
      "+0987654321"
   ],
   "sms": {
      "text": "Hello from SMS!",
      "sender_id": "YourSenderName"
   },
   "viber": {
      "text": "Hello from Viber!",
      "sender_id": "YourSenderName"
   }
}
```

```json
{
   "sequence_id": "your_unique_request_identifier_456",
   "recipients": [
      "+1234567890"
   ],
   "sms": {
      "text": "This is a hybrid message."
   },
   "viber": {
      "text": "This is a hybrid message."
   }
}
```

```json
{
   "sequence_id": "your_unique_request_identifier_789",
   "recipients": [
      "+1234567890"
   ],
   "sms": {
      "text": "Sending only SMS."
   }
}
```

--------------------------------

### TurboSMS API Sessions Method: Example JSON Response

Source: https://turbosms.ua/en/api.html/index

Illustrates the structure of a successful response from the TurboSMS API sessions method. The response contains a status code, status message, and a list of session result objects, each detailing session ID, sender, recipient, chat ID, price, timestamps, and message statistics.

```json
{
   "response_code": 0,
   "response_status": "OK",
   "response_result": [
      {
         "id": 123456,
         "sender_id": 1,
         "sender": "TurboSMS",
         "recipient": 380678998668,
         "chat_id": 1234,
         "price": 0.88,
         "started": "2022-10-04 11:51:29",
         "ended": null,
         "sent_messages": 16,
         "unreplied_messages": 2
      },
      {
         "id": 123321,
         "sender_id": 1,
         "sender": "TurboSMS",
         "recipient": 380678998668,
         "chat_id": 1234,
         "price": 0.88,
         "started": "2022-10-03 09:12:41",
         "ended": "2022-10-04 09:12:41",
         "sent_messages": 31,
         "unreplied_messages": 0
      }
   ]
}
```

--------------------------------

### Get File Details using TurboSMS API

Source: https://turbosms.ua/en/api.html/index

Retrieves details of a previously uploaded file from the TurboSMS server using its unique 'id'. The response structure is identical to the file adding method, including 'id', 'link', 'source', 'size', and 'created' information.

```json
{
   "id": 32895
}
```

--------------------------------

### GET /message/details

Source: https://turbosms.ua/en/api.html/index

Retrieves details about a previously sent message.

```APIDOC
## GET /message/details

### Description
This endpoint allows you to fetch detailed information about a specific message, such as its status, delivery time, and cost, using its unique message ID.

### Method
`GET`

### Endpoint
`https://api.turbosms.ua/message/details.json`

### Parameters
#### Query Parameters
- **token** (string) - Required - Your authentication token.
- **message_id** (string) - Required - The unique identifier of the message you want details for.

### Request Example
`https://api.turbosms.ua/message/details.json?token=_AUTH_TOKEN_&message_id=12345abcde`

### Response
#### Success Response (200)
- **response_code** (integer) - The numeric code for the request processing result.
- **response_status** (string) - The status of the request processing result.
- **response_result** (object | null) - An object containing the details of the message, or null if not found.
  - **id** (string) - Message ID.
  - **status** (string) - Delivery status (e.g., "sent", "delivered", "failed").
  - **cost** (number) - Cost of the message.
  - **send_time** (string) - Timestamp when the message was sent.
  - **delivery_time** (string) - Timestamp when the message was delivered (if applicable).

#### Response Example
```json
{
  "response_code": 0,
  "response_status": "OK",
  "response_result": {
    "id": "12345abcde",
    "status": "delivered",
    "cost": 0.05,
    "send_time": "2023-10-27T10:00:00Z",
    "delivery_time": "2023-10-27T10:05:00Z"
  }
}
```
```

--------------------------------

### GET /message/status

Source: https://turbosms.ua/en/api.html/index

Retrieves the delivery status of a specific message.

```APIDOC
## GET /message/status

### Description
This endpoint is used to check the current delivery status of a message using its unique message ID.

### Method
`GET`

### Endpoint
`https://api.turbosms.ua/message/status.json`

### Parameters
#### Query Parameters
- **token** (string) - Required - Your authentication token.
- **message_id** (string) - Required - The unique identifier of the message.

### Request Example
`https://api.turbosms.ua/message/status.json?token=_AUTH_TOKEN_&message_id=12345abcde`

### Response
#### Success Response (200)
- **response_code** (integer) - The numeric code for the request processing result.
- **response_status** (string) - The status of the request processing result.
- **response_result** (object | null) - An object containing the status of the message.
  - **status** (string) - The current delivery status (e.g., "sent", "delivered", "failed").

#### Response Example
```json
{
  "response_code": 0,
  "response_status": "OK",
  "response_result": {
    "status": "delivered"
  }
}
```
```

--------------------------------

### Get User Balance via TurboSMS API

Source: https://turbosms.ua/en/api.html/index

Retrieves the current account balance for a user via the TurboSMS API. This method requires no parameters in the request body and returns the balance in the response.

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

--------------------------------

### Send Scheduled SMS Message

Source: https://turbosms.ua/en/api.html/index

Provides an example of scheduling an SMS message to be sent at a specific future time using a JSON POST request. This feature is useful for time-sensitive notifications or campaigns. The 'start_time' parameter dictates the delivery schedule.

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

--------------------------------

### API Overview

Source: https://turbosms.ua/en/api.html/index

General information about the TurboSMS API, including base URL, authentication methods, data transmission, and response structure.

```APIDOC
## API Overview

### Base URL
`https://api.turbosms.ua/module/method.format`

### Authentication
Authentication can be provided via:
- **GET parameter**: `token=_AUTH_TOKEN_`
- **POST parameter**: `token=_AUTH_TOKEN_` (with `Content-Type: application/x-www-form-urlencoded` header)
- **HTTP header**: `Authorization: Basic _AUTH_TOKEN_`
- **HTTP header**: `Authorization: Bearer _AUTH_TOKEN_`

### Data Transmission
Data can be sent using:
- **GET parameters** (URL length limit: 2000 characters)
- **POST parameters** (with `Content-Type: application/x-www-form-urlencoded` header)
- **POST request body** (with `Content-Type: application/json` header for JSON data)

*Note: Only one data transmission method can be used per request.*

### Response Format
Responses are currently supported in **JSON** format. Specifying the format in the URL is recommended.

### Standard Response Structure
```json
{
   "response_code": 0,
   "response_status": "OK",
   "response_result": null
}
```

- **response_code**: Numeric code for request processing result (0-999).
- **response_status**: Brief description of the request processing outcome.
- **response_result**: Response data (null, object, or array of objects).

### Ping Method
Each module has a `ping` method to test API status.

**Response Example:**
```json
{
   "response_code": 1,
   "response_status": "PONG",
   "response_result": null
}
```
```

--------------------------------

### GET /chat/senders.json

Source: https://turbosms.ua/en/api.html/index

Retrieves a list of the user's sender data. By default, it returns all senders. You can filter by sender ID or name.

```APIDOC
## GET /chat/senders.json

### Description
This method returns an array of objects with the user's sender data. If the request body is empty, data for all senders that have ever been active will be returned. If you pass the sender ID to `sender_id` or its name to `sender`, only data for the specified sender will be returned.

### Method
GET

### Endpoint
https://api.turbosms.ua/chat/senders.json

### Query Parameters
- **sender_id** (integer) - Optional - The ID of the sender to retrieve data for.
- **sender** (string) - Optional - The name of the sender to retrieve data for.

### Response
#### Success Response (200)
- **response_code** (integer) - The status code of the response.
- **response_status** (string) - The status message of the response.
- **response_result** (array) - An array of sender objects, each containing:
    - **id** (integer) - The sender's ID.
    - **name** (string) - The sender's name.
    - **status** (string) - The sender's status (e.g., "OK", "frozen").
    - **logo_url** (string) - The path to the sender's logo.
    - **start_date** (string) - The date the sender began operating.
    - **reserve** (integer) - The amount reserved for the sender's use.
    - **spent** (float) - The amount spent by the sender.
    - **balance** (float) - The available balance for the sender.
    - **paid_date** (string) - The date through which the sender is paid.
    - **2way** (integer) - Support for two-way messaging (1 for yes, 0 for no).
    - **recipients** (integer) - The number of recipients (only for 2way senders).
    - **unread_messages** (integer) - The number of unread incoming messages (only for 2way senders).
    - **last_message_date** (string) - The date and time of the last message.

#### Response Example
```json
{
   "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"
      }
   ]
}
```
```

--------------------------------

### POST /file/add.json

Source: https://turbosms.ua/en/api.html/index

Uploads a file to the server. The file can be provided via a URL or directly in the request body. Supports various file types and has a size limit of 3MB.

```APIDOC
## POST /file/add.json

### Description
Uploads a file to the TurboSMS server. The file can be provided either as a URL or directly in the request body using the `data` parameter. The `data` parameter should contain the file content in data scheme format (RFC 2397), which can be base64 encoded or unencoded.

**Note:** When providing the file content directly, use the POST method to avoid URL length limitations.

Supported file extensions include: doc, docx, rtf, dot, dotx, odt, odf, fodt, txt, pdf, xps, pdax, eps, xls, xlsx, ods, fods, csv, xlsm, xltx, jpg, jpeg, png. The maximum file size is 3MB.

### Method
POST

### Endpoint
https://api.turbosms.ua/file/add.json

### Parameters
#### Request Body
- **url** (string) - Optional - A URL from which the file will be downloaded.
- **data** (string) - Optional - The file content in data scheme format (e.g., `data:image/png;base64,iVBORw0KGgo...`).

**Note:** Either `url` or `data` must be provided.

### Request Example
```json
{
   "url": "https://turbosms.ua/files/news/http-api.png"
}
```

```json
{
   "data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABIAAAASCAYAAABWzo5XAAAAwElEQVR4AayPMQ7CMBAET/keHSV1HkWRmgegUOZHlEgUkRU8ltY6WRjkxJE2d7f2Ti7D9TZvPTRYfC7nkx1RRFgC0RxVX9B7NXu+1l0iy9/03QhiqWmaDHmfGXlP/d+NFFRVsKxV0DiO+a6HeD9fiE0VFM+sDJUzd6SfIL8JgXLGk6ogH/KbeF8QahXEIRJEFe+bqiCCyIeYkffUJ1DYNLZXZROIeAiBYq01heIrg2LfDNFHySbQfX7Ysiy7RBbQBwAA//8FpsY7AAAABklEQVQDAFVE4hfSuaVLAAAAAElFTkSuQmCC"
}
```

### Response
#### Success Response (0)
- **response_code** (integer) - Status code, 0 indicates success.
- **response_status** (string) - Status message, "OK" for success.
- **response_result** (object)
  - **id** (integer) - The unique identifier of the uploaded file.
  - **link** (string) - A public URL to the uploaded file.
  - **source** (string) - The original source of the file (URL or provided data).
  - **size** (integer) - The size of the file in bytes.
  - **created** (string) - The date and time when the file was saved on the server.

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

**Note:** If the file has been uploaded previously, details of the existing file will be returned.
```

--------------------------------

### GET /chat/messages.json

Source: https://turbosms.ua/en/api.html/index

Retrieves an array of chat messages. Supports filtering by chat ID, sender, recipients, and message status. Includes pagination and sorting options.

```APIDOC
## GET /chat/messages.json

### Description
This method returns an array of chat messages. You can retrieve messages for a specific chat by providing its `ID` in the `chat_id` parameter. Alternatively, you can use `sender_id` or `sender` to identify the sender, along with the `recipients` array to specify for whom you want to receive data. The method supports pagination to limit the amount of data returned, and messages are sorted by time added, from newest to oldest. If `new_only` is specified, only unread messages are returned, and pagination parameters are ignored.

### Method
GET

### Endpoint
`https://api.turbosms.ua/chat/messages.json`

### Parameters
#### Query Parameters
- **chat_id** (integer) - Optional - The ID of the chat to retrieve messages from.
- **sender_id** (integer) - Optional - The ID of the sender.
- **sender** (string) - Optional - The name of the sender.
- **recipients** (array of strings) - Optional - An array of recipient phone numbers.
- **page** (integer) - Optional - The page number for pagination. Ignored if `new_only` is set.
- **rows** (integer) - Optional - The number of rows per page. Ignored if `new_only` is set.
- **new_only** (integer) - Optional - If set to 1, returns only unread messages. Pagination is ignored in this case.
- **last_message_id** (integer) - Optional - Returns messages following this message ID, sorted from oldest to newest.

### Request Example
```json
{
   "chat_id": 1234,
   "page": 2,
   "rows": 15
}
```

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

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

```json
{
   "sender": "TurboSMS",
   "recipients": [
      "380678998668",
      "380503288668",
      "380638998668"
   ]
}
```

### Response
#### Success Response (200)
- **response_code** (integer) - The status code of the response.
- **response_status** (string) - The status message of the response.
- **response_result** (array) - An array of message objects.
  - **id** (integer) - The message ID.
  - **sender_id** (integer) - The sender's ID.
  - **sender** (string) - The sender's name.
  - **recipient** (integer) - The recipient's phone number.
  - **chat_id** (integer) - The ID of the chat.
  - **added** (string) - The timestamp when the message was added.
  - **type** (string) - The type of the message (e.g., 'Inbox', 'Outbox').
  - **message_id** (string) - The unique message identifier.
  - **message** (string) - The content of the message.
  - **message_type** (string) - The type of message (e.g., 'session', 'survey', 'transactional', 'promotional').
  - **status** (string) - The delivery status of the message.
  - **file_id** (integer) - The ID of an attached file.
  - **file_url** (string) - The URL of an attached file.
  - **file_name** (string) - The name of an attached file.
  - **button_caption** (string) - The caption for an action button.
  - **button_action** (string) - The action associated with the button.
  - **replied_message_id** (integer) - The ID of the message this message is a reply to.
  - **replied_message** (string) - The content of the message this message is a reply to.
  - **session_id** (integer) - The ID of the session the message belongs to.
  - **survey** (array of strings) - An array of survey options if the message type is 'survey'.

#### Response Example
```json
{
   "response_code": 0,
   "response_status": "OK",
   "response_result": [
      {
         "id": 1462,
         "sender_id": 1,
         "sender": "SuperShop",
         "recipient": 380678998668,
         "chat_id": 1234,
         "added": "2022-10-09 17:52:29",
         "type": "Inbox",
         "message_id": "",
         "message": "😍 Definitely yes",
         "message_type": "session",
         "status": "Read",
         "file_id": 0,
         "file_url": "",
         "file_name": "",
         "button_caption": "",
         "button_action": "",
         "replied_message_id": 1391,
         "replied_message": "Did you like the items sent in your last order?",
         "session_id": 123678
      }
   ]
}
```
```

--------------------------------

### Chat Module - Viber

Source: https://turbosms.ua/en/api.html/index

Provides functionality for working with Viber chats.

```APIDOC
## Chat Module

This module provides functionality for working with **Viber** chats.
```

--------------------------------

### POST /file/details.json

Source: https://turbosms.ua/en/api.html/index

Retrieves details for a previously uploaded file using its ID.

```APIDOC
## POST /file/details.json

### Description
Retrieves the details of a file that has been previously uploaded using its unique identifier.

### Method
POST

### Endpoint
https://api.turbosms.ua/file/details.json

### Parameters
#### Request Body
- **id** (integer) - Required - The unique identifier of the file whose details are to be retrieved.

### Request Example
```json
{
   "id": 32895
}
```

### Response
#### Success Response (0)
- **response_code** (integer) - Status code, 0 indicates success.
- **response_status** (string) - Status message, "OK" for success.
- **response_result** (object)
  - **id** (integer) - The unique identifier of the uploaded file.
  - **link** (string) - A public URL to the uploaded file.
  - **source** (string) - The original source of the file (URL or provided data).
  - **size** (integer) - The size of the file in bytes.
  - **created** (string) - The date and time when the file was saved on the server.

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

**Note:** The response structure is identical to the file adding method.
```

--------------------------------

### Get Message Status (JSON Request)

Source: https://turbosms.ua/en/api.html/index

This snippet demonstrates how to structure a JSON request to the TurboSMS API's message status endpoint. It requires an array of message IDs to retrieve the delivery status for.

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

--------------------------------

### Upload File via URL using TurboSMS API

Source: https://turbosms.ua/en/api.html/index

Uploads a file to the TurboSMS server using a provided URL. The request should be sent via POST to avoid URL length limitations. This method is part of the File Module.

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

--------------------------------

### Retrieve Message Status (JSON Response)

Source: https://turbosms.ua/en/api.html/index

This is an example JSON response from the TurboSMS API when querying message statuses. It includes details for each message ID, such as recipient, sent time, status, and type (SMS or Viber).

```json
{
   "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"
      }
   ]
}
```

--------------------------------

### GET /chat/sessions.json

Source: https://turbosms.ua/en/api.html/index

Retrieves an array of session data for chat interactions. You can filter sessions by chat ID, session ID, sender information, or recipient details. The method also supports pagination for managing large datasets.

```APIDOC
## GET /chat/sessions.json

### Description
This method returns an array of session data. You can filter sessions by providing either the chat ID in `chat_id` or the session ID in `session_id`. Alternatively, you can use `sender_id` or `sender` along with an array of `recipients` to identify the sender and desired recipients. The method also supports pagination parameters.

### Method
GET

### Endpoint
https://api.turbosms.ua/chat/sessions.json

### Parameters
#### Query Parameters
- **chat_id** (integer) - Optional - The ID of the chat.
- **session_id** (integer) - Optional - The ID of the session.
- **sender_id** (integer) - Optional - The ID of the sender.
- **sender** (string) - Optional - The name of the sender.
- **recipients** (array of strings) - Optional - An array of recipient phone numbers.
- **rows** (integer) - Optional - Number of records per page for pagination.
- **page** (integer) - Optional - The page number for pagination.

### Request Example
```json
{
   "chat_id": 1234,
   "rows": 10
}

{
   "session_id": 123321
}

{
   "sender": "TurboSMS",
   "recipients": [
      "380678998668",
      "380503288668",
      "380638998668"
   ]
}
```

### Response
#### Success Response (200)
- **response_code** (integer) - Status code of the response.
- **response_status** (string) - Status message of the response.
- **response_result** (array of objects) - An array containing session data.
  - **id** (integer) - The unique identifier for the session.
  - **sender_id** (integer) - The ID of the sender.
  - **sender** (string) - The name of the sender.
  - **recipient** (integer) - The recipient's phone number.
  - **chat_id** (integer) - The ID of the chat associated with the session.
  - **price** (float) - The cost of the session in local currency.
  - **started** (string) - The start date and time of the session (YYYY-MM-DD HH:MM:SS).
  - **ended** (string|null) - The end date and time of the session (YYYY-MM-DD HH:MM:SS) or null if the session is still active.
  - **sent_messages** (integer) - The number of messages sent within the session.
  - **unreplied_messages** (integer) - The number of consecutively unreplied messages.

#### Response Example
```json
{
   "response_code": 0,
   "response_status": "OK",
   "response_result": [
      {
         "id": 123456,
         "sender_id": 1,
         "sender": "TurboSMS",
         "recipient": 380678998668,
         "chat_id": 1234,
         "price": 0.88,
         "started": "2022-10-04 11:51:29",
         "ended": null,
         "sent_messages": 16,
         "unreplied_messages": 2
      },
      {
         "id": 123321,
         "sender_id": 1,
         "sender": "TurboSMS",
         "recipient": 380678998668,
         "chat_id": 1234,
         "price": 0.88,
         "started": "2022-10-03 09:12:41",
         "ended": "2022-10-04 09:12:41",
         "sent_messages": 31,
         "unreplied_messages": 0
      }
   ]
}
```
```

--------------------------------

### File API Endpoints

Source: https://turbosms.ua/en/api.html/index

Endpoints for managing files, such as uploading and retrieving file details.

```APIDOC
## File API Endpoints

### POST /file/add
Uploads a file to the system.

### GET /file/details
Retrieves details about a previously uploaded file.
```

--------------------------------

### User API Endpoints

Source: https://turbosms.ua/en/api.html/index

Endpoints for user account management, such as checking the user's balance.

```APIDOC
## User API Endpoints

### GET /user/balance
Retrieves the current account balance for the user.

#### Parameters
- **token** (string) - Required - Your authentication token.

#### Response Example (Success)
```json
{
  "response_code": 0,
  "response_status": "OK",
  "response_result": {
    "balance": 100.50
  }
}
```
```

--------------------------------

### POST /message/send (Viber - File Link Button)

Source: https://turbosms.ua/en/api.html/index

Sends a Viber message with a button linking to a file.

```APIDOC
## POST /message/send (Viber - File Link Button)

### Description
Sends a Viber message with a button linking to a file.

### Method
POST

### Endpoint
/message/send

### Parameters
#### Request Body
- **recipients** (array[string]) - Required - An array of phone numbers to send the message to.
- **viber** (object) - Required - An object containing Viber message details.
  - **sender** (string) - Required - The sender ID of the message.
  - **text** (string) - Required - The main text of the Viber message.
  - **file_id** (integer) - Required - The ID of the file to be linked.
  - **caption** (string) - Required - The text displayed on the button.

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

### Response
#### Success Response (200)
- **response_code** (integer) - Status code of the response.
- **response_status** (string) - Status message of the response.
- **response_result** (object) - Result of the operation. (Structure is similar to POST /message/send for SMS)

#### Response Example
```json
{
  "response_code": 0,
  "response_status": "OK",
  "response_result": {
    "message_id": "7788990011",
    "balance": 97.00,
    "message": {
      "text": "An invoice of 1000 hryvnias has been issued for your order №12345.",
      "sender": "TurboSMS",
      "recipient": "380678998668",
      "status": "Delivered",
      "status_code": 1
    }
  }
}
```
```

--------------------------------

### Send Carousel of Product Cards in Viber Message

Source: https://turbosms.ua/en/api.html/index

Provides an example of sending a carousel of product cards in a Viber message. This rich media format is ideal for showcasing multiple items, each with an image, title, and call-to-action buttons. It's effective for e-commerce promotions.

```json
{
   "recipients": [
      "380678998668"
   ],
   "viber": {
      "sender": "Super FOOD",
      "text": "Only today, on your birthday, we are giving you one of the dishes you ordered most often:",
      "carousel": [
         {
           "image_url": "https://www.willcookforsmiles.com/wp-content/uploads/2025/02/Avocado-salmon-rice-bowl-in-a-bowl.jpg",
           "title": "Bowl with avocado and salmon",
           "button_caption": "I want it!",
           "button_url": "https://super-food.com/order/birthday/bowl-avocado-salmon.html",
           "link_caption": "More details",
           "link_url": "https://super-food.com/bowls/bowl-avocado-salmon.html"
         },
         {
           "file_id": 123456,
           "title": "Tempura vegetables with shrimp",
           "button_caption": "Or this!",
           "button_url": "https://super-food.com/order/birthday/tempura-vegetables-shrimps.html",
           "link_caption": "More details",
           "link_url": "https://super-food.com/tempura/tempura-vegetables-shrimps.html"
         },
         {
           "file_id": 234567,
           "title": "Dragon Roll Platter",
           "button_caption": "Definitely",
           "button_url": "https://super-food.com/order/birthday/set-dragon-rolls.html",
           "link_caption": "More details",
           "link_url": "https://super-food.com/sets/set-dragon-rolls.html"
         }
      ]
   }
}
```
Tokens:
Raw