Direct WA API¶

Отправка¶

Для отправки WhatsApp-сообщения необходимо:

Согласовать имя отправителя в личном кабинете.
Вызвать методы, передавая в теле параметры сообщения с указанием данных авторизации в заголовке:
- POST /whatsapp/v2/messages для одного сообщения.
- POST /whatsapp/v2/messages/batch для нескольких сообщений.

Параметры запроса¶

Внимание

Поддерживаются сообщения следующих типов: текст, изображения, документы, аудио, видео, шаблоны сообщений, местоположение, список контактов, интерактивные сообщения.

Параметр	Тип данных	Описание
from	string	Согласованное имя отправителя.
to	string	Номер телефона в международном формате, согласно стандарту E.164.
recipient_type (optional)	string	Тип получателя, которому отправляется сообщение. Поддерживаемое значение: `individual`.
callbackUrl (optional)	string	URL, на который система будет отправлять коллбэки при изменении статуса сообщения. Любой валидный URL со схемой `HTTP` или `HTTPS`.
callbackData (optional)	string	Данные, которые будут указаны в коллбэке со статусом сообщения. Любой массив вида `"key"`: `{ "key1": "value1", "key2": "value2" }`
preview_url (optional)	boolean	Предварительный просмотр URL-адресов. По умолчанию `false`.
type (optional)	string	Тип сообщения. Возможные значения: ○ `audio` - для сообщений с аудио. ○ `sticker` - для сообщений со стикером. ○ `contacts` - для сообщений с контактами. ○ `document` - для сообщений с документами. ○ `image` - для сообщений с изображениями. ○ `interactive` - для сообщений с кнопками. ○ `location` - для сообщений с геолокацией. ○ `template` - для шаблонных сообщений. ○ `text` - для текстовых сообщений, значение по умолчанию.
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 можно включить следующие объекты: `addresses`, `emails`, `name`, `org`, `phone` и `urls`.
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	Записанное на устройстве аудио. `codecs=opus`
`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. `OK` - успешно обработано. 2. `REJECTED` - произошла ошибка во время обработки запроса.
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` не может быть пустым.

Пример ответа¶

OK

{
  "result": [
    {
      "code": "OK",
      "messageId": "3482512350952730368"
    }    
  ]
}

REJECTED

{
  "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"
    }
]