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

WHATSAPP

Отправка

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

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

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

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

{
  "result": [
    {
      "code": "OK",
      "messageId": "3482512350952730368"
    }    
  ]
}
{
  "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 Не указан получатель или шаблон.