Direct WA API¶
Отправка¶
Для отправки WhatsApp-сообщения необходимо:
- Согласовать имя отправителя в личном кабинете.
- Вызвать методы, передавая в теле параметры сообщения с указанием данных авторизации в заголовке:
- POST /whatsapp/v2/messages для одного сообщения.
- POST /whatsapp/v2/messages/batch для нескольких сообщений.
Параметры запроса¶
Внимание
Поддерживаются сообщения следующих типов: текст, изображения, документы, аудио, видео, шаблоны сообщений, местоположение, список контактов, интерактивные сообщения.
Параметр | Тип данных | Описание |
---|---|---|
from | string | Согласованное имя отправителя. |
to | string | Номер телефона в международном формате, согласно стандарту E.164. |
recipient_type (optional) |
string | Тип получателя, которому отправляется сообщение. Поддерживаемое значение: |
callbackUrl (optional) |
string | URL, на который система будет отправлять коллбэки при изменении статуса сообщения. Любой валидный URL со схемой |
callbackData (optional) |
string | Данные, которые будут указаны в коллбэке со статусом сообщения. Любой массив вида |
preview_url (optional) |
boolean | Предварительный просмотр URL-адресов. По умолчанию false . |
type (optional) |
string | Тип сообщения. Возможные значения: |
text (optional) |
Text | Обязателен для сообщений с типом text .Содержит объект Text. |
audio (optional) |
Media | Обязателен для сообщений с типом audio .Объект Media содержит аудио. |
document (optional) |
Media | Обязателен для сообщений с типом document .Объект Media содержит документ. |
image (optional) |
Media | Обязателен для сообщения с типом image .Объект Media содержит изображение. |
video (optional) |
Media | Обязателен для сообщений с типом video .Объект Media содержит видео. |
sticker (optional) |
Media | Обязателен для сообщений с типом sticker .Объект Media содержит стикер. |
contacts (optional) |
array[object] | Список контактов, отправленных пользователю. Обязателен для сообщений с типом contacts .В Contact можно включить следующие объекты: |
template (optional) |
Template | Используется только для сообщений с шаблоном. Содержит объект Template. |
location (optional) |
Location | Обязателен для сообщений с типом location .Содержит объект Location. |
interactive (optional) |
Interactive | Обязателен для сообщений с типом interactive .Содержит объект Interactive. |
Примеры запросов¶
{
"from": "MySourceAddress",
"to": "PhoneNumber",
"type": "template",
"template": {
"name": "template_name",
"language": {
"code": "ru",
"policy": "deterministic"
}
}
}
{
"messages": [
{
"from": "MySourceAddress",
"to": "PhoneNumber",
"text": "your_message_content",
"callbackUrl": "http://the_url"
},
{
"from": "MySourceAddress",
"to": "PhoneNumber",
"text": "your_message_content",
"callbackUrl": "http://the_url"
}
]
}
Text¶
Параметр | Тип данных | Описание |
---|---|---|
body | string | Содержит текст сообщения. Может содержать несколько URL и форматирование. Максимальная длина текстового сообщения — 4 096 символов. |
Пример сообщения¶
{
"from": "MySourceAddress",
"to": "PhoneNumber",
"type": "text",
"text": {
"body": "your_message_content"
}
}
Media¶
Примечание
Тело действительного запроса может содержать только один объект Media
.
Параметр | Тип данных | Описание |
---|---|---|
link | string | Протокол и URL отправляемого медиафайла. Используется только для URL с префиксом HTTP или HTTPS . Не используется с сообщением типа text . |
id | string | ID медиафайла. Необходим, если вы не используете параметр link . |
caption (optional) |
string | Название медиафайла. Используется для медиафайлов типа image или video .Не используется для файлов audio , sticker и document . |
filename (optional) |
string | Название файла, соответствующее выбранному документу. Используется только для медиафайлов типа document .Длина от 1 до 100. |
MIME Type¶
Медиа | Поддерживаемый тип контента |
Расширения файлов | Ограничения размера | Комментарий |
---|---|---|---|---|
audio |
audio/acc audio/mp4 audio/amr audio/mpeg audio/ogg |
.acc .mp4 .mp4a .amr .mpeg .ogg |
16Mb | codecs=opus |
voice |
audio/ogg |
.ogg |
16 Mb | Записанное на устройстве аудио.
|
document |
любой валидный MIME Type | 100 Mb | ||
image |
image/jpeg image/png |
.jpeg .jpg .png |
5 Mb | GIF-изображения будут автоматически преобразованы в MP4-видео на стороне WhatsApp. Изображения с прозрачным фоном не поддерживаются. |
video |
video/mp4 video/3gpp |
.mp4 .3gp .3g2 |
16 Mb | Поддерживаются только видеокодек H.264 и аудиокодек AAC. Поддерживаются только видео с одним аудиопотоком или без такового. |
Примеры сообщений¶
{
"from": "MySourceAddress",
"to": "PhoneNumber",
"type": "audio",
"audio": {
"link": "http(s)://the_url"
}
}
{
"from": "MySourceAddress",
"to": "PhoneNumber",
"type": "video",
"video": {
"link": "http(s)://the_url",
"caption": "your_video-name"
}
}
{
"from": "MySourceAddress",
"to": "PhoneNumber",
"type": "document",
"document": {
"link": "http(s)://the_url",
"filename": "your_document_filename"
}
}
Contact¶
Информация
Может принимать несколько контактов.
Параметр | Тип данных | Описание |
---|---|---|
name | object | Полное имя контакта (объект ContactName). |
addresses (optional) |
array[object] | Полные адреса контакта (объект ContactAddress). |
birthday (optional) |
string | Строка в формате YYYY-MM-DD . |
emails (optional) |
array[object] | Email-адреса контакта (объект ContactEmail). |
org (optional) |
object | Сведения об организации контакта (объект ContactCompany). |
phones (optional) |
array[object] | Номер телефона контакта (объект ContactPhone). |
urls (optional) |
array[object] | URL контакта (объект ContactUrl). |
ContactName¶
Примечание
С параметром formatted_name
необходимо указать хотя бы один из необязательных параметров.
Параметр | Тип данных | Описание |
---|---|---|
formatted_name | string | Полное имя в стандартном написании. |
first_name (optional) |
string | Имя. |
last_name (optional) |
string | Фамилия. |
middle_name (optional) |
string | Второе имя или отчество. |
suffix (optional) |
string | Суффикс имени. |
prefix (optional) |
string | Префикс имени. |
ContactAddress¶
Параметр | Тип данных | Описание |
---|---|---|
street (optional) |
string | Улица и номер дома. |
city (optional) |
string | Название города. |
state (optional) |
string | Сокращенное название федерального округа. |
zip (optional) |
string | Почтовый индекс. |
country (optional) |
string | Полное название страны. |
country_code (optional) |
string | Двухбуквенный код страны. |
type (optional) |
string | Стандартные значения: HOME , WORK . |
ContactEmail¶
Параметр | Тип данных | Описание |
---|---|---|
email (optional) |
string | Email-адрес. |
type (optional) |
string | Стандартные значения: HOME , WORK . |
ContactCompany¶
Параметр | Тип данных | Описание |
---|---|---|
company (optional) |
string | Название компании. |
department (optional) |
string | Название отдела. |
title (optional) |
string | Должность в компании. |
ContactPhone¶
Параметр | Тип данных | Описание |
---|---|---|
phone (optional) |
string | Автоматически подставляется значение wa_id в виде отформатированного номера телефона. |
type (optional) |
string | Стандартные значения:CELL , MAIN , IPHONE , HOME , WORK . |
wa_id (optional) |
string | ID в WhatsApp. |
ContactUrl¶
Параметр | Тип данных | Описание |
---|---|---|
url (optional) |
string | URL контакта. |
type (optional) |
string | Стандартные значения: HOME , WORK . |
Пример сообщения¶
{
"from": "MySourceAddress",
"to": "PhoneNumber",
"type": "contacts",
"contacts": [
{
"name": {
"formatted_name": "formatted_name 1",
"first_name": "contact_first_name",
"last_name": "contact_last_name"
},
"emails": [
{
"email": "email@example.com",
"type": "WORK"
}
]
},
{
"name": {
"formatted_name": "formatted_name 2",
"first_name": "contact_first_name",
"last_name": "contact_last_name"
},
"phones": [
{
"phone": "+74956460054",
"type": "WORK"
}
]
}
]
}
Template¶
Параметр | Тип данных | Описание |
---|---|---|
name | string | Название шаблона. |
namespace | string | Пространство имен для шаблона. |
language | object | Объект TemplateLanguage задает язык, на котором может отображаться шаблон. Для шаблонов сообщений с медиафайлами применяется только языковая политика deterministic . |
components (optional) |
array[object] | Массив объектов TemplateComponent, содержащий параметры сообщения. |
TemplateLanguage¶
Параметр | Тип данных | Описание |
---|---|---|
policy | string | Языковая политика, которой должно соответствовать сообщение. Значение по умолчанию: deterministic . |
code (optional) |
string | Код используемого языка или региона. Может задаваться в формате language или language_locale (т.е. en или en_US ). |
TemplateComponent¶
Параметр | Тип данных | Описание |
---|---|---|
type | string | Описывает тип component .Значения: header , body , footer , button . |
parameters (optional) |
array[object] | Массив объектов TemplateComponentParameter, содержащий контент сообщения. |
sub_type (optional) |
string | Тип создаваемой кнопки. Значения: quick_reply , url .Обязательный параметр для типа button . |
index (optional) |
string | Индекс положения кнопки. Можно создать до трех кнопок с индексами 0-2 .Обязательный параметр для типа button . |
TemplateComponentParameter¶
Параметр | Тип данных | Описание |
---|---|---|
type | string | Значения для типа: ○ header : text , image , video , document .○ body : text , currency , date_time .○ footer : text .○ button : text , payload . |
payload (optional) |
string | Заданные разработчиком полезные данные, которые возвращаются при нажатии кнопки с текстом. Обязательно для кнопок quick_reply . |
text (optional) |
string | Для header не более 60 символов с поддержкой переменных.Для body не более 1024 символов с поддержкой эмоджи и переменных.Для footer не более 60 символов.Для button c "sub_type": "url" обязателен предоставленный разработчиком суффикс. Этот суффикс добавляется к заданному URL кнопки. Не более 20 символов. |
document (optional) |
object | Объект Media, содержащий документ. |
image (optional) |
object | Объект Media, содержащий изображение. |
video (optional) |
object | Объект Media, содержащий видео. |
currency (optional) |
object | Объект Currency, содержащий информацию о валюте. |
Currency¶
Параметр | Тип данных | Описание |
---|---|---|
fallback_value | string | Текст, который отображается в случае ошибки локализации сообщения. |
amount_1000 (optional) |
integer | Количество валюты, умноженное на 1000. |
code (optional) |
string | Код валюты по ISO 4217. |
Информация
В шаблон можно добавлять переменные. Переменные позволяют добавить уникальную информацию - например, имя клиента, адрес, номер заказа и т.д. Нумерация переменных начинается с единицы и продолжается по возрастанию.
Ваш заказ
{{1}}
на общую сумму{{2}}
подтвержден.
Где {{1}}
и {{2}}
- это переменные: 119833 и 2900.
Ваш заказ 119833 на общую сумму 2900 подтвержден.
Примеры сообщений¶
Кнопка содержит ссылку с переменной частью:
{
"from": "MySourceAddress",
"to": "PhoneNumber",
"type": "template",
"template": {
"name": "template_name",
"language": {
"policy": "deterministic",
"code": "ru"
},
"components": [
{
"type": "button",
"sub_type": "url",
"index": "0",
"parameters": [
{
"type": "text",
"text": "/start"
}
]
}
]
}
}
{
"from": "MySourceAddress",
"to": "PhoneNumber",
"type": "template",
"template": {
"name": "template_name",
"language": {
"policy": "deterministic",
"code": "ru"
},
"components": [
{
"type": "currency",
"currency" : {
"fallback_value": "$230.99",
"code": "USD",
"amount_1000": 230990
}
}
]
}
}
Шаблонное сообщение с документами в header
, переменными в body
, текстом в footer
и двумя кнопками:
{
"from": "MySourceAddress",
"to": "PhoneNumber",
"type": "template",
"template": {
"name": "template_name",
"language": {
"code": "ru",
"policy": "deterministic"
},
"components": [
{
"type": "header",
"parameters": [
{
"type": "document",
"document": {
"link": "http(s)://the_url",
"filename": "document_name"
}
}
]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "119833"
},
{
"type": "text",
"text": "2900"
},
{
"type": "currency",
"currency": {
"fallback_value": "$100.99",
"code": "USD",
"amount_1000": 100990
}
},
{
"type": "date_time",
"date_time": {
"fallback_value": "February 25, 1977",
"day_of_week": 5,
"day_of_month": 25,
"year": 1977,
"month": 2,
"hour": 15,
"minute": 33,
"timestamp": 1485470276
}
}
]
},
{
"type": "footer",
"parameters": [
{
"type": "text",
"text": "text 1"
}
]
},
{
"type": "button",
"sub_type": "quick_reply",
"index": 0,
"parameters": [
{
"type": "payload",
"payload": "Start"
}
]
},
{
"type": "button",
"sub_type": "quick_reply",
"index": 1,
"parameters": [
{
"type": "payload",
"payload": "End"
}
]
}
]
}
}
Location¶
Параметр | Тип данных | Описание |
---|---|---|
longitude | double | Географическая долгота точки. Минимальное значение: -180 Максимальное значение: 180 |
latitude | double | Географическая широта точки. Минимальное значение: -90 Максимальное значение: 90 |
name (optional) |
string | Название локации. |
address (optional) |
string | Адрес локации. Отображается, если указан параметр name . |
Пример сообщения¶
{
"from": "MySourceAddress",
"to": "PhoneNumber",
"type": "location",
"location": {
"latitude": 74.1182263536133,
"longitude": 69.9107435105422,
"address": "location_address",
"name": "location_name"
}
}
Interactive¶
Параметр | Тип данных | Описание |
---|---|---|
type | string | Значения: ○ list - для сообщений-списков.○ button - для кнопок ответа. |
header (optional) |
object | Содержимое заголовка, отображаемое вверху сообщения (объект InteractiveHeader). |
body | object | Тело сообщения (объект InteractiveBody). |
footer (optional) |
object | Нижний колонтитул сообщения (объект InteractiveFooter). |
action | object | Действие, которое пользователь должен выполнить, прочитав сообщение (объект InteractiveAction). |
InteractiveHeader¶
Параметр | Тип данных | Описание |
---|---|---|
type | string | Тип заголовка. Значения: ○ text - для сообщений-списков и кнопок ответа.○ video , image , document - для кнопок ответа. |
text (optional) |
string | Текст заголовка. Обязательный параметр, если "type": "text" .Максимальная длина 60 символов с поддержкой эмоджи. |
video (optional) |
object | Обязательный параметр для типа video . Содержит объект Media. |
image (optional) |
object | Обязательный параметр для типа image . Содержит объект Media. |
document (optional) |
object | Обязательный параметр для типа document . Содержит объект Media. |
InteractiveBody¶
Параметр | Тип данных | Описание |
---|---|---|
text | string | Текст сообщения. Поддерживаются эмоджи, переменные и ссылки. Максимальная длина 1024 символа. |
InteractiveFooter¶
Параметр | Тип данных | Описание |
---|---|---|
text | string | Содержимое нижнего колонтитула. Поддерживаются эмоджи, переменные и ссылки. Максимальная длина 60 символов. |
InteractiveAction¶
Параметр | Тип данных | Описание |
---|---|---|
button (optional) |
string | Содержимое кнопки. Обязателен для типа list .Это значение не может быть пустой строкой и должно быть уникальным в сообщении. Эмоджи и переменные не поддерживаются. Максимальная длина 20 символов. |
buttons (optional) |
array[object] | Массив объектов InteractiveActionButton. Обязателен для типа button .Может содержать в себе максимум 3 объекта. |
sections (optional) |
array[object] | Массив объектов InteractiveActionSection. Обязателен для типа list .Может содержать в себе максимум 10 объектов. |
InteractiveActionButton¶
Параметр | Тип данных | Описание |
---|---|---|
type | string | Значение: reply . |
reply | object | Объект reply содержит в себе: ○ title (string) - название кнопки. Это значение не может быть пустой строкой и должно быть уникальным в сообщении. Эмоджи и переменные не поддерживаются. Максимальная длина 20 символов.○ id (string) - уникальный ID кнопки. Этот ID возвращается в объекте Webhook, когда пользователь нажимает кнопку. Максимальная длина 256 символов. |
InteractiveActionSection¶
Параметр | Тип данных | Описание |
---|---|---|
title (optional) |
string | Заголовок раздела. Обязательный параметр, если сообщение содержит более одного объекта section .Максимальная длина 24 символа. |
rows (optional) |
array[object] | Содержит список строк InteractiveActionSectionRow. Обязательный параметр, если для параметра type задано значение list . |
InteractiveActionSectionRow¶
Параметр | Тип данных | Описание |
---|---|---|
title | string | Заголовок раздела. Максимальная длина 24 символа. |
id | string | ID. Максимальная длина 200 символов. |
description (optional) |
string | Уникальный ID строки. Максимальная длина 72 символа. |
Пример сообщения¶
{
"from": "MySourceAddress",
"to": "PhoneNumber",
"type": "interactive",
"interactive": {
"type": "list",
"header": {
"type": "text",
"text": "your_header_content"
},
"body": {
"text": "your_text_message_content"
},
"footer": {
"text": "your_footer_content"
},
"action": {
"button": "button_content",
"sections": [
{
"title": "your_section_title_content",
"rows": [
{
"id": "unique_row_identifier",
"title": "row_title_content",
"description": "row_description_content"
}
]
},
{
"title": "your_section_title_content",
"rows": [
{
"id": "unique_row_identifier",
"title": "row_title_content",
"description": "row_description_content"
}
]
}
]
}
}
}
{
"from": "MySourceAddress",
"to": "PhoneNumber",
"type": "interactive",
"interactive": {
"type": "button",
"body": {
"text": "your_text_body_content"
},
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"id": "unique_postback_id",
"title": "First Button’s Title"
}
},
{
"type": "reply",
"reply": {
"id": "unique_postback_id",
"title": "Second Button’s Title"
}
}
]
}
}
}
Параметры ответа¶
Параметр | Тип данных | Описание |
---|---|---|
code | string | Указывает на результат обработки сообщения. 1. |
messageId | string | ID сообщения. Указывается только при "code": "OK" . |
reasons | array | Массив ошибок, произошедших во время обработки сообщения. Указывается только при "code": "REJECTED" . |
reasons.key | string | Код ошибки. |
reasons.ref | string | Ссылка на параметр, в котором произошла ошибка. |
Коды ошибок¶
Код | Параметр | Описание |
---|---|---|
invalid | messages[i].to | Неправильно указан номер телефона. |
invalid | messages[i].callbackUrl | URL не соответствует формату HTTP или HTTPS . |
invalid | messages[i].templateButtonParams | Параметр text не может быть пустым. |
invalid | messages[i].templateButtonParams | Параметр payload не может быть пустым. |
invalid | messages[i].languageCode | Неправильно указан код языка. |
not.supported | messages[i].media.filename | Название файла не поддерживается для данного типа медиа. |
unsupported | messages[i].sticker.caption | Описание стикера не поддерживается. |
must.be.not.null | messages[i].audio | Для типа сообщения audio объект audio не может быть пустым. |
must.be.not.null | messages[i].contacts | Для типа сообщения contacts объект contacts не может быть пустым. |
must.be.not.null | messages[i].document | Для типа сообщения document объект document не может быть пустым. |
must.be.not.null | messages[i].template | Для типа сообщения template объект template не может быть пустым. |
must.be.not.null | messages[i].image | Для типа сообщения image объект image не может быть пустым. |
must.be.not.null | messages[i].location | Для типа сообщения location объект location не может быть пустым. |
must.be.not.null | messages[i].text | Для типа сообщения text объект text не может быть пустым. |
must.be.not.null | messages[i].video | Для типа сообщения video объект video не может быть пустым. |
must.be.not.null | messages[i].sticker | Для типа сообщения sticker объект sticker не может быть пустым. |
Пример ответа¶
{
"result": [
{
"code": "OK",
"messageId": "3482512350952730368"
}
]
}
{
"result": {
"code":"REJECTED",
"messageId":null,
"reasons": [
{
"key":"invalid.to",
"ref":"to"
}
]
}
}
Входящие сообщения¶
Как подключить
Для получения входящих WhatsApp-сообщений от пользователей обратитесь к менеджеру компании или в техническую поддержку. Также будет необходимо сообщить URL веб-сервера для обработки входящих сообщений.
Параметры¶
Параметр | Тип данных | Описание |
---|---|---|
incomingMessageId | integer | ID входящего сообщения. |
to | string | Название аккаунта получателя. |
from | string | Номер телефона отправителя. |
text | string | Текст сообщения. |
profileName | string | Название аккаунта отправителя. |
ts | integer | Время получения сообщения (timestamp) в миллисекундах. |
Пример¶
{
"incomingMessageId": 2834738753045023457,
"to": "BusinessProfile",
"from": "799900000000",
"text": "Hello!",
"profileName": "UserName",
"ts": 1670844823000
}
Коллбэки¶
Как подключить
Для настройки коллбэков со статусами сообщений необходимо обратиться к менеджеру компании или в техническую поддержку.
Возможные статусы¶
Код | Описание |
---|---|
SENT | Сообщение отправлено. |
EXPIRED | Истек срок жизни сообщения. |
DELIVERED | Сообщение доставлено получателю. |
SEEN | Сообщение просмотрено получателем. |
REJECTED | Сообщение отклонено оператором, либо превышен лимит отправки сообщений. |
UNDELIVERABLE | Сообщение отклонено оператором, либо отсутствует шаблон сообщения. |
Пример коллбэка¶
[
{
"messageId": 1,
"ts": 1636976602504,
"status": "DELIVERED",
"errorCode": 0,
"callbackData": "string"
}
]