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

WHATSAPP

Отправка

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

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

Параметр Тип данных Описание и Допустимые значения
from string Имя отправителя, используемое при отправке сообщения
Только те имена отправителя, которые доступны для использования у пользователя
to string Номер телефона в международном формате (без "+")
text
(optional)
string Текст сообщения
Не более 1000 UTF-8 символов
validity
(optional)
integer Указывается только в случае отправки сообщения по шаблону. Возможное значние - сутки.
contentUrl
(optional)
string URL на контент
Любой валидный URL со схемой http или https
contentName
(optional)
string Имя контента
Не более 100 символов
contentType
(optional)
string MimeType контента
Существующий Mime Type
callbackUrl
(optional)
string URL, на который система будет отправлять уведомления об изменениях статуса сообщения
Любой валидный URL со схемой http или https
callbackData
(optional)
string Данные, которые будут указаны в обратном вызове со статусом сообщения.
templateId
(optional)
string Идентификатор шаблона в системе поставщика
templateParams
(optional)
object Набор параметров для заполнения по шаблону, где ключ - номер позиции значения.
Например: {"1": "value1","2": "value2" }
Внимание: в значении нельзя использовать: перенос строки, табуляцию и 4 пробела подряд!
languageCode
(optional)
string Код языка, по умолчанию 'EN'

MIMEType

Медиа Поддерживаемые
Content-Type
Расширения файлов Ограничения размера Комментарий
audio audio/acc
audio/mp4
audio/amr
audio/mpeg
audio/ogg
.acc
.mp4
.mp4a
.amr
.mpeg
.ogg
16Mb codecs=opus
document любой валидный MIME-type 100 Mb
image image/jpeg
image/png
.jpeg
.jpg
*.png
16 Mb GIF-изображения автоматически будет преобразован в MP4-видео на стороне WhatsApp
video video/mp4
video/3gpp
.mp4
.3gp
*.3g2
5 Mb Поддерживаются только H.264 и AAC видео-кодеки
voice auidio/ogg .ogg 16 Mb Записанное аудио на устройстве.
codecs=opus

Пример запроса

curl -X POST \
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
 -H 'Content-Type: application/json' \
 -d '{ 
    "messages": [ 
        { 
            "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",
          "validity":86400,
          "callbackUrl":"https://test_callback_url.site"
        }        
    ]
}' https://api.devino.online/whatsapp/messages

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

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

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

Параметр Тип данных Описание и допустимые значения
code string Указывает на результат обработки сообщения.
1. OK - Успешно обработано
2. REJECTED - Произоошла ошибка во время обработки запроса.
reasons
(optional)
Array[String, String] Массив ошибок, произошедших во время обработки сообщения.
Указывается только при code=REJECTED
reasons.key string Код ошибки.
reasons.ref
(optional)
string Ссылка на параметр, в котором произошла ошибка.
messageId
(optional)
string Идентификатор сообщения.
Указывается только при code=OK
description
(optional)
string Описание ошибки.
Указывается только при code=REJECTED

Коды ошибок

Key Ref Описание
billing.error Payment is required
forbidden Отправка запрещена
unknown Unknown error
invalid messages[i].to Неправильно указан номер телефона
invalid messages[i].validity Неправильно указан срок жизни
invalid messages[i].callbackUrl Неправильно указан URL
invalid messages[i].contentUrl Неправильно указан URL контента
invalid messages[i].contentType Неправильно тип контента
invalid messages[i].from Неправильно указан отправитель
invalid messages[i].languageCode Неправильно указан код языка
length.too.long messages[i].to Превышена максимальная длина номера телефона
length.too.long messages[i].text Превышена максимальная длина текста сообщения
length.too.long messages[i].languageCode Слишком длинный код языка
length.too.short messages[i].contentName Слишком короткое имя контента
length.too.short messages[i].languageCode Слишком короткий код языка
must.be.not.null messages[i].to Получатель не указан
must.be.not.null messages Массив messages не может быть пустым
must.be.not.null messages[i].from Отправитель не указан
must.be.not.null messages[i] Поле текста и контента не указано
not.available messages[i].from некорректный адрес отправителя
too.many.messages messages Превышен максимальный размер массива messages

Webhook статусов

Для получения статусов WHATSAPP-сообщений необходимо при отсылке сообщения методом POST /whatsapp/messages указать параметр callbackUrl.

Параметры получения статуса

Параметр Тип данных Описание
messageId long Индификатор сообщения
ts long Timestamp с миллисекундами получения статуса
status string Статус сообщения
errorCode integer Код ошибки
ip string IP адрес
browser string Имя браузера
os string Название операционной системы
userAgent string UserAgent
options string Данные, которые были указаны в callbackData при отправке запроса

Пример получения статуса

[
    {
        "messageId": 1,
        "ts": 0,
        "status": "DELIVERED",
        "errorCode": 0,
        "ip": "127.0.0.1",
        "browser": "string",
        "os": "string",
        "userAgent": "string",
        "options": "string"
    }
]

Коды ошибок

Код Описание
2000 Не определен оператор получателя
2001 Отклонено как спам
2002-2004 Ошибка тарификации
2005 Недостаточно средств
2006-2008 Ошибка тарификации
2009 Отклонено как дубликат
2010, 2011 Исткело время жизни
2012 Ошибка тарификации
2017 Отклонено как спам
2300 Превышен лимит длины текста сообщения
2301 За короткий промежуток времени было отправлено слишком много сообщений. Повторите отправку
2302 Отклонено как спам
2303 Указанный MIME-Type не поддерживается или изображение слишком больше (более или равно 5МБ)
2304 Превышен лимит длины текста сообщения
2305 Пользователь не использовал или более не использует WhatsApp
2307 Возникает при попытке отправить сообщение на номер телефона бизнес-аккаунта, с которого производится отправка
2308 Количество указанных параметров шаблона не соответствует их ожидаемому количеству
2309, 2310 Шаблон не существует для указанного языка или локали
2311 Превышение длины параметра шаблона
2312 Сообщение отправлено вне диалога и без указания шаблона
2313 Неизвестная ошибка

Webhook входящих сообщений

Внимание

Для получения входящих WhatsApp-сообщений необходимо:

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

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

Параметр Тип данных Описание
incomingMessageId long Индификатор сообщения
to string Адрес получателя
from string Адрес отправителя
ts long Timestamp с миллисекундами получения сообщения
text
(optional)
string Текст сообщения
contentUrl
(optional)
string URL на контент в сообщении
contentType
(optional)
string Тип контента в сообщении
contentName
(optional)
string Имя контента в сообщении
profileName
(optional)
string Имя профиля отправителя
whatsAppGeoLocation
(optional)
WhatsAppGeolocation Содержит в себе геопозицию, отправленную пользователем
whatsAppContacts
(optional)
List[WhatsAppContact] Список контактов, отправленных пользователем

WhatsAppGeolocation

Информация

Входящие сообщения с текущими геоданными в настоящее время не поддерживаются.

Параметр Тип данных Описание
latitude double Широта
longitude double Долгота
address string Адрес, по которому находится пользователь
addressName string Название местонахождения пользователя
addressurl string URL, откуда пользователь получил свои геоданные

WhatsAppContact

Информация

Все элемены Массивов имеют тип данных string.

Параметр Тип данных Описание
addresses Массив Полные адреса контакта. Каждый адрес может содержать поля street, city, state, zip, country, countryCode и type.
birthday string День рождения контакта в формате YYYY-MM-DD.
emails Массив Email-адреса. Каждый адрес может содержать email и type.
contactName Массив Полное имя контакта. Каждый объект contactName может содержать поля firstName, middleName, lastName, formattedName, namePrefix и nameSuffix.
contactCompany Массив Информация о месте работы контакта. Каждый объект может содержать поля company, department и title.
phones Массив Номера телефонов контакта. Каждый объект может содержать поля phone, waId и type.
urls Массив URL контакта. Каждый объект может содержать поля url и type.

Пример получения входящего сообщения

{
    "incomingMessageId": 0,
    "to": "str",
    "from": "str",
    "text": "str",
    "contentUrl": "str",
    "contentType": "str",
    "contentName": "str",
    "profileName": "str",
    "ts": 0
}