WHATSAPP¶

Отправка¶

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

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

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

Параметр

Тип данных

Описание

messages

array[Message]

Массив сообщений содержащий заполненные объекты сообщений с параметрами каждого сообщения.

Внимание! Рекомендуется в одном запросе передавать не более 100 объектов. Оптимальным вариантом будет от 10 до 50

Message¶

Набор доступных параметров для одного сообщения.

Внимание

Для отправки шаблонных сообщений параметры templateId и languageCode являются обязательными. Шаблонные сообщения как правило формируют новое диалоговое окно. Если сообщение отправляется в рамках уже открытого диалога, то параметры templateId и languageCode уже не являются обязательным условием.
Диалог начинается либо с исходящего шаблонного сообщения, либо с входящего от абонента.

Параметр	Тип данных	Описание
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	Информация о контакте.

MIME Type¶

Медиа	Поддерживаемый тип контента	Расширения файлов	Ограничения размера	Комментарий
`audio`	`audio/acc` `audio/mp4` `audio/amr` `audio/mpeg`	`.acc` `.mp4` `.mp4a` `.amr` `.mpeg`	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. Поддерживаются только видео с одним аудиопотоком или без такового.

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` - кнопка со ссылкой.

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

Примеры запросов¶

Шаблонное

"messages": [
  { 
    "from":"MyCompany",
    "to":"79034567888",
    "templateId": "account_activated",
    "languageCode": "ru"
  },
  { 
    "from":"MyCompany",
    "to":"79034567889",
    "templateId": "account_activated",
    "languageCode": "ru"
  }
]

Шаблонное с параметрами

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

Свободное(диалог)

"messages": [
  { 
    "from":"MyCompany",
    "to":"79034567888",
    "text": "Hello",
  },
  { 
    "from":"MyCompany",
    "to":"79034567889",
    "text": "Hello too",
  }
]

Свободное(изображение)

"messages": [
  { 
    "from":"MyCompany",
    "to":"79034567888",
    "contentUrl": "https://cdn.imagestorage.com/a/b/c/123/some_image_abcd123.jpg",
    "contentName": "Some_image_test",
    "contentType": "image/jpeg"
  },
  { 
    "from":"MyCompany",
    "to":"79034567889",
    "contentUrl": "https://cdn.imagestorage.com/a/b/c/123/some_image_abcd123.jpg",
    "contentName": "Some_image_test",
    "contentType": "image/jpeg"
  }
]

Параметры ответа `200 OK`¶

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

result

array[MessageResult]

Содержит массив с результатами обработки сообщений.

Для сообщений с ошибкой REJECTED параметр messageId не возвращается (возвращается "null") т.к. он не создается на этапе первичной синхронной обработки.

MessageResult¶

Параметр	Тип данных	Описание
code	string	Указывает на результат обработки сообщения. 1. `OK` - успешно обработано. 2. `REJECTED` - произошла ошибка во время обработки запроса.
messageId	string	ID сообщения. Указывается только при `"code": "OK"`. В остальных случаях `"null"`
reasons	array[RejectReason]	Массив ошибок, произошедших во время обработки сообщения. Указывается только при `"code": "REJECTED"`.
description	string	Более детальное описание возникшей ошибки

RejectReason¶

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

Примеры ответов `200 OK`¶

OK

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

REJECTED

{
  "result": [
    {
      "code": "REJECTED",
      "messageId": "null",
      "reasons": [
        {
          "key": "from.not.available",
          "ref": "from"
        }
      ],
      "description": "Invalid 'sourceAddress'"
    }
  ]
}

Параметры ответа `400 Bad Request`¶

Если процессинг не доходит до стадии обработки сообщений, то результат с ошибкой будет иметь другой формат.

Параметр	Тип данных	Описание
result	null	Всегда содержит нулевое значение т.к. не содержит результатов обработки сообщений.
reasons	array[RejectReason]	Массив ошибок, возникших при запросе .
description	string	Более детальное описание возникшей ошибки.

RejectReason¶

Параметр	Тип данных	Описание
key	string	Код ошибки.
ref	string	Указывает на объект, в котором произошла ошибка.

Пример ответа `400 Bad Request`¶

{
  "result": null,
  "reasons": [
    {
      "key": "channel.not.active.for.user",
      "ref": "WHATSAPP"
    }
  ],
  "description": "Ошибка канала отправки: null"
}

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

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

Для получения входящих 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"
    }
]

WHATSAPP¶

Отправка¶

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

Message¶

MIME Type¶

TemplateButtonParamList¶

Contact¶

ContactName¶

ContactAddress¶

ContactEmail¶

ContactCompany¶

ContactPhone¶

ContactUrl¶

Примеры запросов¶

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

MessageResult¶

RejectReason¶

Коды ошибок¶

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

Параметры ответа 400 Bad Request¶

RejectReason¶

Пример ответа 400 Bad Request¶

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

Параметры¶

Пример¶

Коллбэки¶

Возможные статусы¶

Пример коллбэка¶

Параметры ответа `200 OK`¶

Примеры ответов `200 OK`¶

Параметры ответа `400 Bad Request`¶

Пример ответа `400 Bad Request`¶