WHATSAPP¶

Отправка¶

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

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

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

Параметр	Тип данных	Описание
messages	array[Message]	Массив сообщений.

Message¶

Параметр	Тип данных	Описание
from	string	Согласованное имя отправителя.
to	string	Номер телефона в международном формате, согласно стандарту E.164.
text (optional)	string	Текст сообщения. Максимальная длина - 4096 символов.
address (optional)	string	Адрес пользователя.
addressName (optional)	string	Название адреса пользователя.
addressUrl (optional)	string	URL адреса пользователя.
callbackData (optional)	object	Данные, которые будут указаны в коллбэке со статусом сообщения. Любой массив вида `"key"`: `{ "key1": "value1", "key2": "value2" }`
callbackUrl (optional)	string	URL, на который система будет отправлять коллбэки при изменении статуса сообщения. Любой валидный URL со схемой `HTTP` или `HTTPS`.
contentName (optional)	string	Название контента. Не более 100 символов.
contentType (optional)	MIME Type	MIME Type контента. Существующий MIME Type.
contentUrl (optional)	string	URL контента. Любой валидный URL со схемой `HTTP` или `HTTPS`.
languageCode (optional)	string	Код языка. По умолчанию `en`.
latitude (optional)	number	Широта.
longitude (optional)	number	Долгота.
templateButtonParams (optional)	TemplateButtonParamList	Параметры интерактивных кнопок в сообщении.
templateId (optional)	string	ID шаблона в системе поставщика.
templateParams (optional)	object	Набор параметров для заполнения по шаблону, где ключ - номер позиции значения. Пример: `{ "1": "value1", "2": "value2" }` Внимание! В значении нельзя использовать: переносы строки, табуляцию и 4 пробела подряд.
whatsAppContacts (optional)	Contact	Информация о контакте.

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`.

TemplateButtonParamList¶

Внимание

Название объектов в массиве templateButtonParams - это название вашей кнопки, согласованное в шаблоне.

Параметр	Тип данных	Описание
parameters	TemplateButtonParam	Параметры кнопки.
parameters.payload (optional)	string	Текстовое сообщение, которое будет отправлено в чат при нажатии на кнопку. Для кнопок типа `QUICK_REPLY`.
parameters.text (optional)	string	Суффикс, который добавляется к URL кнопки. Для кнопок типа `URL`.
parameters.type	string	Указывается один из типов параметров: `PAYLOAD` или `TEXT`, в зависимости от типа кнопки.
subType	string	Тип кнопки. Возможные значения: ○ `QUICK_REPLY` - кнопка, которая отправляет текстовое сообщение в чат. ○ `URL` - кнопка со ссылкой.

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": "MyCompany",
    "to": "79034567890",
    "text": "Code: 1234"
  },
  {
    "from":"MyCompany",
    "to":"79034567888",
    "templateId": "account_activated",
    "templateParams":{
      "1": "+7(495) 646 00 54",
      "2": "https://devino.online"
    },
    "languageCode": "ru",
    "callbackUrl":"https://test_callback_url.site"
  }     
]

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

Параметр	Тип данных	Описание
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	Неправильно указан код языка.

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

OK

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

REJECTED

{
  "result": {
    "code":"REJECTED",
    "messageId":null,
    "reasons": [
      {
        "key":"invalid.to",
        "ref":"to"
      }
    ]
  }
}

Входящие сообщения¶

Как подключить

Для получения входящих WhatsApp-сообщений от пользователей обратитесь к менеджеру компании или в техническую поддержку. Также будет необходимо сообщить URL веб-сервера для обработки входящих сообщений.

Параметры¶

Параметр	Тип данных	Описание
contacts	array[WhatsAppContact]	Информация о контакте.
messages	array[Message]	Информация о содержании входящего сообщения.
statuses	array[CallbackWhatsAppStatus]	Информация о статусе входящего сообщения.

WhatsAppContact¶

Параметр	Тип данных	Описание
profile	WhatsAppContactProfile	Информация о контакте, указанная в профиле.
profile.name	string	Имя контакта.
wa_id	string	ID контакта в WhatsApp.

Message¶

Параметр	Тип данных	Описание
id	string	ID сообщения.
from	string	Номер телефона отправителя.
audio	WhatsAppMedia	Аудио, прикрепленное к сообщению.
button	WhatsAppButton	Кнопки, прикрепленные к сообщению.
contacts	array[Contact]	Сообщение с массивом контактов.
document	WhatsAppMedia	Документ, прикрепленный к сообщению.
errors	array[WhatsAppErrorsResponse]	Ошибки сообщения.
image	WhatsAppMedia	Изображение, прикрепленное к сообщению.
interactive	WhatsAppInteractiveCallback	Интерактивное сообщение.
location	WhatsAppLocation	Сообщение с геолокацией.
text	WhatsAppText	Текстовое сообщение.
timestamp	string	Время получения сообщения (timestamp) в миллисекундах.
type	string	Тип сообщения. Возможные значения: ○ `audio` - сообщение с аудио. ○ `video` - сообщение с видео. ○ `contacts` - сообщение с контактами. ○ `document` - сообщение с документами. ○ `image` - сообщение с изображением. ○ `location` - сообщение с геолокацией. ○ `sticker` - сообщение-стикер. ○ `voice` - голосовое сообщение. ○ `text` - текстовое сообщение. ○ `unknown` - неизвестный тип сообщения. ○ `ephemeral` - исчезающее сообщение.
video	WhatsAppMedia	Видео, прикрепленное к сообщению.
voice	WhatsAppMedia	Голосовое сообщение.

WhatsAppMedia¶

Параметр	Тип данных	Описание
caption	string	Описание файла.
filename	string	Название файла на устройстве отправителя. Отображается для типа файла `document`.
id	string	ID прикрепленного файла.
mime_type	string	MIME Type файла.
sha256	string	Хэш файла в кодировке SHA-256.

WhatsAppButton¶

Параметр	Тип данных	Описание
payload	string	Текстовое сообщение, которое было отправлено в чат при нажатии на кнопку. Для кнопок типа `quick_reply`.
text	string	Суффикс, который будет подставлен к кнопке-ссылке. Для кнопок типа `url`.

WhatsAppErrorsResponse¶

Параметр	Тип данных	Описание
code	integer	Код ошибки.
details	string	Детали ошибки.
title	string	Название ошибки.

WhatsAppInteractiveCallback¶

Параметр	Тип данных	Описание
type	string	Тип сообщения. Возможные значения: ○ `button_reply` - для сообщений с интерактивными кнопками. ○ `list_reply` - для сообщений с интерактивным списком.
button_reply	Button	Для сообщений с интерактивными кнопками. Содержит данные кнопки, которую выбрал пользователь.
button_reply.description	string	Описание кнопки.
button_reply.id	string	ID кнопки.
button_reply.title	string	Название кнопки.
list_reply	Button	Для сообщений с интерактивным списком. Содержит данные элемента списка, который выбрал пользователь.
list_reply.description	string	Описание элемента списка.
list_reply.id	string	ID элемента списка.
list_reply.title	string	Название элемента списка.

WhatsAppLocation¶

Параметр	Тип данных	Описание
address	string	Адрес локации.
latitude	integer	Широта локации.
longitude	integer	Долгота локации.
name	string	Название локации.

WhatsAppText¶

Параметр	Тип данных	Описание
body	string	Текст сообщения.

CallbackWhatsAppStatus¶

Параметр	Тип данных	Описание
conversation	Conversation	Информация о сессии с пользователем. Сессия в WhatsApp длится 24 часа, и в ней не предусмотрено лимита по количеству сообщениий.
errors	array[WhatsAppErrorsResponse]	Ошибки сообщения.
id	string	ID сообщения со статусом.
pricing	Pricing	Параметры тарификации сообщения.
recipient_id	string	ID получателя сообщения.
status	string	Статус сообщения в Whatsapp. Возможные значения: ○ `deleted` - сообщение удалено. ○ `delivered` - сообщение доставлено. ○ `failed` - ошибка отправки сообщения. ○ `read` - сообщение прочитано. ○ `sent` - сообщение отправлено.
timestamp	integer	Время получения сообщения со статусом (timestamp) в миллисекундах.

Conversation¶

Параметр Тип данных Описание

expiration_timestamp integer Время (timestamp), когда истечет срок жизни сессии, в миллисекундах.

id string ID сессии.

origin.type

string

Тип инициирования сессии.

Возможные значения:
○ business_initiated - сессия начата бизнес-аккаунтом, который отправил сообщение пользователю.
○ user_initiated - бизнес-аккаунт ответил на входящее сообщение пользователя.
○ referral_conversion - пользователь перешел в чат по реферальной ссылке. В этом случае сессия не тарифицируется.

Pricing¶

Параметр Тип данных Описание

billable boolean Тарифицируется ли сессия с пользователем. Если значение параметра origin.type - referral_conversion, значение данного параметра будет false. Во всех остальных случаях true.

category

string

Тип сессии с пользователем для определения тарификации.

Возможные значения:
○ business_initiated - бизнес-аккаунт отправил сообщение пользователю.
○ user_initiated - бизнес-аккаунт ответил на входящее сообщение пользователя.
○ referral_conversion - пользователь перешел в чат по реферальной ссылке. В этом случае сессия не тарифицируется.

pricing_model string Тип тарификации. В данном параметре всегда будет значение CBP, то есть, Conversation-Based Pricing.

Пример¶

"messages": [
  {
    "statuses": [
      {
        "id": "ID",
        "recipient_id": "WHATSAPP_ID",
        "status": "sent",
        "timestamp": 1587721283000,
        "type": "message",
        "conversation": {
          "id": "CONVERSATION_ID",
          "expiration_timestamp": 1587721283000,
          "origin": {
            "type": "business_initiated"
          }
        },
        "pricing": {
          "pricing_model": "CBP",
          "billable": true,
          "category": "business_initiated"
        }
      }
    ]
  }
]

Коллбэки¶

Как подключить

Для настройки коллбэков со статусами сообщений необходимо обратиться к менеджеру компании или в техническую поддержку.

Коды ошибок¶

Код	Описание
WA_MESSAGE_IS_NOT_VALID WA_MESSAGE_IS_EXPIRED	Истек срок жизни сообщения.
WA_RATE_LIMIT_HIT	Превышен лимит отправки сообщений.
WA_SPAM_RATE_LIMIT_HIT	Превышен лимит отправки сообщений, либо одно из отправленных сообщений было помечено пользователем как спам.
WA_INVALID_FILE_FORMAT	Указанный MIME Type не поддерживается.
WA_MESSAGE_TOO_LONG	Превышена максимальная длина сообщения.
WA_USER_IS_NOT_VALID	Сообщение не может быть доставлено, так как пользователя не существует в системе поставщика.
WA_BAD_USER	Данному пользователю нельзя доставить сообщение.
WA_TEMPLATE_PARAM_COUNT_MISMATCH	Количество указанных параметров шаблона не соответствует их ожидаемому количеству.
WA_TEMPLATE_MISSING WA_TEMPLATE_PACK_MISSING	Указанный шаблон не найден.
WA_TEMPLATE_PARAM_LENGTH_TOO_LONG	Превышена длина параметра шаблона.
WA_MESSAGE_WITHOUT_DIALOG_OR_TEMPLATE	Не указан получатель или шаблон.