Отправка сообщений (imOutMessage)

Метод, описанный в этой статье, предназначен только для 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"
}

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

ПараметрТип данныхОписание
idstringИдентификатор сообщения. Генерируется вашей системой, после чего значение должно быть передано в запрос. Допускается любая длинна строки до 36 символов
subjectstringТекст подписи в сообщении. 

Важно! Все подписи необходимо предварительно зарегистрировать в платформе. Иначе, сообщение не будет доставлено
addressstringНомер абонента, на который будет отправлено сообщение в формате 79ХХХХХХХХХХ
prioritystring (optional)Приоритет сообщения, влияет на время доставки сообщения. Возможные значения:

realtime — сообщение должно быть доставлено немедленно
high — сообщение с высоким приоритетом
normal — сообщение со стандартным приоритетом
low — сообщение с низким приоритетом
startTimestring (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)
validityPeriodSecondsint (optional)Время (в секундах), в течении которого должно быть доставлено сообщение. Если сообщение не может быть доставлено в течение этого времени (например, абонент не доступен), значит оно не будет доставлено вовсе. Значение по умолчанию — 1 сутки. Минимальное значение 30, максимальное 86400. Рекомендуется использовать 86400, так как мессенджер округляет значение до полных суток
imTypestringОпределяет канал взаимодействия, который используется для доставки сообщения:

whatsapp — WhatsApp (опциональный параметр)
viber — Viber Service Messages

Важно! Обязательный параметр!
contentTypestringТип содержимого сообщения. Возможные значения:

text — текстовое сообщение
image — изображение
document — документ, вложенный в сообщение
video — сообщение, содержащее видео
audio — сообщение, содержащее звук
location — сообщение с координатами, адресом и описанием места. Координаты преобразуются в снимок Google maps
textstringТекст сообщения. Требуется, если тип сообщения text.
attachmentNamestring (optional)Название прикрепленного изображения/окумента/видео (для аудио нельзя). 

Важно! Имя вложения не может превышать 25 символов для месенджера Viber. Для все остальных допускается не более 75 символов
attachmentUrlstring (optional)URL прикрепленного изображения/документа/видео. Обязательный параметр, если для параметра contentType указано одно из значений, отличных от text

Важно! URL должен начинаться с https.
latitudestring (optional)Долгота геолокации. Обязательно если contentType='location'
longitudestring (optional)Широта геолокации. Обязательно если contentType='location'
locationAddressstring (optional)Адрес геолокации. Используется только при contentType='location'
captionstring (optional)Название геолокации. Используется только при contentType='location'
commentstring (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"
}

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

ПараметрТип данныхОписание
idstringИдентификатор сообщения. Это номер был сгенерирован на вашей стороне
codestringКод ответа для данного сообщения. Возможные значения

Типы вложений

Все отправляемые вложения должны удовлетворять нижеперечисленным требованиям. Иначе сообщение не будет доставлено.

Поддерживаемые типы медиавложений WhatsApp

Тип вложенияПоддерживаемый форматРазмер, МВ
documentЛюбой корректный MIME тип100
imageimage/jpeg, image/png5
audioaudio/aac, audio/mp4, audio/amr, audio/mpeg, audio/ogg; Кодек=opus (NWB) и ACC16
videovideo/mp4, video/3gpp 

Внимание: Поддерживается только формат MPEG 4 и 3GPP c кодеком H.264 (MPEG-4 Part 10) и AAC для аудио
16

Поддерживаемые типы медиавложений Viber Service Messages

Тип вложенияПоддерживаемый формат Размер, МВ
documentЛюбой корректный MIME тип100
imageimage/jpeg, image/png5
Название прикрепленного файла (attachmentName) не может превышать 25 символов для месенджера Viber. Для все остальных допускается не более 75 символов.

Примеры запросов по типам вложений

  • Пример тела запроса с типом вложения «изображение»:

WhatsApp

{
    "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:

WhatsApp

{
    "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"
        }
}

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

ПараметрТип данныхОписание
subjectstringТекст подписи в SMS-сообщения. 

Важно! Все подписи необходимо предварительно зарегистрировать в платформе. Иначе, сообщение не будет доставлено.
prioritystring (optional)Приоритет сообщения, влияет на время доставки сообщения. Возможные значения:

realtime — сообщение должно быть доставлено немедленно
high — сообщение с высоким приоритетом
normal — сообщение со стандартным приоритетом
low — сообщение с низким приоритетом
contentTypestringТип содержимого сообщения. Возможные значения:

text — текстовое сообщение
image — изображение
document — документ, вложенный в сообщение
video — сообщение, содержащее видео
contentstringТекст сообщения. Требуется, если тип сообщения text.
sendTimeoutSecondsint (optional)Если в течении этого времени, сообщение не будет доставлено в мессенджер, то произойдет отправка SMS-сообщения
validityPeriodSecondsint (optional)Время (в секундах), в течении которого должно быть доставлено SMS-сообщение. Если сообщение не может быть доставлено в течение этого времени (например, абонент не доступен), значит оно не будет доставлено вовсе
commentstring (optional)Текстовый комментарий в сообщении. Значение параметра отображается в детальном отчете.

Введение
Cледующая статья Получение статуса доставки сообщения (imOutMessageId)