WhatsApp

Содержание

WhatsApp#

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

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

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

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

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

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

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

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

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

POST 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	Время, до которого будет ожидаться получение статуса от оператора. Тип значения - timestamp в миллисекундах или в формате ISO 8601. По умолчанию составляет 24 часа с момента отправки сообщения.

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

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

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

string

required

Текст сообщения.

Объём отправляемого текста не должен превышать 1000 символов.

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

Для отправки 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

string

required

Тип контента (image)

imageUrl

string

required

Ссылка на изображение

imageName

string

required

Подпись к изображению

Совет

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

Сообщение с вложенным документом #

Для отправки 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

string

required

Тип контента (document)

documentUrl

string

required

Ссылка на отправляемый в сообщении документ

documentName

string

required

Наименование документа

Совет

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

Сообщение с аудиофайлом #

Для отправки 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

string

required

Тип контента (audio)

audioUrl

string

required

ссылка на отправляемый в сообщении аудиофайл

Совет

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

Сообщение с видеофайлом #

Для отправки 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

string

required

Тип контента (video)

videoUrl

string

required

Ссылка на отправляемый в сообщении видеофайл

videoName

string required

Наименование видеофайла

Совет

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

Сообщение с кнопкой-ссылкой и номером телефона #

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

Совет

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

Сообщение с интерактивным списком #

Для отправки 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	string required	Тип контента (`list_picker`)
button	string required	Наименование кнопки для интерактивного списка.
sections	string required	Массив, содержащий информацию о кнопках в списке
title	string required	Заголовок секции с элементами, который отображается пользователю.
items	string required	Список объектов item, объект содержит поля: `title` – string (required) – название элемента `subtitle` – string (required) – подзаголовок элемента `identifier` – string (required) – сквозной для всего сообщения ID элемента, вернется в ответном сообщении пользователя.

Совет

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

Сообщение с кнопкой с текстом #

Для отправки 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	string required	Тип контента (`text`)
buttons	string required	Массив параметров, передаваемых с кнопками
text	string required	Наименование, отображаемое на кнопке. Максимальный размер - 20 символов.
payload	string required	Скрытый текст, который будет передан во входящем сообщении, если пользователь нажмет на кнопку, максимальное количество символов - 128.

Совет

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

Сообщение с контентом в заголовке #

Для отправки 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	string required	Тип контента (`text`)
header	string optional	Массив параметров, передаваемых в заголовке сообщения.
text	string optional	Текст заголовка. Максимальная длина - 60 символов.
imageUrl	string optional	Ссылка на изображение в заголовке.
documentUrl	string optional	Ссылка на документ в заголовке.
string optional	string optional	Наименование документа в заголовке.
footer	string optional	Массив параметров, передаваемых в подписи.
text	string optional	Текст подписи. Максимальная длина - 60 символов.

Совет

отправлять одновременно в заголовке текст, изображение и документ не допускается;
рекомендовано использовать изображение размером не меньше 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 символов.