Используйте этот метод для отправки сообщений через каналы мессенджеров (WhatsApp и Viber), SMS и пуш, в том числе, используя каскады, то есть комбинацию каналов.
Метод 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" } } } }
Параметры запроса
Ниже представлен полный набором параметров и их описание. Примеры запросов по каждому каналу и типу содержимого доступны здесь.
Общие параметры
Параметр | Тип данных | Описание |
requestId | string | Идентификатор сообщения. Генерируется вашей системой, после чего значение должно быть передано в запрос. Допускается любая длинна строки до 36 символов |
comment | string (optional) | Текстовый комментарий в сообщении. Значение параметра отображается в детальном отчете. |
cascadeId | string | Идентификатор каскада. При создание канала автоматически создается каскад с отправкой сообщения по этому каналу. Для того, чтобы узнать идентификатор нужного вам каскада, используйте метод API по получению информации о каскадах (см поле id ). |
subscriberFilter | object | Получатель сообщения: ID в Платформе edna, ID клиента в Instagram*, номер телефона клиента, а также другие ID для push-сообщений.subscriberFilter включает в себя следующие параметры: address и type . В свою очередь, type может быть PHONE , EDNA_ID , а также различные ID для push-сообщений (полный список ID доступен ниже в описании параметра type ). При этом address — это значение, которое зависит от type . Таким образом, например, если type это PHONE , то address будет номер телефона клиента. Например:"subscriberFilter": { |
address | string | Значение идентификатора указанного типа type |
type | string | Тип идентификатора клиента: Тип содержимого сообщения. Возможные значения (необходимо указывать в верхнем регистре): • 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_ID | string | Идентификатор клиента в базе данных edna, который создаётся автоматически при создании клиента в edna. Отображается на странице Редактирование пользователя в строке URL, например: 3314 в строке https://app.edna.ru/audience/3314/edit Доступен только для каналов WhatsApp, SMS и Viber. |
PHONE | string | Номер телефона клиента |
INSTAGRAM_ID * | string | Идентификатор клиента в Instagram*, состоящий из 16 числовых символов. Этот идентификатор создаётся на стороне Facebook*, когда клиент первым взаимодействует с Instagram* аккаунтом бизнеса. Это значение может быть разным и меняться для одного и того же Instagram* клиента |
DEVICE_APP_ID | string | Идентификатор пуш-устройства клиента |
startTime | string (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) |
content | object | Объект. Может содержать объекты smsContent , whatsappContent , viberContent и pushContent (см. далее в таблице) |
Параметры whatsappContent
Параметр | Тип данных | Описание |
contentType | string (optional) | Тип содержимого сообщения. Возможные значения (необходимо указывать в верхнем регистре): • TEXT — текстовое сообщение• IMAGE — изображение• DOCUMENT — документ, вложенный в сообщение• VIDEO — сообщение, содержащее видео• AUDIO — сообщение, содержащее звук• BUTTON — кнопка• LOCATION — сообщение с координатами, адресом и описанием места. Координаты преобразуются в снимок Google maps• LIST_PICKER — Кнопки интерактивного меню (WhatsApp) |
text | string (optional) | Текст сообщения |
attachment | object (optional) | Содержит информацию о вложении |
attachment.url | string | Ссылка на вложение (изображение, файл, видео, аудио) |
attachment.name | string (optional) | Название вложения (изображения, файла, видео, аудио) |
attachment.size | string (optional) | Размер вложения |
header | string (optional) | Заголовок сообщения. Можно выбрать один из следующих вариантов заголовка: текст, изображение, документ. Для текстового заголовка нужно указать сам текст заголовка, заголовок может содержать одну переменную. Сам заголовок отображается жирным текстом перед сообщением. Для мультимедиа заголовка можно указать ссылку на документ или изображение |
footer | string (optional) | Подпись. Отображается под сообщением приглушенным цветом текста |
location | object (optional) | Содержит информацию о местонахождении |
location.longitude | string | Координаты (долгота) |
location.latitude | string | Координаты (широта) |
location.address | string | Адрес на карте |
buttons | object (optional) | Массив объектов, в каждом из которых определяется кнопка. |
buttons.buttonType | string (optional) | Вид кнопки: • TEXT — Текст кнопки• URL — Ссылка, которая откроется при нажатии на кнопку• PHONE — Телефон• QUICK_REPLY • payload — возвращает входящее сообщение. См. примеры |
buttons.text | string (optional) | Текст кнопки. Максимальная длина — 20 символов |
listPicker | object (optional) | Объект списка элементов. Содержит в себе параметр button и объект sections, который содержит объекты section. |
listPicker.button | String | Наименование кнопки для интерактивного списка |
listPicker.sections | ||
listPicker.sections.title | String | Заголовок секции с элементами, который отображается пользователю |
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
Параметры | Тип данных | Описание |
contentType | string (optional) | Тип содержимого сообщения. Возможные значения (необходимо указывать в верхнем регистре): • TEXT — текстовое сообщение• IMAGE — изображение• DOCUMENT — документ, вложенный в сообщение• VIDEO — сообщение, содержащее видео• AUDIO — сообщение, содержащее звук• BUTTON — кнопка• LOCATION — сообщение с координатами, адресом и описанием места. Координаты преобразуются в снимок Google maps• LIST_PICKER — Кнопки интерактивного меню (WhatsApp) |
text | string (optional) | Текст сообщения |
header | object (optional) | Заголовок сообщения. Можно выбрать один из следующих вариантов заголовка: текст, изображение, документ. Для текстового заголовка нужно указать сам текст заголовка, заголовок может содержать одну переменную. Сам заголовок отображается жирным текстом перед сообщением. Для мультимедиа заголовка можно указать ссылку на документ или изображение. |
footer | object (optional) | Подпись. Отображается под сообщением приглушенным цветом текста |
attachment | object (optional) | Содержит информацию о вложении |
attachment.url | string | Ссылка на вложение (изображение, файл, видео, аудио) |
attachment.name | string (optional) | Название вложения (изображения, файла, видео, аудио) |
attachment.size | string (optional) | Размер вложения |
location | object (optional) | Содержит информацию о местонахождении |
location.longitude | string | Координаты (долгота) |
location.latitude | string | Координаты (широта) |
location.address | string (optional) | Адрес на карте |
caption | string (optional) | Название кнопки |
action | string (optional) | Ссылка для кнопки |
Параметры smsContent
Параметры | Тип данных | Описание |
text | string | Текст сообщения |
Параметры pushContent
Параметры | Тип данных | Описание |
small | object | Параметры отображения свёрнутого пуш-уведомления |
small.title | string (optional) | Заголовок свёрнутого пуш-уведомления |
small.text | string | Текст свёрнутого пуш-уведомления |
small.imageUrl | string (optional) | Иконка (логотип) для отображения в свёрнутом пуш-уведомлении. Рекомендуемое соотношение сторон 1×1, размер не более 1024×1024 |
big | object (optional) | Параметры отображения расширенного пуш-уведомления |
big.title | string (optional) | Заголовок развёрнутого пуш-уведомления |
big.text | string (optional) | Текст развёрнутого пуш-уведомления |
big.imageUrl | string (optional) | Большое изображение для развёрнутого пуша. Рекомендуются изображения с соотношениями сторон 2×1, где основная визуальная масса остается при обрезке до 1.79×1 и 2,5×1 (ограничения Андроид) |
action | string (optional) | Ссылка, которая будет передана приложению при переходе пользователя по пуш-уведомлению |
buttons | object (optional) | Параметры отображения кнопок. Вместе с уведомлением можно отобразить до двух кнопок. |
buttons.text | string (optional) | Название кнопки. Пользователи увидят это название на кнопке в уведомлении. |
buttons.url | string (optional) | Ссылка кнопки. Будет передана приложению при нажатии пользователя на кнопку. |
effects | object (optional) | Звук, вибрация, имя notification channel и цвет мигания светодиода на устройстве пользователя при получении пуш-уведомления |
effects.sound | string (optional) | Имя файла со звуком без расширения. Файл с таким именем должен находится в каталоге res/raw приложения Андроид и в корневом каталоге Xcode приложения iOS |
effects.lights | string (optional) | Цвет LED при получении пуша (только Андроид). На некоторых смартфонах Андроид есть сигнальный светодиод. С помощью этого параметра можно задать цвет мигания этого светодиода при получении пуша |
effects.vibrate | string (optional) | Последовательность промежутков бездействия и вибрации мотора при получении пуша в миллисекундах (только Андроид). Первое значение – бездействие. Например, при паттерне [300,500,300,500] на устройстве будет 300 мс бездействия, 500 мс вибрации, 300 мс бездействия, 500 мс вибрации. |
effects .androidNotificationChannel | string (optional) | Название канала уведомлений для Андроид. Пользователи увидят это название в настройках смартфона. Изменить параметры канала (звук, вибрацию и цвет светодиода) возможно только для новых получателей пуш-уведомлений. |
iosSettings | object (optional) | Уровень прерывания и категория ContentExtension (только для iOS) |
iosSettings | string (optional) | Уровень прерывания определяет вид уведомления на iOS 15 и выше. |
iosSettings.category | string (optional) | Категория для вызова ContentExtension. Параметр обрабатывается на стороне iOS и определяет, как отрисовывается расширенный пуш. |
attributes | object (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 отправленного сообщения и статус его обработки.
Параметр | Тип данных | Описание |
requestid | string | Идентификатор сообщения. Это номер был сгенерирован на вашей стороне |
Типы вложений
Все отправляемые вложения должны удовлетворять нижеперечисленным требованиям. Иначе сообщение не будет доставлено.
Поддерживаемые типы медиа вложений и их допустимые размеры:
Тип вложения | Поддерживаемый формат | Размер, МВ |
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 |
Важно! Название прикрепленного файла (attachmentName
) не может превышать 25 символов для месенджера Viber. Для все остальных допускается не более 75 символов.
Для дополнительной информации по форматам медиа вложений для WhatsApp можно
обратиться на этот ресурс*.
* Деятельность сети запрещена на территории РФ