Метод, описанный в этой статье, предназначен только для SME.
В результате выполнения запроса будет отправлено сообщение в мессенджер в соответствии с заданными параметрами (в теле запроса). В случае успешного выполнения запроса вернется ответ от сервера с кодом 200, содержащий JSON с идентификатором сообщения и статусом его отправки. В случае неуспешного выполнения запроса возвращается сообщение с кодом ошибки.
URL-адрес подключения
Для отправки сообщения выполняется POST-запрос на URL-адрес: https://im.edna.ru/api/imOutMessage
Формат запроса
В теле запроса передается JSON-объект с параметрами сообщения. Набор параметров зависит от типа сообщения и его содержимого.
WhatsApp позволяет пересылать текст, изображение, документ (файл с вложением), аудио или видео.
Viber Service Messages позволяет пересылать текст и изображение, но не передает аудио- или видеоконтент непосредственно, а только в формате «документ». Viber Service Messages позволяет передавать сочетание текст + изображение + кнопка.
Пример запроса с типом сообщения «текст» (Viber Service Messages):
{ "id": "test-001", "subject": "viber_subject", "address": "+79000000000", "imType": "viber", "contentType": "text", "text": "Hello", "сomment":"this is my comment" }
Параметры запроса
Параметр | Тип данных | Описание |
id | string | Идентификатор сообщения. Генерируется вашей системой, после чего значение должно быть передано в запрос. Допускается любая длинна строки до 36 символов |
subject | string | Текст подписи в сообщении. Важно! Все подписи необходимо предварительно зарегистрировать в платформе. Иначе, сообщение не будет доставлено |
address | string | Номер абонента, на который будет отправлено сообщение в формате 79ХХХХХХХХХХ |
priority | string (optional) | Приоритет сообщения, влияет на время доставки сообщения. Возможные значения: • realtime — сообщение должно быть доставлено немедленно• high — сообщение с высоким приоритетом• normal — сообщение со стандартным приоритетом• low — сообщение с низким приоритетом |
startTime | string (optional) | Время, раньше которого сообщение не будет отправлено. Используется при отложенной отправке. Формат: • YYYY-MM-DDTHH:mm:ss.SSSXXX (2020-06-12T15:30:10.000Z) • YYYY-MM-DDTHH:mm:ss.SSS+TZ (2020-06-12T15:30:10.000+03:00) |
validityPeriodSeconds | int (optional) | Время (в секундах), в течении которого должно быть доставлено сообщение. Если сообщение не может быть доставлено в течение этого времени (например, абонент не доступен), значит оно не будет доставлено вовсе. Значение по умолчанию — 1 сутки. Минимальное значение 30 , максимальное 86400 . Рекомендуется использовать 86400 , так как мессенджер округляет значение до полных суток |
imType | string | Определяет канал взаимодействия, который используется для доставки сообщения: • whatsapp — WhatsApp (опциональный параметр)• viber — Viber Service Messages Важно! Обязательный параметр! |
contentType | string | Тип содержимого сообщения. Возможные значения: • text — текстовое сообщение• image — изображение• document — документ, вложенный в сообщение• video — сообщение, содержащее видео• audio — сообщение, содержащее звук• location — сообщение с координатами, адресом и описанием места. Координаты преобразуются в снимок Google maps |
text | string | Текст сообщения. Требуется, если тип сообщения text . |
attachmentName | string (optional) | Название прикрепленного изображения/окумента/видео (для аудио нельзя). Важно! Имя вложения не может превышать 25 символов для месенджера Viber. Для все остальных допускается не более 75 символов |
attachmentUrl | string (optional) | URL прикрепленного изображения/документа/видео. Обязательный параметр, если для параметра contentType указано одно из значений, отличных от text . Важно! URL должен начинаться с https. |
latitude | string (optional) | Долгота геолокации. Обязательно если contentType='location' |
longitude | string (optional) | Широта геолокации. Обязательно если contentType='location' |
locationAddress | string (optional) | Адрес геолокации. Используется только при contentType='location' |
caption | string (optional) | Название геолокации. Используется только при contentType='location' |
comment | string (optional) | Текстовый комментарий в сообщении. Значение параметра отображается в детальном отчете. |
Требования к оформлению текста
Важно! Необходимо быть внимательным к выделению слов в кавычки. Если вы используете знак двойные кавычки “ или одиночные кавычки ‘ в отправляемом сообщении, то их обязательно нужно отделять знаком \ (слэш).
Правильно:
«text»: «Мария! Ждем вас на Мастер-класс \»Готовим вместе c Tefal\» 25.01.2020 в 13.00. Не пропустите это событие! Наш телефон 8(495)100-80-20″
Неправильный
«text»: «Мария! Ждем вас на Мастер-класс «Готовим вместе с Tefal» 25.01.2020 в 13.00. Не пропустите это событие! Наш телефон 8(495)100-80-20″
Формат ответа
В ответ на запрос возвращается JSON-объект, содержащий Id отправленного сообщения и статус его обработки.
{ "id": "test-001", "code": "ok" }
Параметры ответа
Параметр | Тип данных | Описание |
id | string | Идентификатор сообщения. Это номер был сгенерирован на вашей стороне |
code | string | Код ответа для данного сообщения. Возможные значения |
Типы вложений
Все отправляемые вложения должны удовлетворять нижеперечисленным требованиям. Иначе сообщение не будет доставлено.
Поддерживаемые типы медиавложений WhatsApp
Тип вложения | Поддерживаемый формат | Размер, МВ |
document | Любой корректный MIME тип | 100 |
image | image/jpeg, image/png | 5 |
audio | audio/aac, audio/mp4, audio/amr, audio/mpeg, audio/ogg; Кодек=opus (NWB) и ACC | 16 |
video | video/mp4, video/3gpp Внимание: Поддерживается только формат MPEG 4 и 3GPP c кодеком H.264 (MPEG-4 Part 10) и AAC для аудио | 16 |
Поддерживаемые типы медиавложений Viber Service Messages
Тип вложения | Поддерживаемый формат | Размер, МВ |
document | Любой корректный MIME тип | 100 |
image | image/jpeg, image/png | 5 |
attachmentName
) не может превышать 25 символов для месенджера Viber. Для все остальных допускается не более 75 символов. Примеры запросов по типам вложений
- Пример тела запроса с типом вложения «изображение»:
{ "id": "test-001", "subject": "test", "address": "79000000000", "priority": "high", "startTime": "2020-06-12T15:30:10.000Z", "validityPeriodSeconds": 86400, "contentType": "image", "attachmentName": "image name", "attachmentUrl": "https://picsum.photos/id/1006/200/300" }
Viber Service Messages
{ "id": "test-001", "subject": "viber_subject", "address": "+79000000000", "imType": "viber", "contentType": "button", "text": "Test text", "caption": "button text", "action": "https://edna.io" }
- Пример тела запроса с минимально допустимым набором параметров, текстом, изображением и кнопкой (доступен только для Viber Service Messages):
{ "id": "test-001", "subject": "viber_subject", "address": "+79000000000", "imType": "viber", "contentType": "button", "text": "Test text ", "attachmentUrl": "https://www.gstatic.com/webp/gallery/1.jpg", "caption": "Action here", "action": "https://edna.io" }
- Пример тела запроса с минимально допустимым набором параметров и приложенным докуметом pdf:
{ "id": "test-001", "address": "+79000000000", "subject": "test", "contentType": "document", "attachmentUrl": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf", "attachmentName": "Read this please" }
Viber Service Messages
{ "id": "test-001", "subject": "viber_subject", "address": "+79000000000", "imType": "viber", "contentType": "document", "text": "test button", "attachmentUrl": "https://file-examples-com.github.io/uploads/2017/10/file-sample_150kB.pdf", "caption": "name document" }
- Пример тела запроса с минимально допустимым набором параметров и приложенным изображением jpg (WhatsApp):
{ "id": "test-001", "address": "+79000000000", "subject": "test", "contentType": "image", "attachmentUrl": "https://www.gstatic.com/webp/gallery/1.jpg", "attachmentName": "Read this please" }
- Пример тела запроса с минимально допустимым набором параметров и текстом с кнопкой (Viber Service Messages):
{ "id": "test-001", "subject": "viber_subject", "address": "+79000000000", "imType": "viber", "contentType": "button", "text": "Test text", "caption": "button text", "action": "https://edna.io" }
Резервирование SMS-сообщением отправляемого сообещения
Если сообщение по каким-то причинам не будет доставлено получателю, то имеется функция резервирования доставки SMS-сообщением. Для этого необходимо включить в тело запроса imOutMessage
, помимо значений самого сообщения, параметры SMS-сообщения. Нужно учесть, что подпись SMS-сообщения регистрируется на платформе отдельно.
{ "id": "test-001", "subject": "test", "address": "79000000000", "priority": "high", "startTime": "2020-06-12T15:30:10.000Z", "validityPeriodSeconds": 86400, "contentType": "image", "attachmentName": "Image name", "attachmentUrl": "https://picsum.photos/id/1006/200/300" "reserveSms": { "subject": "subject for sms", "priority": "normal", "contentType": "text", "content": "Sms content", "sendTimeoutSeconds": 600, "validityPeriodMinutes": 120, "comment": "some comment" } }
Параметры запроса
Параметр | Тип данных | Описание |
subject | string | Текст подписи в SMS-сообщения. Важно! Все подписи необходимо предварительно зарегистрировать в платформе. Иначе, сообщение не будет доставлено. |
priority | string (optional) | Приоритет сообщения, влияет на время доставки сообщения. Возможные значения: • realtime — сообщение должно быть доставлено немедленно• high — сообщение с высоким приоритетом• normal — сообщение со стандартным приоритетом• low — сообщение с низким приоритетом |
contentType | string | Тип содержимого сообщения. Возможные значения: • text — текстовое сообщение• image — изображение• document — документ, вложенный в сообщение• video — сообщение, содержащее видео |
content | string | Текст сообщения. Требуется, если тип сообщения text . |
sendTimeoutSeconds | int (optional) | Если в течении этого времени, сообщение не будет доставлено в мессенджер, то произойдет отправка SMS-сообщения |
validityPeriodSeconds | int (optional) | Время (в секундах), в течении которого должно быть доставлено SMS-сообщение. Если сообщение не может быть доставлено в течение этого времени (например, абонент не доступен), значит оно не будет доставлено вовсе |
comment | string (optional) | Текстовый комментарий в сообщении. Значение параметра отображается в детальном отчете. |