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
}