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
}