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

Используйте этот метод для отправки сообщений через каналы мессенджеров (WhatsApp и Viber), SMS и пуш, в том числе, используя каскады, то есть комбинацию каналов.

Вы можете также протестировать отправку сообщений на тестовый номер телефона с помощью API edna для канала WhatsApp, не регистрируя собственный канал. Для этого перейдите на вкладку Тестирование в разделе Интеграция.
Если вы хотите протестировать отправку сообщений, имейте в виду, что у нас действует проверка на дубликаты СМС и IM. В течение 20 минут отправить дубликат сообщения нельзя. Сообщения-дубликаты будут отменены.

Метод schedule

В результате выполнения запроса будет отправлено сообщение в канал или по каскаду в соответствии с заданными параметрами (в теле запроса). В случае успешного выполнения запроса вернется ответ от сервера с кодом 200, содержащий JSON с идентификатором сообщения и статусом его отправки. В случае неуспешного выполнения запроса возвращается сообщение с кодом ошибки.

URL-адрес подключения

Для отправки сообщения выполняется POST-запрос на URL-адрес: https://app.edna.ru/api/cascade/schedule

Формат запроса

В теле запроса передаётся набор параметров каскада, в соответствии с которым вы хотите отправить рассылку, а также её содержимое.

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

Ниже приведен пример тела запроса с использованием каскада, в рамках которого отправляется сообщение клиенту через канал push, потом сообщение отправляется в WhatsApp клиента, а затем отправляется SMS сообщение.

{
    "requestId": "test-001",
    "comment": "Postman 2022-12-15T13:57:02.575Z",
    "cascadeId": 111,
    "subscriberFilter": {
        "address": "79000000000",
        "type": "PHONE"
    },
    "startTime": "2022-01-21T08:00:00Z",
    "content": {
        "smsContent": {
            "text": "Карта готова, заберите её в отделении банка"
        },
        "whatsappContent": {
            "contentType": "TEXT",
            "text": "Карта готова, заберите её в отделении банка",
            "attachment": {
                "url": "https://.jpg", 
                "name": "Схема прохода",
                "size": 5123
            },
            "location": {
                "longitude": 56.7645,
                "latitude": 48.4564,
                "address": "г. Москва, ул Правды, д 3"
            }
        },
        "pushContent": {
                "small": {
                    "text": "Заберите её в отделении банка",
                    "title": "Карта готова",
                    "imageUrl": "https://.png"
                },
                "big": {
                    "title": "Карта готова",
                    "text": "Заберите её в отделении банка",
                    "imageUrl": "https://.png"
                },
                "buttons": [
                    {
                        "text": "Поддержка",
                        "url": "DeeplinkSupport"
                    },
                    {
                        "text": "Напомнить позже",
                        "url": "DeeplinkLater"
                    }
                ],
                "action": "DeeplinkMainPush",
                "effects": {
                    "vibrate": "[500,100,500,150,50,50]",
                    "lights": "#770808",
                    "sound": "AthlonRoar",
                    "androidNotificationChannel": "Статус заказа"
                },
                "iosSettings": {
                    "interruptionLevel": "ACTIVE",
                    "category": "ednaPushCategory"
                }
            }
        }
    }

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

Ниже представлен полный набором параметров и их описание. Примеры запросов по каждому каналу и типу содержимого доступны здесь.

Общие параметры

ПараметрТип данныхОписание
requestIdstringИдентификатор сообщения. Генерируется вашей системой, после чего значение должно быть передано в запрос. Допускается любая длинна строки до 36 символов
commentstring (optional)Текстовый комментарий в сообщении. Значение параметра отображается в детальном отчете.
cascadeIdstringИдентификатор каскада.
При создание канала автоматически создается каскад с отправкой сообщения по этому каналу. Для того, чтобы узнать идентификатор нужного вам каскада, используйте метод API по получению информации о каскадах (см поле id).
subscriberFilterobjectПолучатель сообщения: ID в Платформе edna, ID клиента в Instagram*, номер телефона клиента, а также другие ID для push-сообщений.

subscriberFilter включает в себя следующие параметры: address и type. В свою очередь, type может быть PHONEEDNA_ID, а также различные ID для push-сообщений (полный список ID доступен ниже в описании параметра type). При этом address — это значение, которое зависит от type. Таким образом, например, если type это PHONE, то address будет номер телефона клиента. Например:

"subscriberFilter":
{
"address": "79000000000",
"type": "PHONE"
}
addressstringЗначение идентификатора указанного типа type
typestringТип идентификатора клиента:

Тип содержимого сообщения. Возможные значения (необходимо указывать в верхнем регистре):

• INSTAGRAM_ID*
• FACEBOOK_ID*
• DEVICE_APP_ID
• EDNA_ID
• PHONE
• EMAIL
• UTM
• COOKIE_ID
• TELEGRAM_ID 
• GOOGLE_ID
• APPLE_ID
• YANDEX_ID
• EXT_USER_ID
EDNA_IDstringИдентификатор клиента в базе данных edna, который создаётся автоматически при создании клиента в edna. Отображается на странице Редактирование пользователя в строке URL, например: 3314 в строке https://app.edna.ru/audience/3314/edit
Доступен только для каналов WhatsApp, SMS и Viber.
PHONEstringНомер телефона клиента
INSTAGRAM_ID*stringИдентификатор клиента в Instagram*, состоящий из 16 числовых символов. Этот идентификатор создаётся на стороне Facebook*, когда клиент первым взаимодействует с Instagram* аккаунтом бизнеса. Это значение может быть разным и меняться для одного и того же Instagram* клиента
DEVICE_APP_IDstringИдентификатор пуш-устройства клиента
startTimestring (optional)Время, раньше которого сообщение не будет отправлено. Используется при отложенной отправке. Формат:

• YYYY-MM-DDTHH:mm:ss.SSSXXX (2021-01-21T08:00:00Z)
• YYYY-MM-DDTHH:mm:ss.SSS+TZ (2021-01-21T08:00:00Z+03:00)
contentobjectОбъект. Может содержать объекты smsContentwhatsappContentviberContent
и pushContent (см. далее в таблице)

Параметры whatsappContent

ПараметрТип данныхОписание
contentTypestring
(optional)
Тип содержимого сообщения. Возможные значения (необходимо указывать в верхнем регистре):

• TEXT — текстовое сообщение
• IMAGE — изображение
• DOCUMENT — документ, вложенный в сообщение
• VIDEO — сообщение, содержащее видео
• AUDIO — сообщение, содержащее звук
• BUTTON — кнопка
• LOCATION — сообщение с координатами, адресом и описанием места. Координаты преобразуются в снимок Google maps
• LIST_PICKER — Кнопки интерактивного меню (WhatsApp)
textstring (optional)Текст сообщения
attachmentobject (optional)Содержит информацию о вложении
attachment.urlstringСсылка на вложение (изображение, файл, видео, аудио)
attachment.namestring
(optional)
Название вложения (изображения, файла, видео, аудио)
attachment.sizestring
(optional)
Размер вложения
headerstring (optional)Заголовок сообщения. Можно выбрать один из следующих вариантов заголовка: текст, изображение, документ. Для текстового заголовка нужно указать сам текст заголовка, заголовок может содержать одну переменную. Сам заголовок отображается жирным текстом перед сообщением. Для мультимедиа заголовка можно указать ссылку на документ или изображение
footerstring (optional)Подпись. Отображается под сообщением приглушенным цветом текста
locationobject (optional)Содержит информацию о местонахождении
location.longitudestringКоординаты (долгота)
location.latitudestringКоординаты (широта)
location.addressstringАдрес на карте
buttonsobject (optional)Массив объектов, в каждом из которых определяется кнопка.
buttons.buttonTypestring (optional)Вид кнопки:
• TEXT — Текст кнопки
• URL — Ссылка, которая откроется при нажатии на кнопку
• PHONE — Телефон
• QUICK_REPLY
• payload — возвращает входящее сообщение. См. примеры
buttons.textstring (optional)Текст кнопки. Максимальная длина — 20 символов
listPickerobject (optional)
Объект списка элементов. Содержит в себе параметр button и объект sections, который содержит объекты
section.
listPicker.buttonStringНаименование кнопки для интерактивного списка
listPicker.sections
listPicker.sections.titleStringЗаголовок секции с элементами, который отображается пользователю
listPicker.sections.items
Array of Objects
Список объектов item
listPicker.sections.items.
identifier
StringСквозной для всего сообщения ID элемента, вернется в ответном сообщении пользователя
listPicker.sections.items.
title
StringНазвание элемента
listPicker.sections.items.
subtitle
String (optional)Подзаголовок элемента

Параметры viberContent

ПараметрыТип данныхОписание
contentTypestring
(optional)
Тип содержимого сообщения. Возможные значения (необходимо указывать в верхнем регистре):

• TEXT — текстовое сообщение
• IMAGE — изображение
• DOCUMENT — документ, вложенный в сообщение
• VIDEO — сообщение, содержащее видео
• AUDIO — сообщение, содержащее звук
• BUTTON — кнопка
• LOCATION — сообщение с координатами, адресом и описанием места. Координаты преобразуются в снимок Google maps
• LIST_PICKER — Кнопки интерактивного меню (WhatsApp)
textstring (optional)Текст сообщения
headerobject (optional)Заголовок сообщения. Можно выбрать один из следующих вариантов заголовка: текст, изображение, документ. Для текстового заголовка нужно указать сам текст заголовка, заголовок может содержать одну переменную. Сам заголовок отображается жирным текстом перед сообщением. Для мультимедиа заголовка можно указать ссылку на документ или изображение.
footerobject (optional)Подпись. Отображается под сообщением приглушенным цветом текста
attachmentobject (optional)Содержит информацию о вложении
attachment.urlstringСсылка на вложение (изображение, файл, видео, аудио)
attachment.namestring (optional)Название вложения (изображения, файла, видео, аудио)
attachment.sizestring (optional)Размер вложения
locationobject (optional)Содержит информацию о местонахождении
location.longitudestringКоординаты (долгота)
location.latitudestringКоординаты (широта)
location.addressstring (optional)Адрес на карте
captionstring (optional)Название кнопки
actionstring (optional)Ссылка для кнопки

Параметры smsContent

ПараметрыТип данныхОписание
textstringТекст сообщения

Параметры pushContent

ПараметрыТип данныхОписание
smallobjectПараметры отображения свёрнутого пуш-уведомления
small.titlestring
(optional)
Заголовок свёрнутого пуш-уведомления
small.textstringТекст свёрнутого пуш-уведомления
small.imageUrlstring
(optional)
Иконка (логотип) для отображения в свёрнутом пуш-уведомлении. Рекомендуемое соотношение сторон 1×1, размер не более 1024×1024
bigobject (optional)Параметры отображения расширенного пуш-уведомления
big.titlestring (optional)Заголовок развёрнутого пуш-уведомления
big.textstring (optional)Текст развёрнутого пуш-уведомления
big.imageUrlstring (optional)Большое изображение для развёрнутого пуша. Рекомендуются изображения с соотношениями сторон 2×1, где основная визуальная масса остается при обрезке до 1.79×1 и 2,5×1 (ограничения Андроид)
actionstring (optional)Ссылка, которая будет передана приложению при переходе пользователя по пуш-уведомлению
buttonsobject (optional)Параметры отображения кнопок. Вместе с уведомлением можно отобразить до двух кнопок.
buttons.textstring (optional)Название кнопки. Пользователи увидят это название на кнопке в уведомлении.
buttons.urlstring (optional)Ссылка кнопки. Будет передана приложению при нажатии пользователя на кнопку.
effectsobject (optional)Звук, вибрация, имя notification channel и цвет мигания светодиода на устройстве пользователя при получении пуш-уведомления
effects.soundstring (optional)Имя файла со звуком без расширения. Файл с таким именем должен находится в каталоге res/raw приложения Андроид и в корневом каталоге Xcode приложения iOS
effects.lightsstring (optional)Цвет LED при получении пуша (только Андроид). На некоторых смартфонах Андроид есть сигнальный светодиод. С помощью этого параметра можно задать цвет мигания этого светодиода при получении пуша
effects.vibratestring (optional)Последовательность промежутков бездействия и вибрации мотора при получении пуша в миллисекундах (только Андроид). Первое значение – бездействие. Например, при паттерне [300,500,300,500] на устройстве будет 300 мс бездействия, 500 мс вибрации, 300 мс бездействия, 500 мс вибрации.
effects
.androidNotificationChannel
string (optional)Название канала уведомлений для Андроид. Пользователи увидят это название в настройках смартфона. Изменить параметры канала (звук, вибрацию и цвет светодиода) возможно только для новых получателей пуш-уведомлений.
iosSettingsobject (optional)Уровень прерывания и категория ContentExtension (только для iOS)
iosSettings
.interruptionLevel
string (optional)Уровень прерывания определяет вид уведомления на iOS 15 и выше.
iosSettings.categorystring (optional)Категория для вызова ContentExtension. Параметр обрабатывается на стороне iOS и определяет, как отрисовывается расширенный пуш.
attributesobject (optional)Дополнительные параметры пуш-сообщения. Внутри JSON таблица «ключ-значение»

* Деятельность сети запрещена на территории РФ

Кавычки в тексте

Необходимо быть внимательным к выделению слов в кавычки. Если вы используете знак двойные кавычки “ или одиночные кавычки ‘ в отправляемом сообщении, то их обязательно нужно отделять знаком \ (обратный слеш).

Правильно:

"text": "Мария! Ждем вас на Мастер-класс \"Готовим вместе c Tefal\" 25.01.2020 в 13.00. Не пропустите это событие! Наш телефон 8(495)100-00-00"
и так
"text": "Мария! Ждем вас на Мастер-класс «Готовим вместе c Tefal» 25.01.2020 в 13.00. Не пропустите это событие! Наш телефон 8(495)100-00-00"

Неправильно:

"text": "Мария! Ждем вас на Мастер-класс "Готовим вместе с Tefal" 25.01.2020 в 13.00. Не пропустите это событие! Наш телефон 8(495)100-00-00"

Оформление текста в WhatsApp

Вы можете использовать различные опции для оформления текста в WhatsApp сообщениях. Эта опция подключена по умолчанию, отключить её нельзя.

  • Курсив: Используйте символ подчеркивания по обе стороны текста: _текст_
  • Жирный: Используйте символ звёздочки по обе стороны текста: *текст*
  • Зачеркнутый: Используйте символ тильды по обе стороны текста: ~текст~
  • Моноширинный: используйте символ трёх кавычек по обе стороны текста: ```текст```

Формат ответа

В ответ на запрос возвращается JSON-объект, содержащий Id отправленного сообщения и статус его обработки.

ПараметрТип данныхОписание
requestidstringИдентификатор сообщения. Это номер был сгенерирован на вашей стороне

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

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


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

Тип вложенияПоддерживаемый форматРазмер, МВ
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

Важно! Название прикрепленного файла (attachmentName) не может превышать 25 символов для месенджера Viber. Для все остальных допускается не более 75 символов.

Для дополнительной информации по форматам медиа вложений для WhatsApp можно
обратиться на этот ресурс*.

* Деятельность сети запрещена на территории РФ

Cледующая статья Примеры отправки сообщений