# WhatsApp

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

Поддерживается отправка сообщений в режиме чата:

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

Шаблонные сообщения могут содержать следующие типы контента:

* текст;
* кнопки с ссылками (URL и/или номер телефона);
* кнопки с текстом (до 3 кнопок);
* заголовок с текстом;
* заголовок с изображением;
* заголовок с документом;
* подпись сообщения.

Сообщения, отправленные в период 24 часового окна, могут содержать любой тип контента;

Сообщения, содержащие заголовок, подпись, кнопки с ссылками или кнопки с текстом обязательно должны соответствовать зарегистрированному шаблону, независимо от момента отправки;

Весь медиаконтент, передаваемый в WhatsApp-сообщениях, является строкой: двойные кавычки необходимо экранировать при помощи обратной косой черты.

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

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

Метод позволяет отправить одиночное WhatsApp-сообщение.\
Ниже перечислены общие параметры запроса.

#### Headers

| Name          | Type   | Description                 |
| ------------- | ------ | --------------------------- |
| Content-Type  | string | application/json            |
| Authorization | string | 'nodeID:password' \| base64 |

#### Request Body

| Name            | Type    | Description                                                                                                                                                                                                                             |
| --------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| @type           | string  | Тип сообщения, имеет постоянное значение оutbound (исходящее).                                                                                                                                                                          |
| addresses       | object  | Объект, содержащий адреса отправителя и получателя.                                                                                                                                                                                     |
| source          | string  | Имя отправителя.                                                                                                                                                                                                                        |
| destination     | string  | Номер телефона получателя. Указывается в международном формате MSISDN, состоящем из кода страны, DEF-кода оператора и номера абонента. Например, российский номер выглядит так: 79001234567, где 7 - код страны (Россия).               |
| body            | object  | Объект, в котором передаётся содержимое сообщения.                                                                                                                                                                                      |
| bodyType        | string  | Тип сообщения (WhatsApp).                                                                                                                                                                                                               |
| content         | string  | Контент сообщения. Ниже описаны возможные варианты содержимого.                                                                                                                                                                         |
| nodeId          | integer | Номер ноды                                                                                                                                                                                                                              |
| requestDelivery | boolean | Указывает, cледует ли предоставлять отчёт о доставке после отправки сообщения (true\|false).                                                                                                                                            |
| expirationDate  | integer | <p>Время, до которого будет ожидаться получение статуса от оператора.<br>Тип значения - <strong>timestamp</strong> в миллисекундах или в формате ISO 8601.<br>По умолчанию составляет 24 часа с момента отправки сообщения.<br><br></p> |

::::{tab-set}

:::{tab-item} 200 В случае успешного запроса возвращается ответ, в котором указан идентификатор сообщения и время отправки сообщения в формате Unix Timestamp.

```
{
    "id": "41937aa1-6322-1264-3409-aa0003429600",
    "timestamp": 1632212643428,
    "code": 200
}
```
:::


:::{tab-item} 400 Неверный синтаксис запроса

```
{
    "timestamp": 1632212694926,
    "code": 400,
    "description": "incorrect request body"
}
```
:::

::::


## Текстовое сообщение

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

```
POST https://external-api.i-dgtl.ru/message
Authorization: Basic Mzk5OTk6MTIzNjU0
Content-Type: application/json

{
    "@type": "outbound",
    "addresses": {
        "source": "Testing",
        "destination": "79500197493"
    },
    "body": {
        "bodyType": "whatsapp",
        "content": "Have a nice day!"
    },
    "nodeId": 31937,
    "requestDelivery": true
}
```

| Параметр | Тип                                   | Описание                                                                                    |
| -------- | ------------------------------------- | ------------------------------------------------------------------------------------------- |
| content  | <p>string</p><p><em>required</em></p> | <p>Текст сообщения.</p><p>Объём отправляемого текста не должен превышать 1000 символов.</p> |

## Сообщение с графическим вложением

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

```
POST https://external-api.i-dgtl.ru/message
Authorization: Basic Mzk5OTk6MTIzNjU0
Content-Type: application/json

{
    "@type": "outbound",
    "addresses": {
        "source": "Testing",
        "destination": "79500197493"
    },
    "body": {
        "bodyType": "whatsapp",
        "content": "{\"content_type\":\"image\",\"imageUrl\":\"ссылка на изображение\"}"
    },
    "nodeId": 31937,
    "requestDelivery": true
}
```

| Параметр      | Тип                                   | Описание               |
| ------------- | ------------------------------------- | ---------------------- |
| content\_type | <p>string</p><p><em>required</em></p> | Тип контента (`image`) |
| imageUrl      | <p>string</p><p><em>required</em></p> | Ссылка на изображение  |
| imageName     | <p>string</p><p><em>required</em></p> | Подпись к изображению  |

::::::{tip}
* так как параметр content\_type является строкой, двойные кавычки необходимо экранировать при помощи обратной косой черты;
* поддерживаемые форматы изображений - JPEG и PNG;
* оптимальный размер изображения - 400x400 пикселей;
* размер отправляемого изображения не должен превышать 100 МБ.
::::::

## Сообщение с вложенным документом <a href="#button" id="button"></a>

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

```
POST https://external-api.i-dgtl.ru/message
Authorization: Basic Mzk5OTk6MTIzNjU0
Content-Type: application/json

{
    "@type": "outbound",
    "addresses": {
        "source": "Testing",
        "destination": "79500197493"
    },
    "body": {
        "bodyType": "whatsapp",
        "content":  "{\"content_type\":\"document\",\"documentUrl\":\"https://i-dgtl.ru/content/uploads/2020/12/Tipovoj_dogovor-i-Digital.pdf\",\"documentName\":\"Типовой договор\"}"
    },
    "nodeId": 31937,
    "requestDelivery": true
}
```

| Параметр      | Тип                                   | Описание                                    |
| ------------- | ------------------------------------- | ------------------------------------------- |
| content\_type | <p>string</p><p><em>required</em></p> | Тип контента (`document`)                   |
| documentUrl   | <p>string</p><p><em>required</em></p> | Ссылка на отправляемый в сообщении документ |
| documentName  | <p>string</p><p><em>required</em></p> | Наименование документа                      |

::::::{tip}
* так как параметр content\_type является строкой, двойные кавычки необходимо экранировать при помощи обратной косой черты;
* в виде документа может быть отправлен файл следующих форматов: .doc .docx .pdf;
* размер отправляемого изображения не должен превышать 100 МБ.
::::::

## Сообщение с аудиофайлом <a href="#button" id="button"></a>

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

```
POST https://external-api.i-dgtl.ru/message
Authorization: Basic Mzk5OTk6MTIzNjU0
Content-Type: application/json

{
    "@type": "outbound",
    "addresses": {
        "source": "Testing",
        "destination": "79500197493"
    },
    "body": {
        "bodyType": "whatsapp",
        "{\"content_type\":\"audio\",\"audioUrl\":\"http://example.com/audios/hello.mp3\"}"
    },
    "nodeId": 31937,
    "requestDelivery": true
}
```

| Параметр      | Тип                                   | Описание                                     |
| ------------- | ------------------------------------- | -------------------------------------------- |
| content\_type | <p>string</p><p><em>required</em></p> | Тип контента (`audio`)                       |
| audioUrl      | <p>string</p><p><em>required</em></p> | ссылка на отправляемый в сообщении аудиофайл |

::::::{tip}
* так как параметр content\_type является строкой, двойные кавычки необходимо экранировать при помощи обратной косой черты;
* поддерживаемые аудиоформаты: mp3, ogg, AAC;
* поддерживаемые кодеки: AMR, MPEG, Opu;
* размер отправляемого изображения не должен превышать 100 МБ.
::::::

## Сообщение с видеофайлом <a href="#button" id="button"></a>

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

```
POST https://external-api.i-dgtl.ru/message
Authorization: Basic Mzk5OTk6MTIzNjU0
Content-Type: application/json

{
    "@type": "outbound",
    "addresses": {
        "source": "Testing",
        "destination": "79500197493"
    },
    "body": {
        "bodyType": "whatsapp",
        "content": "{\"content_type\":\"video\",\"videoUrl\":\"http://example.com/videos/hello.mp4\",\"videoName\":\"Добро пожаловать\"}"
    },
    "nodeId": 31937,
    "requestDelivery": true
}
```

| Параметр      | Тип                                   | Описание                                     |
| ------------- | ------------------------------------- | -------------------------------------------- |
| content\_type | <p>string</p><p><em>required</em></p> | Тип контента (`video`)                       |
| videoUrl      | <p>string</p><p><em>required</em></p> | Ссылка на отправляемый в сообщении видеофайл |
| videoName     | string required                       | Наименование видеофайла                      |

::::::{tip}
* так как параметр content\_type является строкой, двойные кавычки необходимо экранировать при помощи обратной косой черты;
* поддерживаемые видеоформаты: mp4;
* поддерживаемые кодеки: H.264 и AAC;
* размер отправляемого изображения не должен превышать 100 МБ.
::::::

## Сообщение с кнопкой-ссылкой и номером телефона <a href="#button" id="button"></a>

Для отправки WhatsApp-сообщения с кнопкой-ссылкой и номером телефона используется следующий запрос:

```
POST https://external-api.i-dgtl.ru/message
Authorization: Basic Mzk5OTk6MTIzNjU0
Content-Type: application/json

{
    "@type": "outbound",
    "addresses": {
        "source": "Testing",
        "destination": "79500197493"
    },
    "body": {
        "bodyType": "whatsapp",
        "content": "{\"content_type\":\"text\",\"buttons\":[{\"text\":\"Наш сайт\",\"url\":\"https://i-dgtl.ru\"},{\"text\":\"Позвоните нам\",\"phone\":\"78124269988\"}],\"text\":\"Текст сообщения\"}"
    },
    "nodeId": 31937,
    "requestDelivery": true
}
```

| Параметр      | Тип                                   | Описание                                                                                                                               |
| ------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| content\_type | <p>string</p><p><em>required</em></p> | Тип контента (`text`)                                                                                                                  |
| buttons       | <p>string</p><p><em>required</em></p> |  Массив параметров, передаваемых с кнопками                                                                                            |
|       text    | string required                       | <p>Наименование, отображаемое на кнопке.</p><p>Максимальный размер - 20 символов.</p>                                                  |
|       url     | string required                       | Ссылка, на которую будет выполнен переход после нажатия                                                                                |
|       phone   | string required                       | <p>Номер телефона в формате</p><p>+СХХХ ХХХ-ХХ-ХХ, где С – код страны, Х – номер телефона,</p><p>Задается при регистрации шаблона.</p> |

::::::{tip}
* максимальное количество кнопок - 2;
* может быть только одна кнопка со ссылкой на сайт;
* может быть только одна кнопка с номером телефона: при нажатии на неё пользователю будет предложено позвонить по номеру телефона.
::::::

## Сообщение с интерактивным списком <a href="#button" id="button"></a>

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

```
POST https://external-api.i-dgtl.ru/message
Authorization: Basic Mzk5OTk6MTIzNjU0
Content-Type: application/json

{
    "@type": "outbound",
    "addresses": {
        "source": "Testing",
        "destination": "79500197493"
    },
    "body": {
        "bodyType": "whatsapp",
        "content": "{\"content_type\":\"list_picker\",\"button\":\"Main Menu\",\"sections\":[{\"title\":\"First Section\",\"items\":[{\"identifier\":\"1\",\"title\":\"Buy bundles\",\"subtitle\":\"You can add a note here\"},{\"identifier\":\"2\",\"title\":\"Buy airtime\",\"subtitle\":\"You can add a note here\"},{\"identifier\":\"3\",\"title\":\"Manage your account\",\"subtitle\":\"You can add a note here\"}]},{\"title\":\"Second Section\",\"items\":[{\"identifier\":\"4\",\"title\":\"FAQs\",\"subtitle\":\"You can add a note here\"},{\"identifier\":\"5\",\"title\":\"Get help with a problem\",\"subtitle\":\"You can add a note here\"}]}],\"text\":\"Текст сообщения\"}"
    },
    "nodeId": 31937,
    "requestDelivery": true
}
```

| Параметр      | Тип                                   | Описание                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| content\_type | <p>string</p><p><em>required</em></p> | Тип контента (`list_picker`)                                                                                                                                                                                                                                                                                                                                                                                        |
| button        | <p>string</p><p><em>required</em></p> | Наименование кнопки для интерактивного списка.                                                                                                                                                                                                                                                                                                                                                                      |
| sections      | string _required_                     | Массив, содержащий информацию о кнопках в списке                                                                                                                                                                                                                                                                                                                                                                    |
| title         | string _required_                     | Заголовок секции с элементами, который отображается пользователю.                                                                                                                                                                                                                                                                                                                                                   |
| items         | string required                       | <p>Список объектов item, объект содержит поля:</p><p><strong><code>title</code></strong> – <em>string (required)</em> – название элемента</p><p><strong><code>subtitle</code></strong> – <em>string (required)</em> – подзаголовок элемента</p><p><strong><code>identifier</code></strong> – <em>string (required)</em> – сквозной для всего сообщения ID элемента, вернется в ответном сообщении пользователя.</p> |

::::::{tip}
* Пользователь может выбрать один и тот же вариант несколько раз или новый вариант. На каждый выбор будет сформировано входящее сообщение.
::::::

## Сообщение с кнопкой с текстом <a href="#button" id="button"></a>

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

```
POST https://external-api.i-dgtl.ru/message
Authorization: Basic Mzk5OTk6MTIzNjU0
Content-Type: application/json

{
    "@type": "outbound",
    "addresses": {
        "source": "Testing",
        "destination": "79500197493"
    },
    "body": {
        "bodyType": "whatsapp",
        "content": "{ \"content_type\":\"text\", \"buttons\":[ {\"text\":\"Название  кнопки_1\", \"payload\":\"скрытый текст_1\"}, {\"text\":\"Название кнопки_2\", \"payload\":\"скрытый текст_2\"}, {\"text\":\"Название кнопки_3\", \"payload\":\"скрытый текст_3\"}],  \"text\": \"Текст сообщения\" }"
    },
    "nodeId": 31937,
    "requestDelivery": true
}
```

| Параметр      | Тип                                   | Описание                                                                                                                                             |
| ------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| content\_type | <p>string</p><p><em>required</em></p> | Тип контента (`text`)                                                                                                                                |
| buttons       | <p>string</p><p><em>required</em></p> |  Массив параметров, передаваемых с кнопками                                                                                                          |
|       text    | string required                       | <p>Наименование, отображаемое на кнопке.</p><p>Максимальный размер - 20 символов.</p>                                                                |
|       payload | string required                       | <p>Скрытый текст, который будет передан во входящем сообщении, если пользователь нажмет на кнопку,</p><p>максимальное количество символов - 128.</p> |

::::::{tip}
* комбинировать кнопку с текстом с кнопкой-ссылкой не допускается;
* максимальное количество кнопок в сообщении – 3;
::::::

## Сообщение с контентом в заголовке <a href="#button" id="button"></a>

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

```
POST https://external-api.i-dgtl.ru/message
Authorization: Basic Mzk5OTk6MTIzNjU0
Content-Type: application/json

{
    "@type": "outbound",
    "addresses": {
        "source": "Testing",
        "destination": "79500197493"
    },
    "body": {
        "bodyType": "whatsapp",
        "content": "{\"content_type\":\"text\",\"text\":\"Текст сообщения\",\"header\":{\"documentUrl\":\"ссылка на документ\",\"documentName\":\"Название документа\"},\"footer\":{\"text\":\"Текст подписи\"}}
    },
    "nodeId": 31937,
    "requestDelivery": true
}
```

| Параметр        | Тип                                   | Описание                                                        |
| --------------- | ------------------------------------- | --------------------------------------------------------------- |
| content\_type   | <p>string</p><p><em>required</em></p> | Тип контента (`text`)                                           |
| header          | string optional                       | Массив параметров, передаваемых в заголовке сообщения.          |
|       text      | <p>string</p><p><em>optional</em></p> | <p>Текст заголовка.</p><p>Максимальная длина - 60 символов.</p> |
|       imageUrl  | <p>string</p><p><em>optional</em></p> | Ссылка на изображение в заголовке.                              |
| documentUrl     | string _optional_                     | Ссылка на документ в заголовке.                                 |
| string optional | string _optional_                     | Наименование документа в заголовке.                             |
| footer          | string _optional_                     | Массив параметров, передаваемых в подписи.                      |
|       text      | string _optional_                     | <p>Текст подписи.</p><p>Максимальная длина - 60 символов.</p>   |

::::::{tip}
* отправлять одновременно в заголовке текст, изображение и документ не допускается;
* рекомендовано использовать изображение размером не меньше 400x400px с расширением JPG или PNG;
* формат документа – pdf.
::::::

## Ограничения

### Текстовые сообщения
- Максимальная длина текста WhatsApp-сообщения — **1000 символов**.

### Упрощённый формат (входящие)
- Максимальная длина текста — **1000 символов**.
- Этот формат используется по умолчанию для входящих сообщений.

### Изображения
- Поддерживаемые форматы: **JPEG**, **PNG**.
- Максимальный размер изображения — **100 МБ**.
- Максимальное разрешение — **400×400** пикселей.

### Документы
- Может быть отправлен файл любого формата.
- Максимальный размер документа — **100 МБ**.

### Аудио
- Поддерживаемые форматы: **MP3**, **OGG**, **AAC**.
- Максимальный размер аудиофайла — **100 МБ**.

### Видео
- Поддерживаемый формат: **MP4**.
- Максимальный размер видеофайла — **100 МБ**.

### Кнопки
- Максимальное количество кнопок в сообщении:  
  - **2** (одна ссылка + один телефон), либо  
  - **3 текстовые кнопки**.
- Нельзя комбинировать текстовые кнопки с кнопкой-ссылкой.
- Текст кнопки — до **20 символов**.
- Для кнопки с номером телефона: номер должен быть в формате `tel:+XXXXXXXXXXX`.

### Заголовок и подпись
- Максимальная длина заголовка — **60 символов**.
- Максимальная длина подписи — **60 символов**.