# Отправка SMS

## Отправка SMS-сообщений

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

Метод позволяет отправлять массив одиночных сообщений **(от 1 до 1000)**

#### 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  | Канал отправки (`SMS`)                                                                                                                                                                                                                                                                                     |
| senderName<mark style="color:red;">\*</mark>  | string  | Имя отправителя. Допускаются SMS-имена в статусе "Одобрено" с датой начала действия не позднее, чем время отправки запроса                                                                                                                                                                                 |
| destination<mark style="color:red;">\*</mark> | string  | Номер абонента                                                                                                                                                                                                                                                                                             |
| content<mark style="color:red;">\*</mark>     | string  | Сообщение; строка в кодировке UTF-8 без Byte Order Mark                                                                                                                                                                                                                                                    |
| tags                                          | array   | Теги сообщения (массив строк). Каждый тег должен соответствовать выражению `^\w+$` (допускаются буквы в любом регистре, цифры и нижнее подчеркивание "\_")                                                                                                                                                 |
| useLocalTime                                  | boolean | <p>Флаг, отвечающий за таймзону, в которой будет отправлено сообщение:<br><strong><code>true</code></strong> – отправка в таймзоне абонента<br><strong><code>false</code></strong> – отправка по МСК<br><em>По умолчанию true</em></p>                                                                     |
| localSendTime                                 | string  | <p>Нижняя граница допустимого времени отправки сообщения (с учетом значения<code>useLocalTime</code>)<br>Дата в формате '<code>YYYY-MM-DD hh:mm:ss</code>' в диапазоне от (текущее время в UTC - 12 часов) до (текущее время в UTC + 7 дней)<br><em>По умолчанию сообщение будет отправлено сразу</em></p> |
| localCompletionTime                           | string  | Верхняя граница допустимого времени отправки сообщения (с учетом `useLocalTime`) в диапазоне от `localSendTime` до (текущее время в UTC + 70 дней)                                                                                                                                                         |
| ttl                                           | integer | <p>Время жизни сообщения в секундах. По истечении ttl сообщению устанавливается финальный статус.<br><code>60 ≤ ttl ≤ 86400</code></p>                                                                                                                                                                     |
| hours                                         | array   | Допустимые часы отправки (массив чисел). В массиве могут быть переданы целые числа от 0 до 23, каждое из которых соответствует разрешенному для отправки часовому интервалу с учетом `useLocalTime;` значения должны быть уникальны.                                                                       |
| days                                          | array   | Допустимые дни отправки (массив чисел). В массиве могут быть переданы целые числа от 1 (пн) до 7 (вс), каждое из которых соответствует разрешенному для отправки дню недели; значения должны быть уникальны.                                                                                               |
| shortUrl                                      | boolean | <p>Флаг, отвечающий за сокращение ссылок в сообщении:<br><code>true</code>- ссылки в тексте сообщения будут сокращены<br>По умолчанию <code>false</code></p>                                                                                                                                               |
| callbackUrl                                   | string  | Адрес для отправки callback                                                                                                                                                                                                                                                                                |
| callbackEvents                                | array   | События, по которым будут отправлены callback (массив строк). При наличии `callbackUrl` и отсутствии `callbackEvents` в запросе, будет отправлен callback по событию `delivered`                                                                                                                           |
| externalMessageId                             | string  | Внутренний id сообщения в вашей системе. До 100 символов.                                                                                                                                                                                                                                                  |

{% tabs %}
{% tab title="200" %}
В случае успешного запроса возвращается ответ, в котором перечислены идентификаторы сообщений (в том числе ваши, если были переданы) и коды результата. При значении errors = false гарантируется, что все переданные сообщения успешно созданы.

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

{% endtab %}

{% tab title="401" %}
Использование невалидного токена / отсутствие заголовка авторизации.

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

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

{% endtab %}

{% tab title="402" %}
Недостаточно средств на балансе.

```
{
    "error": {
        "code": 402,
        "msg": "Insufficient funds"
    }
}
```

{% endtab %}

{% tab title="403" %}
Использование неподходящего токена.

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

{% endtab %}

{% tab title="422" %}
Невалидные параметры в теле запроса или превышение максимального количества объектов.

<pre><code>// Превышение количества сообщений
{
    "error": {
        "code": 4220,
        "msg": "Max count of messages is 1000"
    }
}
-----------------------------------------------------------------------------
// Некорректное значение localSendTime
{
    "error": {
        "code": 4220,
        "msg": "Local send time is less than minimal {minLocalSendTime}"
    }
}
-----------------------------------------------------------------------------
<strong>// Некорректное значение localSendTime
</strong>{
    "error": {
        "code": 4220,
        "msg": "Local send time is greater than minimal {maxLocalSendTime}"
    }
}
-----------------------------------------------------------------------------
// Некорректное значение localCompletionTime
<strong>{
</strong>    "error": {
        "code": 4220,
        "msg": "Local completion time is less than minimal {minLocalCompletionTime}"
    }
}
-----------------------------------------------------------------------------
// Некорректное значение localCompletionTime
<strong>{
</strong>    "error": {
        "code": 4220,
        "msg": "Local completion time is greater than maximal {maxLocalCompletionTime}"
    }
}
-----------------------------------------------------------------------------
// Некорректное значение senderName
<strong>{
</strong>    "error": {
        "code": 4220,
        "msg": "No active sender name: ({channelType}, {senderName})"
    }
}
-----------------------------------------------------------------------------
// Некорректное значение destination
<strong>{
</strong>    "error": {
        "code": 4220,
        "msg": "Invalid msisdn"
    }
}
-----------------------------------------------------------------------------
// Некорректное значение content
{
    "error": {
        "code": 4220,
        "msg": "Blank content"
    }
}
-----------------------------------------------------------------------------
// Некорректное значение tags
{
    "error": {
        "code": 4220,
        "msg": "Invalid tags: {tags}"
    }
}
-----------------------------------------------------------------------------
// Некорректное значение ttl
{
    "error": {
        "code": 4220,
        "msg": "Invalid TTL {ttl}"
    }
}
-----------------------------------------------------------------------------
// Некорректное значение hours
{
    "error": {
        "code": 4222,
        "msg": "Invalid hours: {hours}"
    }
}
-----------------------------------------------------------------------------
// Некорректное значение days
{
    "error": {
        "code": 4223,
        "msg": "Invalid days: {days}"
    }
}
</code></pre>

{% endtab %}

{% tab title="503" %}
Временная недоступность сокращения ссылок. Рекомендуется повторить запрос.

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

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Рекомендуемое время ожидания ответа: 70 секунд.\
Как правило, ответ на запрос возвращается не более чем за несколько секунд, но таймаут величиной в 70 секунд позволяет гарантированно получить ответ на запрос, в том числе в ситуациях повышенной нагрузки.
{% endhint %}

{% hint style="info" %}
В качестве имени отправителя при отправке SMS-сообщений допускается использование имен в статусе "Одобрено" с датой начала действия не позднее текущей.

Имя отправителя можно создать как при помощи [API](/sender-names/post.md), так и в личном кабинете на странице "[Имена отправителей](https://direct.i-dgtl.ru/sender-names/sms)"
{% endhint %}

{% hint style="info" %}
Для использования личного домена в сокращенных ссылках необходимо обратиться в поддержку
{% endhint %}

Возможные варианты перечислений:

| Параметр       | Варианты                                                              |
| -------------- | --------------------------------------------------------------------- |
| callbackEvents | [События для отправки callback](/extra/references.md#callback-events) |

## Тестирование <a href="#testing" id="testing"></a>

Для тестирования отправки SMS без регистрации своего собственного имени отправителя вы можете использовать следующие данные:

* senderName – sms\_promo
* прочие параметры – произвольные, в соответствии с описанием

## Пример запроса <a href="#example" id="example"></a>

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

```
POST https://direct.i-dgtl.ru/api/v1/message
Authorization: Basic QWxhZGRpbjpv...
Content-Type: application/json
[
  {
    "channelType": "SMS",
    "senderName": "sms_promo",
    "destination": "79818268484",
    "content": "Текст сообщения, которое получит абонент"
  }
]
```

{% endtab %}

{% tab title="cURL" %}

```
curl -X POST 'https://direct.i-dgtl.ru/api/v1/message' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
-d '[{"channelType":"SMS","senderName":"sms_promo","destination":"79818268484","content":"Текст сообщения, которое получит абонент"}]'
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
В примере указан минимальный набор параметров, который позволяет моментально отправить SMS. Вы можете кастомизировать время отправки, настроить коллбэки и добавить теги, используя опциональные параметры, описанные в начале данной страницы.&#x20;
{% endhint %}


---

# 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.docs.direct.i-dgtl.ru/messages/sms-sending.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.