# General Info

The Direct API service is designed to send messages via various communication channels under the HTTP protocol. The following channels are supported:

* SMS
* FlashCall
* Viber
* WhatsApp
* VK

Also, using the service, you can

* create, view and edit system entities
  * senders’ names
  * templates
* get statistics on the messages sent


# Authorization

In all requests, authorization occurs using an api-key. In this case, the keys are divided into two types:

1. to deal with traffic (in the description of methods – `TOKEN_1`)
2. to deal with system entities (in the description of methods –`TOKEN_2`)

For generating and receiving the key regardless of type, please contact your manager. 


# Connection check

## The method allows checking the connection and performance of our systems

<mark style="color:blue;">`GET`</mark> `https://direct.revicom.ltd/api/v1/ping`

Authorization is not required

{% tabs %}
{% tab title="200: OK " %}

```javascript
```

{% endtab %}
{% endtabs %}


# Sending SMS

## Sending SMS

<mark style="color:green;">`POST`</mark> `https://direct.revicom.ltd/api/v1/message`

The method allows for sending an array of single messages **(1 to 1,000)**

#### Headers

| Name                                            | Type   | Description        |
| ----------------------------------------------- | ------ | ------------------ |
| Authorization<mark style="color:red;">\*</mark> | string | `Basic {TOKEN_1}`  |
| Content-Type<mark style="color:red;">\*</mark>  | string | `application/json` |

#### Request Body

| Name                                          | Type    | Description                                                                                                                                                                                                                                                                                        |
| --------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| channelType<mark style="color:red;">\*</mark> | string  | Sending channel (`SMS`)                                                                                                                                                                                                                                                                            |
| senderName<mark style="color:red;">\*</mark>  | string  | Sender ID. SMS-names with the status “Approved” are allowed, with the start date not later than the request time                                                                                                                                                                                   |
| destination<mark style="color:red;">\*</mark> | string  | Subscriber number                                                                                                                                                                                                                                                                                  |
| content<mark style="color:red;">\*</mark>     | string  | Message text; UTF-8 encoded string without Byte Order Mark                                                                                                                                                                                                                                         |
| tags                                          | array   | Message tags (array of strings). Each tag must match the expression `^\w+$` (any case letters, numbers and underscore "\_" are allowed)                                                                                                                                                            |
| useLocalTime                                  | boolean | <p>Flag responsible for the time zone in which the message will be sent:<br><strong><code>true</code></strong> – sending in the subscriber time zone<br><strong><code>false</code></strong> – sending by Moscow time<br><em>By default, true</em></p>                                              |
| localSendTime                                 | string  | <p>Low bound for the allowed time to send a message (subject to <code>useLocalTime</code>)<br>Date in the format '<code>YYYY-MM-DD hh:mm:ss</code>' in the range from (current UTC time – 12 hours) to (current UTC time + 7 days)<br><em>By default the message will be sent immediately</em></p> |
| localCompletionTime                           | string  | Upper bound for the allowed time to send a message (subject to `useLocalTime`) in the range from `localSendTime` to (current UTC time + 70 days)                                                                                                                                                   |
| ttl                                           | integer | <p>Message lifetime in seconds. After the ttl expires, the final status is set to the message<br><code>60 ≤ ttl ≤ 86400</code></p>                                                                                                                                                                 |
| hours                                         | array   | Valid sending hours (array of numbers). Integers from 0 to 23 can be transmitted in the array, each corresponding to the hour interval allowed for sending, subject to `useLocalTime;` the values must be unique.                                                                                  |
| days                                          | array   | Valid sending days (array of numbers). Integers from 1 (Mon) to 7 (Sun) can be transmitted in the array, each corresponding to the week day allowed for sending; the values must be unique.                                                                                                        |
| shortUrl                                      | boolean | <p>Flag responsible for shortening links in the message:<br><code>true</code>- links in the text of the message will be shortened<br>By default, <code>false</code></p>                                                                                                                            |
| callbackUrl                                   | string  | Address to send callback                                                                                                                                                                                                                                                                           |
| callbackEvents                                | array   | Events to send callback (an array of strings). If there is `callbackUrl` and no `callbackEvents` in the request, a callback will be sent on the event `delivered`                                                                                                                                  |

{% tabs %}
{% tab title="200" %}
If the request is successful, a response is returned that lists the message IDs and result codes. With errors = false, all submitted messages are guaranteed to have been successfully generated.

```
{
  "errors": false,
  "items": [
    {
      "messageUuid": "063474ec-a34f-4558-90c5-984395000004",
      "code": 201
    },
    {
      "messageUuid": "063564ec-a34f-4558-90c5-984395000005",
      "code": 201
    }
  ]
}
```

{% endtab %}

{% tab title="401" %}
Invalid token used/authorization header missing.

{% tabs %}
{% tab title="4012" %}

```
{
    "error": {
        "code": 4012,
        "msg": "Bad credentials"
    }
}
```

{% endtab %}

{% tab title="4010" %}

```
{
    "error": {
        "code": 4010,
        "msg": "Not Authenticated"
    }
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="403" %}
Token of wrong type used.

```
{
    "error": {
        "code": 4030,
        "msg": "Access Denied"
    }
}
```

{% endtab %}

{% tab title="422" %}
The request body contains invalid parameters or the maximum number of objects is exceeded.

```
{
    "error": {
        "code": 4220,
        "msg": "Max count of messages is 1000"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Local send time is less than minimal {minLocalSendTime}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Local send time is greater than minimal {maxLocalSendTime}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Local completion time is less than minimal {minLocalCompletionTime}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Local completion time is greater than maximal {maxLocalCompletionTime}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "No active sender name: ({channelType}, {senderName})"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Invalid msisdn"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Blank content"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Invalid tags: {tags}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Invalid TTL {ttl}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4222,
        "msg": "Invalid hours: {hours}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4223,
        "msg": "Invalid days: {days}"
    }
}
```

{% endtab %}

{% tab title="503 " %}

```
{
    "error": {
        "code": 5030,
        "msg": "Url shortener is unavailable"
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Recommended minimum timeout: 70 seconds
{% endhint %}

{% hint style="warning" %}
It is allowed to use as a sender name when sending SMS messages the names in the “Approved” status with a validity start date no later than the current one.

For creating sender ID, please contact your manager.
{% endhint %}

{% hint style="warning" %}
To set up custom domain for the link shortening functionality, please contact customer support
{% endhint %}

Enumerations:

| Parameter      | Allowed values                                       |
| -------------- | ---------------------------------------------------- |
| callbackEvents | [Callback Events](/extra/references#callback-events) |

## **Request example** <a href="#example" id="example"></a>

{% tabs %}
{% tab title="JSON" %}

```
POST https://direct.revicom.ltd/api/v1/message
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
[
  {
    "channelType": "SMS",
    "senderName": "SENDER",
    "destination": "14085553911",
    "content": "Message Text",
    "localSendTime": "2020-01-01 18:00:00",
    "localCompletionTime": "2020-01-02 18:00:00",
    "useLocalTime": true,
    "ttl": 43200,
    "hours": [
      12,
      13,
      14
    ],
    "days": [
      1,
      2
    ],
    "shortUrl": true,
    "callbackUrl": "https://company.com/callback",
    "callbackEvents": [
      "sent",
      "delivered",
      "click"
    ],
    "tags": [
      "tag1",
      "tag2"
    ]
  }
]
```

{% endtab %}

{% tab title="cURL" %}

```
curl -X POST 'https://direct.revicom.ltd/api/v1/message' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
-d '[{"channelType":"SMS","senderName":"SENDER","destination":"14085553911","content":"Message Text https://domain.com","localSendTime":"2020-01-01 18:00:00","localCompletionTime":"2020-01-02 18:00:00","useLocalTime":true,"ttl":43200,"hours":[12,13,14],"days":[1,2],"callbackUrl":"https://company.com/callback","callbackEvents":["sent","delivered"],"tags":["tag1","tag2"]}]'
```

{% endtab %}
{% endtabs %}


# Sending FLASHCALL

## Sending FLASHCALL messages

<mark style="color:green;">`POST`</mark> `https://direct.revicom.ltd/api/v1/message`

The method allows for sending an array of single messages **(1 to 1,000)**

#### Headers

| Name                                            | Type   | Description        |
| ----------------------------------------------- | ------ | ------------------ |
| Authorization<mark style="color:red;">\*</mark> | string | `Basic {TOKEN_1}`  |
| Content-Type<mark style="color:red;">\*</mark>  | string | `application/json` |

#### Request Body

| Name                                          | Type   | Description                                                                                                                                                        |
| --------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| channelType<mark style="color:red;">\*</mark> | string | Sending channel (`FLASHCALL`)                                                                                                                                      |
| senderName<mark style="color:red;">\*</mark>  | string | Sender name. Any string is allowed. The call will come from a number, the last digits being the sent code.                                                         |
| destination<mark style="color:red;">\*</mark> | string | Subscriber number                                                                                                                                                  |
| content<mark style="color:red;">\*</mark>     | string | Numerical code, 4 symbols                                                                                                                                          |
| tags                                          | array  | Message tags (array of strings). Each tag must match the expression `^\w+$` (any case letters, numbers and underscore "\_" are allowed)                            |
| callbackUrl                                   | string | Address to send callback                                                                                                                                           |
| callbackEvents                                | array  | Events to send callback (an array of strings). If there is `callbackUrl` and no `callbackEvents` in the request, a callback will be sent on the event `delivered`. |

{% tabs %}
{% tab title="200" %}
If the request is successful, a response is returned that lists the message IDs and result codes. With errors = false, all submitted messages are guaranteed to have been successfully generated.

```
{
  "errors": false,
  "items": [
    {
      "messageUuid": "063474ec-a34f-4558-90c5-984395000004",
      "code": 201
    },
    {
      "messageUuid": "063564ec-a34f-4558-90c5-984395000005",
      "code": 201
    }
  ]
}
```

{% endtab %}

{% tab title="401" %}
Invalid token used.

{% tabs %}
{% tab title="4012" %}

```
{
    "error": {
        "code": 4012,
        "msg": "Bad credentials"
    }
}
```

{% endtab %}

{% tab title="4010" %}

```
{
    "error": {
        "code": 4010,
        "msg": "Not Authenticated"
    }
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="403" %}
Token of wrong type used.

```
{
    "error": {
        "code": 4030,
        "msg": "Access Denied"
    }
}
```

{% endtab %}

{% tab title="422" %}
The request body contains invalid parameters; below are some response examples.

```
{
    "error": {
        "code": 4220,
        "msg": "Invalid content"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Invalid msisdn"
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
If you need to use codes consisting of more than four digits, please contact customer support.
{% endhint %}

{% hint style="warning" %}
Recommended minimum timeout: 70 seconds
{% endhint %}

Enumerations:

| Parameter      | Allowed values                                       |
| -------------- | ---------------------------------------------------- |
| callbackEvents | [Callback Events](/extra/references#callback-events) |

## Request example <a href="#example" id="example"></a>

{% tabs %}
{% tab title="JSON" %}

```
POST https://direct.revicom.ltd/api/v1/message
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
[
  {
    "channelType": "FLASHCALL",
    "senderName": "any sender",
    "destination": "14085553911",
    "content": "1234",
    "callbackUrl": "https://company.com/callback",
    "callbackEvents": [
      "sent",
      "delivered"
    ],
    "tags": [
      "tag1",
      "tag2"
    ]
  }
]
```

{% endtab %}

{% tab title="cURL" %}

```
curl -X POST 'https://direct.revicom.ltd/api/v1/message' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
-d '[{"channelType":"FLASHCALL","senderName":"any sender","destination":"14085553911","content":"1234","callbackUrl":"https://company.com/callback","callbackEvents":["sent","delivered"],"tags":["tag1","tag2"]}]'
```

{% endtab %}
{% endtabs %}

## Sending FLASHCALL conversion

<mark style="color:green;">`POST`</mark> `https://direct.i-dgtl.ru/api/v1/flashcall-conversion`

The method is used to report the correctness of the user-entered code sent in a FLASHCALL message

#### Headers

| Name                                            | Type   | Description        |
| ----------------------------------------------- | ------ | ------------------ |
| Authorization<mark style="color:red;">\*</mark> | string | `Bearer {TOKEN_1}` |
| Content-Type<mark style="color:red;">\*</mark>  | string | `application/json` |

#### Request Body

| Name                                          | Type   | Description                                                                                                         |
| --------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| messageUuid<mark style="color:red;">\*</mark> | string | FLASHCALL message uuid                                                                                              |
| result<mark style="color:red;">\*</mark>      | string | <p>Code entry result<br>Code approved: <code>NUMBER\_VERIFIERD</code><br>Invalid code: <code>WRONG\_CODE</code></p> |
| code                                          | string | Code                                                                                                                |

{% tabs %}
{% tab title="200 This corresponds to the response to sending single messages" %}

```
{
  "errors": false,
  "items": [
    {
      "messageUuid": "063474ec-a34f-4558-90c5-984395000004",
      "code": 201
    },
    {
      "messageUuid": "063564ec-a34f-4558-90c5-984395000005",
      "code": 201
    }
  ]
}
```

{% endtab %}
{% endtabs %}

Enumerations:

| Parameter | Allowed values              |
| --------- | --------------------------- |
| result    | FLASHCALL conversion result |

{% hint style="info" %}
Sending the conversion assists in improvement of the quality of sending FLASHCALL-messages
{% endhint %}

## Request example <a href="#conversion-example" id="conversion-example"></a>

{% tabs %}
{% tab title="JSON" %}

```
POST https://direct.i-dgtl.ru/api/v1/flashcall-conversion
Authorization: Bearer QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
[
  {
    "messageUuid": "063464ec-a34f-4558-90c5-984395000004",
    "result": "NUMBER_VERIFIED",
    "code": "7777"
  }
]
```

{% endtab %}

{% tab title="cURL" %}

```
curl -X POST 'https://direct.i-dgtl.ru/api/v1/flashcall-conversion' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
-d '[{"messageUuid":"063464ec-a34f-4558-90c5-984395000004","result":"NUMBER_VERIFIED","code":"7777"}]'
```

{% endtab %}
{% endtabs %}


# Sending VOICECODE

## Sending VOICECODE messages

<mark style="color:green;">`POST`</mark> `https://direct.revicom.ltd/api/v1/message`

The method allows sending an array of single messages **(1 to 1,000)**

#### Headers

| Name                                            | Type   | Description        |
| ----------------------------------------------- | ------ | ------------------ |
| Authorization<mark style="color:red;">\*</mark> | string | `Basic {TOKEN_1}`  |
| Content-Type<mark style="color:red;">\*</mark>  | string | `application/json` |

#### Request Body

| Name                                                  | Type    | Description                                                                                                                                                                                                                       |
| ----------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| channelType<mark style="color:red;">\*</mark>         | string  | Sending channel (always `VOICECODE`)                                                                                                                                                                                              |
| senderName<mark style="color:red;">\*</mark>          | string  | Sender name (always `voicecode`)                                                                                                                                                                                                  |
| destination<mark style="color:red;">\*</mark>         | string  | Subscriber number                                                                                                                                                                                                                 |
| content<mark style="color:red;">\*</mark>             | string  | Object with a message content                                                                                                                                                                                                     |
| tags                                                  | array   | Message tags (array of strings). Each tag must match the expression `^\w+$` (any case letters, numbers and underscore "\_" are allowed)                                                                                           |
| callbackUrl                                           | string  | Address (URL) to send callback                                                                                                                                                                                                    |
| callbackEvents                                        | array   | <p>Events to send callback (an array of strings). </p><p>If <code>callbackUrl</code> value is set and <code>callbackEvents</code> value is not set in the request, callback will be sent on the <code>delivered</code> event.</p> |
| content.contentType<mark style="color:red;">\*</mark> | string  | Content type (always `text`)                                                                                                                                                                                                      |
| content.text<mark style="color:red;">\*</mark>        | string  | The text of the message that will be read to the subscriber. Must match the template (described below). From 1 to 1000 characters                                                                                                 |
| ttl                                                   | integer | Message lifetime in seconds. After the ttl expires, the final status is assigned to the message. `30`**`≤`**`ttl`**`≤`**`86400`                                                                                                   |
| externalMessageId                                     | string  | Internal message id in your system (up to 100 symbols)                                                                                                                                                                            |

{% tabs %}
{% tab title="200" %}
If the request is successful, a response is returned that lists the message IDs and result codes. With errors = false, all submitted messages are guaranteed to have been successfully generated.

```
{
  "errors": false,
  "items": [
    {
      "messageUuid": "063474ec-a34f-4558-90c5-984395000004",
      "code": 201
    },
    {
      "messageUuid": "063564ec-a34f-4558-90c5-984395000005",
      "code": 201
    }
  ]
}
```

{% endtab %}

{% tab title="401" %}
Invalid token used.

{% tabs %}
{% tab title="4012" %}

```
{
    "error": {
        "code": 4012,
        "msg": "Bad credentials"
    }
}
```

{% endtab %}

{% tab title="4010" %}

```
{
    "error": {
        "code": 4010,
        "msg": "Not Authenticated"
    }
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="403" %}
Token of wrong type used.

```
{
    "error": {
        "code": 4030,
        "msg": "Access Denied"
    }
}
```

{% endtab %}

{% tab title="422" %}
The request body contains invalid parameters; below are some response examples.

```
{
    "error": {
        "code": 4220,
        "msg": "Invalid content"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Invalid msisdn"
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Recommended timeout: 70 seconds.

Usually, response to request returns in no more than a few seconds. However, timeout of 70 seconds guarantees that response will be received, including in situations of increased load.
{% endhint %}

{% hint style="info" %}
A message text must match the following template:\
`Код авторизации от {brand}: {code}.`You can send a code with space ( 1 2 3 4), without space (1234), or separated with a special character (1-2-3-4). It does not affect the quality of the voice over of the code.\
\
If you want to send messages using a different template, contact your manager.
{% endhint %}

Enumerations:

| Parameter      | Allowed values                                       |
| -------------- | ---------------------------------------------------- |
| callbackEvents | [Callback Events](/extra/references#callback-events) |

## Request example <a href="#example" id="example"></a>

{% tabs %}
{% tab title="JSON" %}

```
POST https://direct.revicom.ltd/api/v1/message
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
[
  {
    "channelType": "VOICECODE",
    "senderName": "voicecode",
    "destination": "14085553911",
    "content": {
        "contentType": "text",
        "text": "Код авторизации от revicom: 3 4 5 6"
    },
    "callbackUrl": "https://company.com/callback",
    "callbackEvents": [
      "sent",
      "delivered"
    ],
    "tags": [
      "tag1",
      "tag2"
    ]
  }
]
```

{% endtab %}

{% tab title="cURL" %}

```
curl -X POST 'https://direct.revicom.ltd/api/v1/message' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
-d '[{"channelType":"VOICECODE","senderName":"voicecode","destination":"14085553911","content":{"contentType": "text","text": "Код авторизации от revicom: 3 4 5 6"},"callbackUrl":"https://company.com/callback","callbackEvents":["sent","delivered"],"tags":["tag1","tag2"]}]'
```

{% endtab %}
{% endtabs %}


# Sending WHATSAPP

{% hint style="warning" %}
To have an opportunity to send WHATSAPP messages, please contact your manager.
{% endhint %}

{% hint style="info" %}
Messages are sent in chat mode:

* if the chat is initiated by a client, the first message must match the registered template. Each time the subscriber replies, a 24-hour window will open to send messages with arbitrary content. If the subscriber does not reply, the client can send messages to the user outside the 24-hour window using pre-registered message templates;
* if the chat is initiated by the subscriber, during the 24-hour window the client can send messages with arbitrary content.
  {% endhint %}

## Sending WHATSAPP

<mark style="color:green;">`POST`</mark> `https://direct.revicom.ltd/api/v1/message`

The method allows for sending an array of single messages **(1 to 1,000)**

#### Headers

| Name                                            | Type   | Description        |
| ----------------------------------------------- | ------ | ------------------ |
| Authorization<mark style="color:red;">\*</mark> | string | `Basic {TOKEN_1}`  |
| Content-Type<mark style="color:red;">\*</mark>  | string | `application/json` |

#### Request Body

| Name                                          | Type    | Description                                                                                                                                                                                                                                                                                        |
| --------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| channelType<mark style="color:red;">\*</mark> | string  | Sending channel (`SMS`)                                                                                                                                                                                                                                                                            |
| senderName<mark style="color:red;">\*</mark>  | string  | Sender name. WHATSAPP-names with the status “Approved” are allowed, with the start date not later than the request time                                                                                                                                                                            |
| destination<mark style="color:red;">\*</mark> | string  | Subscriber number                                                                                                                                                                                                                                                                                  |
| content<mark style="color:red;">\*</mark>     | object  | Message content. Below are the possible contents                                                                                                                                                                                                                                                   |
| tags                                          | array   | Message tags (array of strings). Each tag must match the expression `^\w+$` (any case letters, numbers and underscore "\_" are allowed)                                                                                                                                                            |
| useLocalTime                                  | boolean | <p>Flag responsible for the time zone in which the message will be sent:<br><strong><code>true</code></strong> – sending in the subscriber time zone<br><strong><code>false</code></strong> – sending by Moscow time<br><em>By default, true</em></p>                                              |
| localSendTime                                 | string  | <p>Low bound for the allowed time to send a message (subject to <code>useLocalTime</code>)<br>Date in the format '<code>YYYY-MM-DD hh:mm:ss</code>' in the range from (current UTC time – 12 hours) to (current UTC time + 7 days)<br><em>By default the message will be sent immediately</em></p> |
| localCompletionTime                           | string  | Upper bound for the allowed time to send a message (subject to `useLocalTime`) in the range from `localSendTime` to (current UTC time + 70 days)                                                                                                                                                   |
| ttl                                           | integer | <p>Message lifetime in seconds. After the ttl expires, the final status is set to the message<br><code>60 ≤ ttl ≤ 86400</code></p>                                                                                                                                                                 |
| hours                                         | array   | Valid sending hours (array of numbers). Integers from 0 to 23 can be transmitted in the array, each corresponding to the hour interval allowed for sending, subject to `useLocalTime;` the values must be unique.                                                                                  |
| days                                          | array   | Valid sending days (array of numbers). Integers from 1 (Mon) to 7 (Sun) can be transmitted in the array, each corresponding to the week day allowed for sending; the values must be unique.                                                                                                        |
| shortUrl                                      | boolean | <p>Flag responsible for shortening links in the message:<br><code>true</code>- links in the text of the message will be shortened<br>By default, <code>false</code></p>                                                                                                                            |
| callbackUrl                                   | string  | Address to send callback                                                                                                                                                                                                                                                                           |
| callbackEvents                                | array   | Events to send callback (an array of strings). If there is `callbackUrl` and no `callbackEvents` in the request, a callback will be sent on the event `delivered`                                                                                                                                  |

{% tabs %}
{% tab title="200" %}
If the request is successful, a response is returned that lists the message IDs and result codes. With errors = false, all submitted messages are guaranteed to have been successfully generated.

```
{
  "errors": false,
  "items": [
    {
      "messageUuid": "063474ec-a34f-4558-90c5-984395000004",
      "code": 201
    },
    {
      "messageUuid": "063564ec-a34f-4558-90c5-984395000005",
      "code": 201
    }
  ]
}
```

{% endtab %}

{% tab title="401" %}
Invalid token used/authorization header missing.

{% tabs %}
{% tab title="4012" %}

```
{
    "error": {
        "code": 4012,
        "msg": "Bad credentials"
    }
}
```

{% endtab %}

{% tab title="4010" %}

```
{
    "error": {
        "code": 4010,
        "msg": "Not Authenticated"
    }
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="403" %}
Token of wrong type used.

```
{
    "error": {
        "code": 4030,
        "msg": "Access Denied"
    }
}
```

{% endtab %}

{% tab title="422" %}
The request body contains invalid parameters or the maximum number of objects is exceeded.

```
{
    "error": {
        "code": 4220,
        "msg": "Max count of messages is 1000"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Local send time is less than minimal {minLocalSendTime}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Local send time is greater than minimal {maxLocalSendTime}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Local completion time is less than minimal {minLocalCompletionTime}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Local completion time is greater than maximal {maxLocalCompletionTime}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "No active sender name: ({channelType}, {senderName})"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Invalid msisdn"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Blank content"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Invalid tags: {tags}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Invalid TTL {ttl}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4222,
        "msg": "Invalid hours: {hours}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4223,
        "msg": "Invalid days: {days}"
    }
}
```

{% endtab %}

{% tab title="503 " %}

```
{
    "error": {
        "code": 5030,
        "msg": "Url shortener is unavailable"
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Recommended minimum timeout: 70 seconds
{% endhint %}

{% hint style="warning" %}
To set up custom domain for the link shortening functionality, please contact customer support
{% endhint %}

Enumerations:

| Parameter      | Allowed values                                       |
| -------------- | ---------------------------------------------------- |
| callbackEvents | [Callback Events](/extra/references#callback-events) |

## Text message

In addition to text, a WHATSAPP text message may contain a header, footer, and buttons. To send a text WHATSAPP message, use the following object `content`:

```
{
  "contentType": "text",
  "text": "whatsapp message text",
  "header": {
    "text": "message header"
  },
  "footer": {
    "text": "message footer"
  },
  "buttons": [
    {
      "text": "button text 1",
      "url": "https://revicom.ltd"
    },
    {
      "text": "button text 2",
      "phone": "14085553911"
    }
  ]
}
```

| Parameter           | Type                                        | Description                                                                                                                            |
| ------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| contentType         | <p>string</p><p><em>required</em></p>       | Content type (`text`)                                                                                                                  |
| text                | <p>string</p><p><em>required</em></p>       | <p>Message text; UTF-8 encoded string without Byte Order Mark</p><p>1 to 1,000 characters</p>                                          |
| header              | <p>object<br><em>optional</em></p>          | Message header                                                                                                                         |
| header.text         | <p>string<br><em>optonal</em></p>           | <p>Header text<br>Any string 1 to 60 characters</p>                                                                                    |
| header.documentUrl  | <p>string<br><em>optional</em></p>          | Link to the document for the header                                                                                                    |
| header.documentName | <p>string<br><em>optio</em>n<em>al</em></p> | Title of the document for the header; may only be present if documentUrl                                                               |
| header.imageUrl     | <p>string<br><em>optional</em></p>          | Link to the image for the header                                                                                                       |
| footer              | <p>object<br><em>optional</em></p>          | Message footer                                                                                                                         |
| footer.text         | <p>string<br><em>optional</em></p>          | <p>Footer text<br>Any string 1 to 60 characters</p>                                                                                    |
| buttons             | <p>array (objects)<br><em>optional</em></p> | Array with button objects                                                                                                              |
| buttons.text        | <p>string<br><em>optonal</em></p>           | <p>Button text<br>Any string 1 to 20 characters</p>                                                                                    |
| buttons.url         | <p>string<br><em>optional</em></p>          | <p>The link to which the button is clicked</p><p>Any string 1 to 1,000 characters  </p><p>Must begin with <code>http</code></p>        |
| buttons.phone       | <p>string<br><em>optional</em></p>          | <p>Phone number to which you are prompted to make a call when you press the button         </p><p>Any string 1 to 1,000 characters</p> |
| buttons.payload     | <p>string<br><em>optional</em></p>          | <p>Hidden text that will be sent in the incoming message if the user clicks on the button</p><p>Any string 1 to 1,000 mcharacters</p>  |

### Message header

• in the `header` object, only one of the following can be used:

* `text`
* `documentUrl` и `documentName`
* `imageUrl`

### Message buttons

* in the buttons array, 1 to 3 objects are allowed
* any object must have text
* there are two types of the buttons:
  * link button: contains text and url or text and phone
  * text button: contains text and payloa
  * :exclamation: Transmission of payload alongside with url or phone is not allowed
* one message may transmit one-type buttons only
* one message may have only one button with parameter `url`
* one message may have only one button with parameter `phone`
* when transmitting buttons with text, no more than three objects in the array are allowed
* when passing buttons with a link, no more than two objects in the array are allowed
* buttons in the message do not affect a header or footer

### Objects examples <a href="#object_examples" id="object_examples"></a>

{% tabs %}
{% tab title="Text" %}

```
{
  "contentType": "text",
  "text": "message text"
}
```

{% endtab %}

{% tab title="With header" %}

```
{
  "contentType": "text",
  "text": "message text",
  "header": {
    "documentUrl": "https://example.com/document.pdf",
    "documentName": "document.pdf"
  }
}
```

{% endtab %}

{% tab title="With header and footer" %}

```
{
  "contentType": "text",
  "text": "message text",
  "header": {
    "imageUrl": "https://example.com/image.png"
  },
  "footer": {
  "text": "message footer"
  }
}
```

{% endtab %}

{% tab title="With text buttons" %}

```
{
  "contentType": "text",
  "text": "message text",
  "buttons": [
    {
      "text": "button text 1",
      "payload": "id=1"
    },
    {
      "text": "button text 2",
      "payload": "id=2"
    }
  ]
}
```

{% endtab %}

{% tab title="With link buttons" %}

```
{
  "contentType": "text",
  "text": "message text",
  "buttons": [
    {
      "text": "button text 1",
      "url": "https://i-dgtl.ru/"
    },
    {
      "text": "button text 2",
      "phone": "78124269988"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Message with image

To send WHATSAPP message with an image attached, use the following object `content`:

```
{
  "contentType": "image",
  "imageUrl": "https://image.png",
  "imageName": "Image",
  "header": {
    "text": "message header"
  },
  "footer": {
    "text": "message footer"
  },
  "buttons": [
    {
      "text": "button text 1",
      "url": "https://i-dgtl.ru/"
    },
    {
      "text": "button text 2",
      "phone": "14085553911"
    }
  ]
}
```

| Parameter   | Type                               | Description            |
| ----------- | ---------------------------------- | ---------------------- |
| contentType | <p>string<br><em>required</em></p> | Content Type (`image`) |
| imageUrl    | <p>string<br><em>required</em></p> | Link to the image      |
| imageName   | <p>string<br><em>required</em></p> | Image name             |

{% hint style="info" %}
Header, footer and buttons are validated according to the same rules as for a text message
{% endhint %}

## Message with document

To send WHATSAPP message with an image attached, use the following object `content`:

```
{
  "contentType": "document",
  "documentUrl": "https://document.pdf",
  "documentName": "Document",
  "header": {
    "text": "header text"
  },
  "footer": {
    "text": "footer text"
  },
  "buttons": [
    {
      "text": "button text 1",
      "url": "https://revicom.ltd"
    },
    {
      "text": "button text 2",
      "phone": "78124269988"
    }
  ]
}
```

| Parameter    | Type                               | Description               |
| ------------ | ---------------------------------- | ------------------------- |
| contentType  | <p>string<br><em>required</em></p> | Content Type (`document`) |
| documentUrl  | <p>string<br><em>required</em></p> | Link to the document      |
| documentName | <p>string<br><em>required</em></p> | Name of the document      |

{% hint style="info" %}
Header, footer and buttons are validated according to the same rules as for a text message
{% endhint %}

## **Request example** <a href="#example" id="example"></a>

{% tabs %}
{% tab title="JSON" %}

```
POST https://direct.revicom.ltd/api/v1/message
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
[
  {
    "senderName": "SENDER",
    "channelType": "WHATSAPP",
    "content": {
      "contentType": "text",
      "text": "Message text",
      "header": {
        "imageUrl": "https://example.com/image.png"
      },
      "footer": {
        "text": "Message footer"
      },
      "buttons": [
        {
          "text": "button text 1",
          "url": "https://revicom.ltd"
        },
        {
          "text": "button text 2",
          "phone": "14085553912"
        }
      ]
    },
    "destination": "14085553911",
    "localSendTime": "2022-06-15 18:00:00",
    "localCompletionTime": "2022-06-16 21:00:00",
    "shortUrl": true,
    "callbackUrl": "https://company.com/callback",
    "callbackEvents": [
      "delivered",
      "read",
      "click"
    ],
    "useLocalTime": true,
    "ttl": 43200,
    "hours": [
      12,
      13,
      14,
      15,
      16,
      17,
      18,
      19
    ],
    "days": [
      1,
      2,
      3,
      4,
      5,
      6,
      7
    ],
    "tags": [
      "tag1",
      "tag2"
    ]
  }
]
```

{% endtab %}

{% tab title="cURL" %}

```
curl -X POST 'https://direct.revicom.ltd/api/v1/message' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
-d '[{"senderName":"SENDER","channelType":"VIBER","content":{"contentType":"text","text":"message text https://domain.com"},"destination":"7818242882","localSendTime":"2022-06-15 18:00:00","localCompletionTime":"2022-06-16 21:00:00","shortUrl":true,"callbackUrl":"https://company.com/callback","callbackEvents":["delivered","read","click"],"useLocalTime":true,"ttl":43200,"hours":[12,13,14,15,16,17,18,19],"days":[1,2,3,4,5,6,7],"tags":["tag1","tag2"]},{"senderName":"SENDER","channelType":"VIBER","destination":"7818242882","callbackUrl":"https://company.com/callback","callbackEvents":["delivered","read"],"content":{"contentType":"button","text":"message text","caption":"button text","action":"<button link>","imageUrl":"<image link>"},"localSendTime":"2022-06-15 18:00:00","localCompletionTime":"2022-06-16 21:00:00","useLocalTime":true,"ttl":43200,"hours":[12,13,14,15,16,17,18,19],"days":[1,2,3,4,5,6,7],"tags":["tag1","tag2"]},{"senderName":"SENDER","channelType":"VIBER","callbackUrl":"https://company.com/callback","callbackEvents":["delivered","read"],"destination":"7818242882","content":{"contentType":"image","imageUrl":"<image link>"},"localSendTime":"2022-06-15 18:00:00","localCompletionTime":"2022-06-16 21:00:00","useLocalTime":true,"ttl":43200,"hours":[12,13,14,15,16,17,18,19],"days":[1,2,3,4,5,6,7],"tags":["tag1","tag2"]}]'
```

{% endtab %}
{% endtabs %}


# Sending VK

## Sending VK

<mark style="color:green;">`POST`</mark> `https://direct.revicom.ltd/api/v1/message`

The method allows for sending an array of single messages **(1 to 1,000)**

#### Headers

| Name                                            | Type   | Description        |
| ----------------------------------------------- | ------ | ------------------ |
| Authorization<mark style="color:red;">\*</mark> | string | `Basic {TOKEN_1}`  |
| Content-Type<mark style="color:red;">\*</mark>  | string | `application/json` |

#### Request Body

| Name                                          | Type    | Description                                                                                                                                                                                                                                                                                        |
| --------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| channelType<mark style="color:red;">\*</mark> | string  | Sending channel (`VK`)                                                                                                                                                                                                                                                                             |
| senderName<mark style="color:red;">\*</mark>  | string  | Sender name. Any non-empty string is alliwed                                                                                                                                                                                                                                                       |
| destination<mark style="color:red;">\*</mark> | string  | Subscriber number                                                                                                                                                                                                                                                                                  |
| content<mark style="color:red;">\*</mark>     | string  | Message text; UTF-8 encoded string without Byte Order Mark. 1 to 2048 characters                                                                                                                                                                                                                   |
| tags                                          | array   | Message tags (array of strings). Each tag must match the expression `^\w+$` (any case letters, numbers and underscore "\_" are allowed)                                                                                                                                                            |
| useLocalTime                                  | boolean | <p>Flag responsible for the time zone in which the message will be sent:<br><strong><code>true</code></strong> – sending in the subscriber time zone<br><strong><code>false</code></strong> – sending by Moscow time<br><em>By default, true</em></p>                                              |
| localSendTime                                 | string  | <p>Low bound for the allowed time to send a message (subject to <code>useLocalTime</code>)<br>Date in the format '<code>YYYY-MM-DD hh:mm:ss</code>' in the range from (current UTC time – 12 hours) to (current UTC time + 7 days)<br><em>By default the message will be sent immediately</em></p> |
| localCompletionTime                           | string  | Upper bound for the allowed time to send a message (subject to `useLocalTime`) in the range from `localSendTime` to (current UTC time + 70 days)                                                                                                                                                   |
| ttl                                           | integer | <p>Message lifetime in seconds. After the ttl expires, the final status is set to the message<br><code>60 ≤ ttl ≤ 86400</code></p>                                                                                                                                                                 |
| hours                                         | array   | Valid sending hours (array of numbers). Integers from 0 to 23 can be transmitted in the array, each corresponding to the hour interval allowed for sending, subject to `useLocalTime;` the values must be unique.                                                                                  |
| days                                          | array   | Valid sending days (array of numbers). Integers from 1 (Mon) to 7 (Sun) can be transmitted in the array, each corresponding to the week day allowed for sending; the values must be unique.                                                                                                        |
| shortUrl                                      | boolean | <p>Flag responsible for shortening links in the message:<br><code>true</code>- links in the text of the message will be shortened<br>By default, <code>false</code></p>                                                                                                                            |
| callbackUrl                                   | string  | Address to send callback                                                                                                                                                                                                                                                                           |
| callbackEvents                                | array   | Events to send callback (an array of strings). If there is `callbackUrl` and no `callbackEvents` in the request, a callback will be sent on the event `delivered`                                                                                                                                  |

{% tabs %}
{% tab title="200" %}
If the request is successful, a response is returned that lists the message IDs and result codes. With errors = false, all submitted messages are guaranteed to have been successfully generated.

```
{
  "errors": false,
  "items": [
    {
      "messageUuid": "063474ec-a34f-4558-90c5-984395000004",
      "code": 201
    },
    {
      "messageUuid": "063564ec-a34f-4558-90c5-984395000005",
      "code": 201
    }
  ]
}
```

{% endtab %}

{% tab title="401" %}
Invalid token used/authorization header missing.

{% tabs %}
{% tab title="4012" %}

```
{
    "error": {
        "code": 4012,
        "msg": "Bad credentials"
    }
}
```

{% endtab %}

{% tab title="4010" %}

```
{
    "error": {
        "code": 4010,
        "msg": "Not Authenticated"
    }
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="403" %}
Token of wrong type used.

```
{
    "error": {
        "code": 4030,
        "msg": "Access Denied"
    }
}
```

{% endtab %}

{% tab title="422" %}
The request body contains invalid parameters or the maximum number of objects is exceeded.

```
{
    "error": {
        "code": 4220,
        "msg": "Max count of messages is 1000"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Local send time is less than minimal {minLocalSendTime}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Local send time is greater than minimal {maxLocalSendTime}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Local completion time is less than minimal {minLocalCompletionTime}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Local completion time is greater than maximal {maxLocalCompletionTime}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "No active sender name: ({channelType}, {senderName})"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Invalid msisdn"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Blank content"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Invalid tags: {tags}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Invalid TTL {ttl}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4222,
        "msg": "Invalid hours: {hours}"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4223,
        "msg": "Invalid days: {days}"
    }
}
```

{% endtab %}

{% tab title="503 " %}

```
{
    "error": {
        "code": 5030,
        "msg": "Url shortener is unavailable"
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Recommended minimum timeout: 70 seconds
{% endhint %}

{% hint style="warning" %}
To set up the link shortening functionality, you need to contact customer support
{% endhint %}

Enumerations:

| Parameter      | Allowed values                                       |
| -------------- | ---------------------------------------------------- |
| callbackEvents | [Callback Events](/extra/references#callback-events) |

## **Request example** <a href="#example" id="example"></a>

{% tabs %}
{% tab title="JSON" %}

```
POST https://direct.revicom.ltd/api/v1/message
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
[
  {
    "channelType": "VK",
    "senderName": "SENDER",
    "destination": "14085553911",
    "content": "message text https://domain.com",
    "localSendTime": "2022-01-01 18:00:00",
    "localCompletionTime": "2022-01-02 18:00:00",
    "useLocalTime": true,
    "shortUrl": true,
    "ttl": 43200,
    "hours": [
      12,
      13,
      14,
      15,
      16,
      17,
      18,
      19
    ],
    "days": [
      1,
      2,
      3,
      4,
      5,
      6,
      7
    ],
    "callbackUrl": "https://company.com/callback",
    "callbackEvents": [
      "delivered",
      "read"
    ],
    "tags": [
      "tag1",
      "tag2"
    ]
  }
]
```

{% endtab %}

{% tab title="cURL" %}

```
curl -X POST 'https://direct.revicom.ltd/api/v1/message' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
-d '[{"channelType":"VK","senderName":"SENDER","destination":"79818268484","content":"message text https://domain.com","localSendTime":"2022-01-01 18:00:00","localCompletionTime":"2022-01-02 18:00:00","useLocalTime":true,"shortUrl":true,"ttl":43200,"hours":[12,13,14,15,16,17,18,19],"days":[1,2,3,4,5,6,7],"callbackUrl":"https://company.com/callback","callbackEvents":["delivered","read"],"tags":["tag1","tag2"]}]'
```

{% endtab %}
{% endtabs %}


# Receiving Callback

{% hint style="info" %}
The callbackUrl value must comply with RFC 3986, which specifically allows:

* use of both https and http secure zone
* transmission of a login:password pair for Basic authorization. Example:"callbackUrl": "<https://login:password@example.com/callback>"
* explicit transmission of ip-address and port. Example: "callbackUrl": "[http://12.34.567.89:8080/callback](https://api.direct.revicom.ltd/messages/http:/12.34.567.89:8080/callback)"
  {% endhint %}

## Outbound Messages Callback <a href="#outbound_callback" id="outbound_callback"></a>

If the `callbackUrl` parameter (and optionally `callbackEvents`) was transmitted in the message object when requesting to send POST /v1/message, then when one of the specified events (or the default event) occurs, a callback will be sent to the specified `callbackUrl`.

| Event     | Description                                                                                                                                                                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| delivered | <p>Getting one of the message statuses:</p><ul><li>delivered – the message was delivered</li><li>undelivered – the message was not delivered in lifetime (default 25 hours)</li><li>unsent – the message was not sent</li></ul><p>Is the default event, if there is a callbackUrl and no callbackEvents in the query.</p> |
| sent      | Getting the message status “sent”                                                                                                                                                                                                                                                                                         |
| read      | <p>Getting one of the message statuses:</p><ul><li>read – the message was read</li><li>unread – the message was not read in lifetime (default 25 hours)</li></ul>                                                                                                                                                         |
| price     | Changing the message price                                                                                                                                                                                                                                                                                                |
| click     | Clicking on a shortened link in the text of the message                                                                                                                                                                                                                                                                   |

### Message status change <a href="#status_callback" id="status_callback"></a>

When any of the `delivered`, `sent`, `read` events specified in the message sending request occurs, the following query will be sent to the specified `callbackUrl`:

```
POST {{callback_url}}
Content-Type: application/json
[
  {
    "message_uuid": "063464ec-a34f-4558-90c5-984395000003",
    "channel_type": "SMS",
    "cascade_message_uuid": "063464ec-a34f-4558-90c5-984395000002",
    "cascade_step": 2,
    "callback_event": "delivered",
    "status": "undelivered",
    "status_time": "2020-10-16T18:51:13Z",
    "error_code": 6969
  }
]
```

| Parameter              | Type                                   | Description                                                                                 |
| ---------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------- |
| message\_uuid          | <p>string</p><p><em>required</em></p>  | Message uuid                                                                                |
| channel\_type          | <p>string</p><p><em>required</em></p>  | [Message channel](/extra/references#channel-types)                                          |
| cascade\_message\_uuid | <p>string</p><p><em>optional</em></p>  | Identifier of the first message in the cascade. This is sent for cascading messages only    |
| cascade\_step          | <p>integer</p><p><em>optional</em></p> | The sequence number of the message in the cascade. This is sent for cascading messages only |
| callback\_event        | <p>string</p><p><em>required</em></p>  | [Callback event](/extra/references#callback-events)                                         |
| status                 | <p>string</p><p><em>required</em></p>  | [Message status](/extra/references#message-states)                                          |
| status\_time           | <p>string</p><p><em>required</em></p>  | Message status time                                                                         |
| error\_code            | <p>integer</p><p><em>optional</em></p> | [Error code](/extra/references/error-codes)                                                 |

### Message price change <a href="#price_callback" id="price_callback"></a>

When the price event occurs, if it was specified in the message sending request, the following query will be sent to the specified `callbackUrl`:

```
POST {{callback_url}}
Content-Type: application/json
[
  {
    "message_uuid": "063464ec-a34f-4558-90c5-984395000003",
    "channel_type": "SMS",
    "cascade_message_uuid": "063464ec-a34f-4558-90c5-984395000002",
    "cascade_step": 2,
    "callback_event": "price",
    "parts": 5,
    "price": 0.1,
    "currency": "EUR",
    "price_time": "2020-10-16T18:51:13Z"
  }
]
```

| Parameter              | Type                                   | Description                                                                                                           |
| ---------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| message\_uuid          | <p>string</p><p><em>required</em></p>  | Message uuid                                                                                                          |
| channel\_type          | <p>string</p><p><em>required</em></p>  | [Message channel](/extra/references#channel-types)                                                                    |
| cascade\_message\_uuid | <p>string</p><p><em>optional</em></p>  | Identifier of the first message in the cascade. This is sent for cascading messages only                              |
| cascade\_step          | <p>integer</p><p><em>optional</em></p> | The sequence number of the message in the cascade. This is sent for cascading messages only                           |
| callback\_event        | <p>string</p><p><em>required</em></p>  | Callback event. In this case: `price`                                                                                 |
| parts                  | <p>integer</p><p><em>required</em></p> | Number of parts in the message                                                                                        |
| price                  | <p>number</p><p><em>required</em></p>  | Price of the message                                                                                                  |
| currency               | <p>string</p><p><em>required</em></p>  | Price currency. Three-digit letter code according to [ISO 4217](https://www.iso.org/ru/iso-4217-currency-codes.html)​ |
| price\_time            | <p>string<br><em>required</em></p>     | Message price setting time                                                                                            |

### Click through <a href="#click_callback" id="click_callback"></a>

When the `click` event occurs, if it was specified in the request to send a message, the following query will be sent to the specified `callbackUrl`:

```
POST {{callback_url}}
Content-Type: application/json
[
  {
    "message_uuid": "063464ec-a34f-4558-90c5-984395000003",
    "callback_event": "click",
    "channel_type": "SMS",
    "cascade_message_uuid": "31d6f174-2ef6-4f25-b03b-c4c06e0e4df8",
    "cascade_step": 3,
    "url": "https://revicom.ltd",
    "short_url": "a.bc/61EwQ",
    "click_time": "2021-04-21T17:41:43Z"
  }
]
```

| Parameter              | Type                                   | Description                                                                                 |
| ---------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------- |
| message\_uuid          | <p>string</p><p><em>required</em></p>  | Message uuid                                                                                |
| channel\_type          | <p>string</p><p><em>required</em></p>  | [Message channel](/extra/references#channel-types)                                          |
| cascade\_message\_uuid | <p>string</p><p><em>optional</em></p>  | Identifier of the first message in the cascade. This is sent for cascading messages only    |
| cascade\_step          | <p>integer</p><p><em>optional</em></p> | The sequence number of the message in the cascade. This is sent for cascading messages only |
| callback\_event        | <p>string</p><p><em>required</em></p>  | Callback event. In this case: `click`                                                       |
| url                    | <p>string</p><p><em>required</em></p>  | Initial link                                                                                |
| short\_url             | <p>string</p><p><em>required</em></p>  | Shortened link​                                                                             |
| click\_time            | <p>string<br><em>required</em></p>     | Click time                                                                                  |

## Inbound Messages Callback <a href="#inbound_callback" id="inbound_callback"></a>

1. Contact your manager to enable the option to get inbounds (currently only possible for the WhatsApp channel)
2. Go to the PA page Settings / Inbounds
3. Click **Add** and fill out the form
4. In the field **Traffic Partitioning Center**, specify the traffic partitioning center to which incoming messages should be assigned
5. In the field **Callback URL,** specify the address to which the callback will be sent when an inbound is got

If **Include sender names** is specified, you can select the names for inbounds of which the selected **TPC** and **CallbackUrl** will be assigned (if you do not take into account names, then the assignment of **TPC** and **CallbackUrl** will be valid for all inbounds via the channel)

Inbounds for which no matching rule is found will be assigned to the default TPC (specified on the Settings/Traffic Partitioning Centers page).

### Receiving inbound message <a href="#inbound_sent_callback" id="inbound_sent_callback"></a>

When an inbound is got for which a suitable rule with `CallbackUrl` was found, the following query will be sent to the specified address:

```
POST {{callback_url}}
[
  {
    "message_uuid": "063464ec-9999-4558-90c5-984395000001",
    "callback_event": "inbound_sent",
    "channel_type": "WHATSAPP",
    "status": "inbound_sent",
    "status_time": "2021-11-15T18:38:07Z",
    "item": {
      "createdTime": "2021-12-06T16:31:22.892Z",
      "sentTime": "2021-11-15T18:38:07.000Z",
      "messageUuid": "063464ec-9999-4558-90c5-984395000001",
      "direction": "inbound",
      "channelType": "WHATSAPP",
      "trafficCenterId": 111,
      "senderName": "UNDELIV2",
      "destination": "14085553911",
      "content": "message text",
      "specialContent": {
        "text": "message text",
        "contentType": "text"
      },
      "totalParts": 1
    }
  }
]
```

| Parameter       | Type                               | Description                                                                                             |
| --------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------- |
| message\_uuid   | <p>string<br><em>required</em></p> | Message uuid                                                                                            |
| callback\_event | <p>string<br><em>required</em></p> | Callback event. In this case: `inbound_sent`                                                            |
| channel\_type   | <p>string<br><em>required</em></p> | [Message channel](/extra/references#channel-types)                                                      |
| status          | <p>string<br><em>required</em></p> | Message status. In this case: `inbound_sent`                                                            |
| status\_time    | <p>string<br><em>requied</em></p>  | Time of sending                                                                                         |
| item            | <p>object<br><em>required</em></p> | Message object in the form of the response object [GET /v1/message​](/messages/sms-sending#sending-sms) |

## Expected response <a href="#response" id="response"></a>

In response to a callback of any type, HTTP code **2\*\*** is expected. If there is no response within 24 hours, resending will be performed every 5 minutes.


# Getting Messages

## Getting array of messages

<mark style="color:blue;">`GET`</mark> `https://direct.revicom.ltd/api/v1/message`

This method allows for getting arrays of message objects that conform filtration parameters.

#### Query Parameters

| Name                   | Type    | Description                                                                                                                                                                        |
| ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| page                   | integer | Requested page: By default, 1                                                                                                                                                      |
| per\_page              | integer | Number of messages per page. By default, 100. The limitation: `page * perPage <= 10000` should be satisfied                                                                        |
| sort                   | string  | Sorting                                                                                                                                                                            |
| time\_from             | string  | Low bound of the time of sending in UTC (or receiving the final `unsent` status). Value example: `2020-01-01T00:00:00Z`                                                            |
| time\_to               | string  | Upper bound of the time of sending in UTC (or receiving the final `unsent` status).                                                                                                |
| dispatch\_id           | integer | <p>Dispatch ID<br><em>Multiple parameter</em></p>                                                                                                                                  |
| message\_uuid          | string  | <p>Message ID<br><em>Multiple parameter</em></p>                                                                                                                                   |
| destination            | string  | <p>Phone number<br><em>Multiple parameter</em></p>                                                                                                                                 |
| status                 | string  | <p>Status<br><em>Multiple parameter</em></p>                                                                                                                                       |
| traffic\_center\_id    | integer | <p>Traffic center ID<br><em>Multiple parameter</em></p>                                                                                                                            |
| tags                   | string  | <p>Message tag<br><em>Multiple parameter</em></p>                                                                                                                                  |
| sending\_method        | string  | <p>Sending method<br><em>Multiple parameter</em></p>                                                                                                                               |
| channel\_type          | string  | <p>Channel type<br><em>Multiple parameter</em></p>                                                                                                                                 |
| traffic\_type          | string  | <p>Traffic type<br><em>Multiple parameter</em></p>                                                                                                                                 |
| template\_id           | string  | <p>Template ID</p><p><em>Multiple parameter</em></p>                                                                                                                               |
| content                | string  | String contained in the message text                                                                                                                                               |
| content\_nor           | string  | String not contained in the message content                                                                                                                                        |
| sender\_name           | string  | <p>Sender name</p><p><em>Multiple parameter</em></p>                                                                                                                               |
| cascade\_message\_uuid | string  | Root cascade message ID                                                                                                                                                            |
| root                   | boolean | `true` – only non-cascade and cascade messages of the first step are returned; `false` – only cascade messages are returned starting from the second step;  By default, null       |
| ready\_to\_stop        | boolean | `true` – only ready to stop messages are returned (see Stopping messages)                                                                                                          |
| country\_code          | string  | Subscriber’s country two-letter code according to [ISO-3166](https://www.iso.org/iso-3166-country-codes.html)                                                                      |
| direction              | string  | <p>Message direction; by default, <code>outbound</code></p><p><em>Multiple parameter</em></p>                                                                                      |
| dispatch               | booean  | <p><code>true</code> – only dispatch messages are returned;</p><p><code>false</code> – only single messages are returned.</p><p><em>Applicable for outbound-messages only</em></p> |

#### Headers

| Name                                            | Type   | Description       |
| ----------------------------------------------- | ------ | ----------------- |
| Authorization<mark style="color:red;">\*</mark> | string | `Basic {TOKEN_1}` |

{% tabs %}
{% tab title="200 " %}

```
{
  "page": 1,
  "perPage": 1,
  "total": 100,
  "items": [
    {
      ... // message object
    }
  ]
}
```

{% endtab %}

{% tab title="401 Invalid token used/authorization header absent" %}
{% tabs %}
{% tab title="4012" %}

```
{
    "error": {
        "code": 4012,
        "msg": "Bad credentials"
    }
}
```

{% endtab %}

{% tab title="4010" %}

```
{
    "error": {
        "code": 4010,
        "msg": "Not Authenticated"
    }
}
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
This method allows for getting no more than 10,000 messages from one digest. That is, regardless of the total value in the response, paging is possible until the number of 10,000 messages is exceeded.
{% endhint %}

{% hint style="info" %}
To have the option to get inbounds, please, contact a manager.
{% endhint %}

Enumerations:

| Parameter       | Allowed Values                                        |
| --------------- | ----------------------------------------------------- |
| sort            | <ul><li>sentTime:asc</li><li>sentTime:desc</li></ul>  |
| status          | [Message statuses​](/extra/references#message-states) |
| sending\_method | [Sending methods](/extra/references#sending-methods)  |
| channel\_type   | [Channel types](/extra/references#channel-types)      |
| traffic\_type   | [Traffic types​](/extra/references#traffic-types)     |
| direction       | [Directions](/extra/references#directions)            |

## Response object description <a href="#response-object" id="response-object"></a>

| Parameter | Type    | Description                                                            |
| --------- | ------- | ---------------------------------------------------------------------- |
| page      | integer | Requested page number                                                  |
| perPage   | integer | Number of entries per page                                             |
| total     | integer | The total number of the entries found that matched the filter criteria |
| items     | array   | Message objects array (described below)                                |

## Request Example <a href="#example" id="example"></a>

This allows for getting dispatch messages 1 and 2 in the delivered and undelivered statuses, to which this status was assigned in the interval from 2020-11-01 21:00:00 UTC to 2020-11-02 21:00:00 UTC

{% tabs %}
{% tab title="JSON" %}

```
GET https://direct.revicom.ltd/api/v1/message?time_from=2020-11-01T21:00:00Z&time_to=2020-11-02T21:00:00Z&dispatch_id=1&dispatch_id=2&status=delivered&status=undelivered
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
```

{% endtab %}

{% tab title="cURL" %}

```
curl -X GET 'https://direct.revicom.ltd/api/v1/message?time_from=2020-11-01T21:00:00Z&time_to=2020-11-02T21:00:00Z&dispatch_id=1&dispatch_id=2&status=delivered&status=undelivered' \
-H 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
```

{% endtab %}
{% endtabs %}

## Getting message by uuid

<mark style="color:blue;">`GET`</mark> `https://direct.revicom.ltd/api/v1/message/{message_uuid}`

#### Path Parameters

| Name                                            | Type   | Description  |
| ----------------------------------------------- | ------ | ------------ |
| message\_uuid<mark style="color:red;">\*</mark> | string | Message uuid |

#### Headers

| Name                                            | Type   | Description       |
| ----------------------------------------------- | ------ | ----------------- |
| Authorization<mark style="color:red;">\*</mark> | string | `Basic {TOKEN_1}` |

{% tabs %}
{% tab title="200 " %}

```
{
  "createdTime": "2020-01-01T08:00:00Z",
  "channelType": "SMS",
  "sendingMethog": "UI",
  "trafficType": "SERVICE",
  "templateId": 120,
  "dispatchId": 123,
  "dispatchName": "dispatch 1",
  "messageUuid": "9d213ffc-c388-46f5-b42b-01d589d1a815",
  "trafficCenterId": 1,
  "senderName": "testSender",
  "destination": "14085553911",
  "content": "message text",
  "tags": [
    "tag1",
    "tag2"
  ],
  "ttl": 86400,
  "hours": [
    10,
    11,
    12
  ],
  "days": [
    5,
    6
  ],
  "localSendTime": "2021-02-02 15:00:00",
  "localCompletionTime": "2021-02-10 15:00:00",
  "useLocalTime": true,
  "callbackEvents": [
    "sent",
    "delivered"
  ],
  "callbackUrl": "https://url-for-callbacks",
  "totalParts": 1,
  "price": {
    "totalPrice": 2.5,
    "currency": "RUB",
    "invoicedParts": 1,
    "final": false
  },
  "sentTime": "2020-01-01T09:00:00Z",
  "statusTime": "2020-01-01T10:00:00Z",
  "status": "undelivered",
  "cascadeMessageUuid": "9d213ffc-c388-46f5-b42b-01d589d1a814",
  "cascadeStep": 1,
  "errorCode": 7060
}
```

{% endtab %}

{% tab title="401" %}
Invalid token used.

```
{
    "error": {
        "code": 4012,
        "msg": "Bad credentials"
    }
}
```

{% endtab %}

{% tab title="403" %}
Token of wrong type used.

```
{
    "error": {
        "code": 4030,
        "msg": "Access Denied"
    }
}
```

{% endtab %}
{% endtabs %}

## Message object description <a href="#message-object" id="message-object"></a>

| Parameter                  | Type            | Description                                                                                            |
| -------------------------- | --------------- | ------------------------------------------------------------------------------------------------------ |
| createdTime                | string          | Message creation time (UTC)                                                                            |
| channelType                | string          | [Channel type](/extra/references#channel-types)                                                        |
| sendingMethod              | string          | [Sending method](/extra/references#sending-methods)                                                    |
| trafficType                | string          | [Traffic type](/extra/references#traffic-types)                                                        |
| templateId                 | integer         | Template ID (possible for SERVICE and TRANSACT traffic type)                                           |
| dispatchId                 | integer         | Dispatch ID (-1 for single messages)                                                                   |
| dispatchName               | string          | Dispatch name (if exists)                                                                              |
| messageUuid                | string          | Message ID                                                                                             |
| trafficCenterId            | integer         | Traffic partitioning center ID                                                                         |
| senderName                 | string          | Sender name                                                                                            |
| destination                | string          | Subscriber's number                                                                                    |
| direction                  | string          | [Direction](/extra/references#directions)                                                              |
| brand                      | string          | Subscriber's mobile operator                                                                           |
| country                    | string          | Subscriber's country                                                                                   |
| region                     | string          | Subscriber's region                                                                                    |
| content                    | string          | Message text                                                                                           |
| tags                       | array           | Array of tags (if exists)                                                                              |
| ttl                        | integer         | Message ttl                                                                                            |
| hours                      | array (integer) | Allowed hours for sending                                                                              |
| days                       | array (integer) | Allowed days for sending                                                                               |
| localSendTime              | string          | Low bound of the sending time                                                                          |
| localCompletionTime        | string          | Upper bound of the sending time                                                                        |
| useLocalTime               | boolean         | Flag which shows if subscribers local time is used for localSendTime, localCompletionTime, hours, days |
| callbackEvents             | string          | [Callback Events](/extra/references#callback-events)                                                   |
| callbackUrl                | string          | Address to send callback                                                                               |
| totalParts                 | integer         | Number of parts in the message                                                                         |
| price.totalPrice           | number          | Message cost                                                                                           |
| price.currency             | string          | Message currency                                                                                       |
| price.invoicedParts        | integer         | Number of the rated parts                                                                              |
| price.final                | boolean         | Price is final (true) / preliminary (false)                                                            |
| sentTime                   | string          | Sending time (UTC)                                                                                     |
| status                     | string          | [Message status​](/extra/references#message-states)                                                    |
| statusTime                 | string          | Status time (UTC)                                                                                      |
| readStatus                 | string          | [Read status​](/extra/references#message-read-states)                                                  |
| readStatusTime             | string          | Read status time (UTC)                                                                                 |
| specialContent             | object          | Message content                                                                                        |
| specialContent.contentType | string          | Message content type​. For SMS only `text`                                                             |
| specialContent.text        | string          | Message text                                                                                           |
| errorCode                  | integer         | [Error code​](/extra/references/error-codes)                                                           |
| cascadeMessageUuid         | string          | Root cascade message ID                                                                                |
| cascadeStep                | integer         | Cascade step number                                                                                    |


# Stopping Messages

## Stopping messages by uuid

<mark style="color:green;">`POST`</mark> `https://direct.revicom.ltd/api/v1/message/stop`

The method allows for permanent cancelation of single messages with identifiers transmitted

#### Headers

| Name                                            | Type   | Description        |
| ----------------------------------------------- | ------ | ------------------ |
| Authorization<mark style="color:red;">\*</mark> | string | `Basic {TOKEN_1}`  |
| Content-Type<mark style="color:red;">\*</mark>  | string | `application/json` |

#### Request Body

| Name                                    | Type  | Description                                                      |
| --------------------------------------- | ----- | ---------------------------------------------------------------- |
| uuids<mark style="color:red;">\*</mark> | array | Array of message identifiers; at most 10,000 values are allowed. |

{% tabs %}
{% tab title="200" %}
If the request is correct, a response will list the message stopping statuses.

```
{
  "errors": true,
  "items": [
    {
      "messageUuid": "2a28d557-22a1-4be6-8908-1481723043dd",
      "code": 201
    },
    {
      "messageUuid": "811c27e3-3bc4-406a-9fcd-44435a8208da",
      "code": 403
    },
    {
      "messageUuid": "cc46e6b6-2d77-4457-aa81-c17a027721d3",
      "code": 404
    }
  ]
}
```

{% endtab %}

{% tab title="401" %}
Invalid token used/ authorization header missing.

{% tabs %}
{% tab title="4012" %}

```
{
    "error": {
        "code": 4012,
        "msg": "Bad credentials"
    }
}
```

{% endtab %}

{% tab title="4010" %}

```
{
    "error": {
        "code": 4010,
        "msg": "Not Authenticated"
    }
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="403" %}
Token of wrong type used.

```
{
    "error": {
        "code": 4030,
        "msg": "Access Denied"
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Changing the status of messages is asynchronous: it can take a few seconds between successful completion of the request and the status of messages being set to unsent.
{% endhint %}

{% hint style="info" %}

* This request can be performed for both single messages and dispatch messages
* When a root cascade message is successfully stopped, the entire cascade from that message will be stopped
  {% endhint %}

## **Response object description** <a href="#response-description" id="response-description"></a>

```
{
  "errors": true,
  "items": [
    {
      "messageUuid": "2a28d557-22a1-4be6-8908-1481723043dd",
      "code": 200
    },
    {
      "messageUuid": "063464ec-a34f-4558-90c5-984395000001",
      "code": 202
    },
    {
      "messageUuid": "811c27e3-3bc4-406a-9fcd-44435a8208da",
      "code": 403
    },
    {
      "messageUuid": "cc46e6b6-2d77-4457-aa81-c17a027721d3",
      "code": 404
    }
  ]
}
```

| Parameter         | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| errors            | boolean | Unsuccessful message stops (codes 403, 404 in the response)                                                                                                                                                                                                                                                                                                                                    |
| items             | array   | Array with message stop result objects                                                                                                                                                                                                                                                                                                                                                         |
| items.messageUuid | string  | Message ID                                                                                                                                                                                                                                                                                                                                                                                     |
| items.code        | integer | <p>Message stop result:</p><ul><li>200 — the message will be stopped for sure</li><li>202 — the message will be stopped <strong>not</strong> for sure, because it enters the stage of sending or generating a cascade message</li><li>403 — the message cannot be stopped because it is being sentor already sent</li><li>404 — the message was not stopped because it was not found</li></ul> |

## Request example <a href="#example" id="example"></a>

{% tabs %}
{% tab title="JSON" %}

```
POST https://direct.revicom.ltd/api/v1/message/stop
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
{
  "uuids": [
    "2a28d557-22a1-4be6-8908-1481723043dd",
    "811c27e3-3bc4-406a-9fcd-44435a8208da",
    "cc46e6b6-2d77-4457-aa81-c17a027721d3"
  ]
}
```

{% endtab %}

{% tab title="cURL" %}

```
curl -X POST 'https://direct.revicom.ltd/api/v1/message/stop' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
-d '{"uuids":["2a28d557-22a1-4be6-8908-1481723043dd","811c27e3-3bc4-406a-9fcd-44435a8208da","cc46e6b6-2d77-4457-aa81-c17a027721d3"]}'
```

{% endtab %}
{% endtabs %}


# Account Balance

## Getting the accont balance

<mark style="color:blue;">`GET`</mark> `https://direct.revicom.ltd/api/v1/balance`

The method allows for getting the value of the account balance

#### Headers

| Name                                            | Type   | Description                                                        |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------ |
| Authorization<mark style="color:red;">\*</mark> | string | <p><code>Basic {TOKEN}</code><br>Token of any type can be used</p> |

{% tabs %}
{% tab title="200" %}
In the successful response, the object from the pairs “currency” : “value” is returned.

```
{
  "USD": 1200.00
}
```

{% endtab %}
{% endtabs %}

#### Request example

{% tabs %}
{% tab title="JSON" %}

```
GET https://direct.revicom.ltd/api/v1/balance
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
```

{% endtab %}

{% tab title="cURL" %}

```
curl -X GET 'https://direct.revicom.ltd/api/v1/balance' \
-H 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
```

{% endtab %}
{% endtabs %}


# References

## Traffic channels <a href="#channel-types" id="channel-types"></a>

| Channel   |
| --------- |
| SMS       |
| FLASHCALL |
| VIBER     |
| WHATSAPP  |
| VK        |

## Sending methods <a href="#sending-methods" id="sending-methods"></a>

| Sending method | Description                               |
| -------------- | ----------------------------------------- |
| API            | Message was sent via API Direct           |
| UI             | Message was sent via web-interface Direct |

## Message directions <a href="#directions" id="directions"></a>

| Direction | Description      |
| --------- | ---------------- |
| outbound  | Outbound message |
| inbound   | Inbound message  |

## Traffic types <a href="#traffic-types" id="traffic-types"></a>

| Traffic type | Description           |
| ------------ | --------------------- |
| PROMO        | Advertasing traffic   |
| SERVICE      | Service traffic       |
| AUTHORIZE    | Authorization traffic |
| TRANSACT     | Transaction traffic   |

## Main message statuses <a href="#message-states" id="message-states"></a>

| Message status | Description                     |
| -------------- | ------------------------------- |
| delivered      | Delivered (final status)        |
| undelivered    | Undelivered (final status)      |
| unsent         | Unsent (final status)           |
| sent           | Sent; awaiting the final status |
| sending        | Awaiting sending                |

## Read message statuses <a href="#message-read-states" id="message-read-states"></a>

| Message read status | Description                                                                                      |
| ------------------- | ------------------------------------------------------------------------------------------------ |
| read                | Read; available for channels: VIBER, VK, WHATSAPP                                                |
| unread              | Not read during the lifetime of the message (`ttl`); available for channels: VIBER, VK, WHATSAPP |

## Cascading conditions <a href="#cascade-conditions" id="cascade-conditions"></a>

| Condition      | Description                                                                                                          |
| -------------- | -------------------------------------------------------------------------------------------------------------------- |
| not\_delivered | The next cascading message is generated when this message does not receive the delivered status during its lifetime. |
| not\_read      | The next cascaded message is generated when this message has not received the read status during its lifetime.       |

## Callback events <a href="#callback-events" id="callback-events"></a>

| Callback event | Description                                                                                                      |
| -------------- | ---------------------------------------------------------------------------------------------------------------- |
| delivered      | <p>Message received one of the final statuses:</p><ul><li>delivered</li><li>undelivered</li><li>unsent</li></ul> |
| sent           | Message received the status sent                                                                                 |
| read           | <p>Message received one of the statuses:</p><ul><li>read</li><li>unread</li></ul>                                |
| price          | Changing of the message price                                                                                    |
| click          | Click through shortened link                                                                                     |

## FLASHCALL conversion result <a href="#flashcall-result" id="flashcall-result"></a>

| Conversion result | Description            |
| ----------------- | ---------------------- |
| NUMBER\_VERIFIED  | Code verified          |
| WRONG\_CODE       | Wrong code was entered |

## Dispatch statuses <a href="#dispatch-states" id="dispatch-states"></a>

| Status    | Description                                                            |
| --------- | ---------------------------------------------------------------------- |
| initiated | Dispatch is being generated                                            |
| changing  | Transitional status: dispatch is in the process of updating the status |
| scheduled | Dispatch is scheduled: start time has not come yet                     |
| sending   | Dispatch is being sent                                                 |
| awaiting  | All dispatch messages have been sent, awaiting statuses                |
| done      | All dispatch messages have been sent, statuses done *(final status)*   |
| paused    | Dispatch is paused                                                     |
| stopped   | Dispatching is stopped *(final status)*                                |

## Dispatch rate <a href="#dispatch_velocity" id="dispatch_velocity"></a>

| rateTerm value | Description                                                                                                                                 |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| d              | the number of messages sent per day, **taking into account the allowed sending hours**, is guaranteed not to exceed the `rate` value :star: |
| h              | the number of messages sent per hour is guaranteed not to exceed the `rate` value                                                           |
| m              | the number of messages sent per minute is guaranteed not to exceed the `rate` value                                                         |

&#x20;:star: For example, when generating a dispatch with the parameters:

```
"rate": 100000,
"rateTerm": "d",
"hours": [10, 11, 12, 13, 14]
```

&#x20;the number of the `rate` messages will be sent within the five allowable sending `hours`. Thus, the maximum allowable dispatch rate will be 20,000 messages per hour.

However, if `hours` are specified: `[10, 11]`, then the maximum allowed dispatch rate will be 50,000 messages per hour.

:warning:The hours value will not be taken into account if `"rateTerm": "h"` or `"rateTerm": "m"` are specified


# Messages Error Codes

| Code | Description                                                       |
| ---- | ----------------------------------------------------------------- |
| 0    | Message is successfully delivered                                 |
| 6969 | Unknown error                                                     |
| 7031 | Message text contains prohibited words                            |
| 7032 | Subscriber denied                                                 |
| 7040 | The recipient number incorrect or not existing                    |
| 7050 | Technical error when sending a message                            |
| 7060 | Status timed out                                                  |
| 7070 | Send time expired                                                 |
| 7080 | Dispatch canceled by user                                         |
| 7091 | Dispatch timeout expired                                          |
| 7092 | The allowable time of the process of creating a dispatch expired  |
| 7093 | The allowable pause time expired                                  |
| 7401 | No substitutions for dispatch text                                |
| 7402 | Invalid subscriber number when filling the dispatch with messages |