Перейти к содержанию

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 не может быть пустым.

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

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