# Отправка WHATSAPP

{% hint style="warning" %}
Для получения возможности отправки WHATSAPP-сообщений необходимо заполнить [анкету](https://i-dgtl.ru/wa-registration-2/), после чего будет зарегистрировано имя отправителя и шаблон для отправки сообщений.

Получение WHATSAPP-шаблонов и преобразование в сообщения описано [здесь](/templates/get.md#formirovanie-whatsapp-soobsheniya).
{% endhint %}

{% hint style="info" %}
Отправка сообщений происходит в режиме чата:

* если чат инициируется клиентом, первое сообщение должно соответствовать зарегистрированному шаблону. После каждого ответа абонента открывается 24-часовое окно для отправки сообщений с произвольным содержанием. Если абонент не ответил, клиент может отправлять сообщения пользователю вне рамок 24-часового окна с использованием заранее зарегистрированных шаблонов сообщений;
* если чат инициируется абонентом, в течение 24-часового окна клиент может отправлять сообщения с произвольным содержанием.
  {% endhint %}

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

<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  | Канал отправки (`WHATSAPP`)                                                                                                                                                                                                                                                                              |
| senderName<mark style="color:red;">\*</mark>  | string  | Имя отправителя. Допускаются WHATSAPP-имена в статусе "Одобрено"                                                                                                                                                                                                                                         |
| destination<mark style="color:red;">\*</mark> | string  | Номер абонента                                                                                                                                                                                                                                                                                           |
| content<mark style="color:red;">\*</mark>     | object  | Контент сообщения. Ниже описаны возможные варианты содержимого.                                                                                                                                                                                                                                          |
| 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>По умолчанию false</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",
      "code": 201
    },
    {
      "messageUuid": "063564ec-a34f-4558-90c5-984395000005",
      "code": 201
    }
  ]
}
```

{% endtab %}

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

{% 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" %}
Использование неподходящего токена.

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

{% endtab %}

{% tab title="422" %}
Невалидные параметры в теле запроса; ниже приведены несколько примеров ответа.

```
{
    "error": {
        "code": 4220,
        "msg": "Invalid msisdn"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Invalid text length in viber content (0)"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Invalid caption length in viber content (3)"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Invalid caption length in viber content (3)"
    }
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

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

{% hint style="danger" %}
Для данного канала рекомендуется использовать ttl не менее 24 часов, так как сервис может доставить сообщение даже спустя 24 часа неактивности абонента (например, если устройство было выключено).
{% endhint %}

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

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

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

## Текстовое сообщение <a href="#text" id="text"></a>

Текстовое WHATSAPP-сообщение, помимо текста, может содержать заголовок, подпись и кнопки.

Для отправки текстового WHATSAPP-сообщения используется следующий объект `content`:

```
{
  "contentType": "text",
  "text": "текст whatsapp-сообщения",
  "header": {
    "text": "Заголовок сообщения"
  },
  "footer": {
    "text": "Подпись сообщения"
  },
  "buttons": [
    {
      "text": "текст кнопки",
      "url": "https://i-dgtl.ru"
    },
    {
      "text": "текст второй кнопки",
      "phone": "78124269988"
    }
  ]
}
```

| Параметр            | Тип                                         | Описание                                                                                                              |
| ------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| contentType         | <p>string</p><p><em>required</em></p>       | Тип контента (`text`)                                                                                                 |
| text                | <p>string</p><p><em>required</em></p>       | <p>Текст сообщения; строка в кодировке UTF-8 без Byte Order Mark</p><p>От 1 до 1000 символов</p>                      |
| header              | <p>object<br><em>optional</em></p>          | Заголовок сообщения                                                                                                   |
| header.text         | <p>string<br><em>optonal</em></p>           | <p>Текст для заголовка<br>От 1 до 60 символов</p>                                                                     |
| header.documentUrl  | <p>string<br><em>optional</em></p>          | Ссылка на документ для заголовка. Документ должен быть в формате PDF.                                                 |
| header.documentName | <p>string<br><em>optio</em>n<em>al</em></p> | Название документа для заголовка; может присутствовать только при наличии documentUrl                                 |
| header.imageUrl     | <p>string<br><em>optional</em></p>          | Ссылка на изображение для заголовка. Изображение должно быть в формате JPG или PNG                                    |
| footer              | <p>object<br><em>optional</em></p>          | Подпись сообщения                                                                                                     |
| footer.text         | <p>string<br><em>optional</em></p>          | Текст для подписи; от 1 до 60 символов                                                                                |
| buttons             | <p>array (objects)<br><em>optional</em></p> | Массив с объектами кнопок                                                                                             |
| buttons.text        | <p>string<br><em>optonal</em></p>           | Текст кнопки; от 1 до 25 символов                                                                                     |
| buttons.url         | <p>string<br><em>optional</em></p>          | Ссылка, на которую происходит переход при нажатии на кнопку; от 1 до 1000 символов; должна начинаться с `http`        |
| buttons.phone       | <p>string<br><em>optional</em></p>          | Телефонный номер, на который предлагается сделать вызов при нажатии на кнопку; от 1 до 1000 символов                  |
| buttons.payload     | <p>string<br><em>optional</em></p>          | Скрытый текст, который будет передан во входящем сообщении, если пользователь нажмет на кнопку; от 1 до 1000 символов |

### Заголовок в сообщениях <a href="#header" id="header"></a>

в объекте `header` допускается использовать только одно из:

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

### Кнопки в сообщениях <a href="#buttons" id="buttons"></a>

* кнопки передаются объектами в массиве `buttons`&#x20;
* в каждом объекте обязателен `text`
* существует два типа кнопок:
  * кнопка с ссылкой: содержит `text` и `url` или `text` и `phone`
  * кнопка с текстом: содержит `text` и `payload`
* в одном сообщении допускается передача кнопок только одного типа (то есть передача `payload`-кнопок вместе с `url/phone`-кнопками не допускается)
* в сообщении допускается только одна кнопка с параметром `url`
* в сообщении допускается только одна кнопка с параметром `phone`
* при передаче кнопок с текстом допускается не более трех объектов в массиве
* при передаче кнопок с ссылкой допускается не более двух объектов в массиве
* наличие кнопок в сообщении не влияет на возможность наличия заголовка и подписи

### Примеры объектов <a href="#object_examples" id="object_examples"></a>

{% tabs %}
{% tab title="Текст" %}

```
{
  "contentType": "text",
  "text": "текст сообщения"
}
```

{% endtab %}

{% tab title="С заголовком" %}

```
{
  "contentType": "text",
  "text": "Текст сообщения",
  "header": {
    "documentUrl": "https://example.com/document.pdf",
    "documentName": "document.pdf"
  }
}
```

{% endtab %}

{% tab title="С заголовком и подписью" %}

```
{
  "contentType": "text",
  "text": "Текст сообщения",
  "header": {
    "imageUrl": "https://example.com/image.png"
  },
  "footer": {
  "text": "Подпись сообщения"
  }
}
```

{% endtab %}

{% tab title="С текстовыми кнопками" %}

```
{
  "contentType": "text",
  "text": "Текст сообщения",
  "buttons": [
    {
      "text": "текст кнопки 1",
      "payload": "id=1"
    },
    {
      "text": "текст кнопки 2",
      "payload": "id=2"
    }
  ]
}
```

{% endtab %}

{% tab title="С кнопками и ссылками" %}

```
{
  "contentType": "text",
  "text": "Текст сообщения",
  "buttons": [
    {
      "text": "текст кнопки 1",
      "url": "https://i-dgtl.ru/"
    },
    {
      "text": "текст кнопки 2",
      "phone": "78124269988"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Аутентификационное сообщение <a href="#authentication" id="authentication"></a>

Для отправки аутентификационного WHATSAPP-сообщения используется следующий объект content:

```
{
  "contentType": "authentication",
  "text": "1234",
  "lang": "ru",
  "addSecurityRecommendation": true,
  "codeExpirationMinutes": 10,
  "buttons": [
    {
      "text": "Скопировать"
    }
  ]
}
```

| Параметр                  | Тип                                 | Описание                                                                                                                                                                                       |
| ------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| contentType               | <p>string<br><em>required</em></p>  | Тип контента (`authentication`)                                                                                                                                                                |
| text                      | <p>string<br><em>required</em></p>  | Текст сообщения, не более 15 символов                                                                                                                                                          |
| lang                      | <p>string<br><em>required</em></p>  | Язык сообщения, не более 2 символов                                                                                                                                                            |
| addSecurityRecommendation | <p>boolean<br><em>required</em></p> | Определяет, будет ли сообщение содержать предустановленный текст безопасности                                                                                                                  |
| codeExpirationMinutes     | <p>integer<br><em>optional</em></p> | Срок действия пароля или кода в минутах. Если не указывать этот параметр, сообщение не будет содержать предупреждение об истечении срока действия пароля. **Допустимые значения: от 1 до 90**. |
| buttons                   | <p>array<br><em>required</em></p>   | Массив кнопок. Должен содержать ровно одну кнопку.                                                                                                                                             |
| buttons.text              | <p>string<br><em>required</em></p>  | Текст на кнопке, не более 25 символов                                                                                                                                                          |

{% hint style="warning" %}
Значения параметров lang, addSecurityRecommendation, codeExpirationMinutes, buttons.text должны соответствовать указанным в зарегистрированном шаблоне
{% endhint %}

## Сообщение с изображением <a href="#image" id="image"></a>

Для отправки WHATSAPP-сообщения с изображением используется следующий объект `content`:

```
{
  "contentType": "image",
  "imageUrl": "https://image.png",
  "imageName": "Изображение"
}
```

| Параметр    | Тип                                   | Описание               |
| ----------- | ------------------------------------- | ---------------------- |
| contentType | <p>string</p><p><em>required</em></p> | Тип контента (`image`) |
| imageUrl    | <p>string</p><p><em>required</em></p> | Ссылка на изображение  |
| imageName   | <p>string<br><em>required</em></p>    | Название изображения   |

## Сообщение с документом <a href="#document" id="document"></a>

Для отправки WHATSAPP-сообщения с документом используется следующий объект `content`:

```
{
  "contentType": "document",
  "documentUrl": "https://document.pdf",
  "documentName": "Документ"
}
```

| Параметр     | Тип                                   | Описание                  |
| ------------ | ------------------------------------- | ------------------------- |
| contentType  | <p>string</p><p><em>required</em></p> | Тип контента (`document`) |
| documentUrl  | <p>string</p><p><em>required</em></p> | Ссылка на документ        |
| documentName | <p>string<br><em>required</em></p>    | Название документа        |

## Сообщение с видео <a href="#video" id="video"></a>

Для отправки WHATSAPP-сообщения с видео используется следующий объект `content`:

```
{
  "contentType": "video",
  "videoUrl": "https://video.mp4",
  "videoName": "Название видео"
}
```

| Параметр    | Тип                                   | Описание               |
| ----------- | ------------------------------------- | ---------------------- |
| contentType | <p>string</p><p><em>required</em></p> | Тип контента (`video`) |
| videoUrl    | <p>string</p><p><em>required</em></p> | Ссылка на видео        |
| videoName   | <p>string<br><em>optional</em></p>    | Название видео         |

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

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

```
POST https://direct.i-dgtl.ru/api/v1/message
Authorization: Basic QWxhZGRpbjp...
Content-Type: application/json
[
  {
    "senderName": "SENDER",
    "channelType": "WHATSAPP",
    "content": {
      "contentType": "text",
      "text": "Текст WHATSAPP-сообщения",
    },
    "destination": "7818242882",
  }
]
```

{% endtab %}

{% tab title="cURL" %}

```
curl -X POST 'https://direct.i-dgtl.ru/api/v1/message' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic QWxhZGRpbjpvc...' \
-d '[{"senderName":"SENDER","channelType":"WHATSAPP","content":{"contentType":"text","text":"Текст WHATSAPP-сообщения"},"destination":"7818242882"}]'
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
В примере указан минимальный набор параметров, который позволяет моментально отправить WHATSAPP-сообщение (при наличии зарегистрированного имени отправителя и шаблона). Вы можете кастомизировать контент, время отправки, настроить коллбэки и добавить теги, используя опциональные параметры, описанные выше на данной странице.&#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/whatsapp-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.