> For the complete documentation index, see [llms.txt](https://api.direct.revicom.ltd/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.direct.revicom.ltd/messages/sending-voicecode.md).

# 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.md#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 %}