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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api.direct.revicom.ltd/messages/sending-voicecode.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.