Используйте этот метод для отправки сообщений по каналам мессенджеров WhatsApp и Viber, SMS, push, а также VK Notify и OK Notify.
Сообщения всегда отправляются через каскад. Каскад — это сценарий рассылки, который может содержать один канал или их комбинацию. При регистрации канала для него автоматически создается каскад. Создать каскад из комбинации каналов можно в личном кабинете edna Pulse. Подробнее в статье.
Метод schedule
В результате выполнения запроса будет платформе будет передано задание на отправку сообщения по каскаду в соответствии параметрами, заданными в теле запроса. Запрос выполняется через публичный интерфейс API с авторизацией по API-ключу.
Если запрос принят к исполнению, сервер возвращает ответ с кодом 200, содержащий JSON-объект с идентификатором запроса, который присвоила система. Если первичная проверка запроса окончилась ошибкой, то возвращается ответ с кодом ошибки.
Информация о результате отправки сообщения адресату придет на установленный вами вебхук. Дополнительные сведения смотрите в статье.
В случае успешной отправки сообщения вернется статус sent
, затем delivered
, read
или undelivered
(в зависимости от канала). Если статус сообщения failed
, то сообщение обработано с ошибкой и не отправлено. Полный список статусов смотрите в статье.
Если сервер не вернул статус сообщения, возможно, что сообщение не удалось доставить адресату. В этом случае необходимо обратиться в службу технической поддержки.
URL-адрес подключения
Чтобы обратиться к методу schedule, отправьте POST-запрос на URL-адрес https://app.edna.ru/api/cascade/schedule.
Формат запроса
В теле запроса передаётся набор параметров каскада, в соответствии с которым вы хотите отправить сообщения.
{ "requestId": "string", "cascadeId": 0, "subscriberFilter": { "address": "string", "type": "EDNA_ID" }, "startTime": "2023-09-27T12:06:29.078Z", "ttl": "PT1M", "content": { "smsContent": { "text": "string" }, "whatsappContent": { "contentType": "TEXT", "text": "string", "attachment": { "url": "string", "name": "string", }, "location": { "longitude": 0, "latitude": 0, "address": "string" }, "comment": "string", "caption": "string", "action": "string", "header": { "text": "string", "imageUrl": "string", "documentUrl": "string", "documentName": "string", "videoUrl": "string", "videoName": "string" }, "footer": { "text": "string" }, "keyboard": { "rows": [ { "buttons": [ { "text": "string", "url": "string", "urlPostfix": "string", "phone": "string", "payload": "string", "type": "PHONE", "otpType": "COPY_CODE", "color": "string", "requestContact": true, "requestLocation": true, "autofillText": "string", "packageName": "string", "hash": "string", "appId": 0, "ownerId": 0 } ] } ] }, "listPicker": { "button": "string", "sections": [ { "title": "string", "items": [ { "identifier": "string", "title": "string", "subtitle": "string" } ] } ] }, "catalog": { "id": "string", "product": { "id": "string" }, "sections": [ { "title": "string", "products": [ { "id": "string" } ] } ] }, "order": { "catalogId": "string", "products": [ { "id": "string", "quantity": 0, "price": 0, "currency": "RUB" } ] }, "messageMatcherId": 0 }, "viberContent": { "contentType": "TEXT", "text": "string", "attachment": { "url": "string", "name": "string", }, "location": { "longitude": 0, "latitude": 0, "address": "string" }, "comment": "string", "caption": "string", "action": "string", "header": { "text": "string", "imageUrl": "string", "documentUrl": "string", "documentName": "string", "videoUrl": "string", "videoName": "string" }, "footer": { "text": "string" }, "keyboard": { "rows": [ { "buttons": [ { "text": "string", "url": "string", "urlPostfix": "string", "phone": "string", "payload": "string", "type": "PHONE", "otpType": "COPY_CODE", "color": "string", "requestContact": true, "requestLocation": true, "autofillText": "string", "packageName": "string", "hash": "string", "appId": 0, "ownerId": 0 } ] } ] } }, "pushContent": { "attributes": { "additionalProp1": "string", "additionalProp2": "string", "additionalProp3": "string" }, "small": { "title": "string", "text": "string", "imageUrl": "string" }, "big": { "title": "string", "text": "string", "imageUrl": "string" }, "buttons": [ { "text": "string", "url": "string" } ], "action": "string", "effects": { "sound": "string", "lights": "string", "vibrate": "string", "androidNotificationChannel": "string" }, "iosSettings": { "interruptionLevel": "ACTIVE", "category": "string" }, "subscription": "string" }, "vkNotifyContent": { "contentType": "string", "text": "string", "messageMatcherId": 0, "keyboard": { "rows": [ { "buttons": [ { "text": "string", "buttonType": "QUICK_REPLY", "payload": "string", "color": "string" } ] } ] } }, "okNotifyContent": { "contentType": "string", "text": "string" } }, "errorIfNotMatched": true, "comment": "string", "priority": "default" }
Пример запроса
Ниже приведен пример тела запроса с использованием каскада, в рамках которого отправляется сообщение клиенту через канал 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": "Схема прохода", }, "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 | Текстовый комментарий в сообщении. Значение параметра отображается в детальном отчете. | |
cascadeId | string | да | Идентификатор каскада. При создании канала автоматически создается каскад для отправки сообщений по этому каналу. Чтобы узнать идентификатор нужного вам каскада, используйте метод API по получению информации о каскадах (см. поле id ). |
subscriberFilter | object | да | Получатель сообщения: ID в edna Pulse, номер телефона клиента, а также другие 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 * — Идентификатор клиента в Instagram*, состоящий из 16 числовых символов. Этот идентификатор создаётся на стороне Facebook*, когда клиент первым взаимодействует с Instagram* аккаунтом бизнеса. Это значение может быть разным и меняться для одного и того же Instagram* клиента.• FACEBOOK_ID* • DEVICE_APP_ID — Идентификатор push-устройства клиента• EDNA_ID — Идентификатор клиента в базе данных edna, который создаётся автоматически при создании клиента в edna. Отображается на странице Редактирование пользователя в строке URL, например: 3314 в строке https://app.edna.ru/audience/3314/edit.Доступен только для каналов WhatsApp, SMS и Viber. • PHONE — Номер телефона клиента в формате «79000000000»• EMAIL • UTM • COOKIE_ID • TELEGRAM_ID • GOOGLE_ID • APPLE_ID • YANDEX_ID • EXT_USER_ID |
startTime | string | Время, раньше которого сообщение не будет отправлено. Используется при отложенной отправке. Формат: • 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 | да | Может содержать объекты whatsappContent, viberContent, smsContent, pushContent, vkNotifyContent и okNotifyContent. |
Параметры whatsappContent
Параметр | Тип данных | Обязательный | Описание |
contentType | string | Тип содержимого сообщения. Возможные значения (необходимо указывать в верхнем регистре): • TEXT — текстовое сообщение;• IMAGE — изображение;• DOCUMENT — документ, вложенный в сообщение;• VIDEO — сообщение, содержащее видео;• AUDIO — сообщение, содержащее звук;• BUTTON — кнопка;• LOCATION — сообщение с координатами, адресом и описанием места. Координаты преобразуются в снимок Google maps;• LIST_PICKER — кнопки интерактивного меню (WhatsApp);• AUTHENTICATION — сообщение с одноразовым паролем и кнопкой копирования. | |
text | string | да, если contentType = TEXT or AUTHENTICATION | Текст сообщения, если contentType = TEXT. Одноразовый пароль, если contentType = AUTHENTICATION. |
attachment | object | Содержит информацию о вложении. ВАЖНО! Если при отправке чат-сообщения WhatsApp указано поле attachment , то поле text игнорируется. Отправляется только вложение. | |
attachment.url | string | да, если объект attachment не пустой | Ссылка на вложение (изображение, файл, видео, аудио). |
attachment.name | string | Название вложения (изображения, файла, видео, аудио). Максимальная длина — 70 символов. | |
header | string | Заголовок сообщения. Можно выбрать один из следующих вариантов заголовка: текст, изображение, документ. Для текстового заголовка нужно указать сам текст заголовка, заголовок может содержать одну переменную. Сам заголовок отображается жирным текстом перед сообщением. Для мультимедиа заголовка можно указать ссылку на документ или изображение. | |
footer | string | Подпись. Отображается под сообщением приглушенным цветом текста. | |
location | object | Содержит информацию о местонахождении. | |
location.longitude | string | да, если объект location не пустой | Координаты (долгота). |
location.latitude | string | да, если объект location не пустой | Координаты (широта). |
location.address | string | Адрес на карте. | |
buttons | object | Массив объектов, в каждом из которых определяется кнопка. | |
buttons.type | string | Вид кнопки: • URL — открывает указанную ссылку;• PHONE — набирает указанный номер телефона;• QUICK_REPLY — отправляет готовый ответ;• OTP — копирует одноразовый пароль.См. примеры. В одном сообщении может быть либо не более трех кнопок типа QUICK_REPLY, либо не более одной каждой из кнопок URL и PHONE. Кнопки QUICK_REPLY не могут быть в сообщении с другими кнопками. Возможные варианты: • QUICK_REPLY • QUICK_REPLY QUICK_REPLY • QUICK_REPLY QUICK_REPLY QUICK_REPLY • URL • PHONE • URL PHONE | |
buttons.text | string | Текст кнопки. Максимальная длина — 20 символов. | |
buttons.url | string | URL-адрес, который открывается при нажатии кнопки. | |
buttons.urlPostfix | string | Динамическая часть ссылки URL-адреса кнопки. | |
buttons.phone | string | Номер телефона, который набирается при нажатии кнопки. | |
buttons.payload | string | Код кнопки быстрого ответа. | |
listPicker | object | Объект списка элементов. Содержит в себе параметр button и объект sections , который содержит объекты section. | |
listPicker.button | string | да, если объект listPicker не пустой | Наименование кнопки для интерактивного списка. |
listPicker.sections.title | string | да, если объект listPicker не пустой | Заголовок секции с элементами, который отображается пользователю. |
listPicker.sections.items | array of objects | Список объектов item . | |
listPicker.sections.items. | string | да, если объект listPicker не пустой | Сквозной для всего сообщения ID элемента, вернется в ответном сообщении пользователя. |
listPicker.sections.items. | string | да, если объект listPicker не пустой | Название элемента. |
listPicker.sections.items. | string | Подзаголовок элемента. | |
messageMatcherId | integer | да, если contentType = AUTHENTICATION | Идентификатор шаблона для данного авторизационного сообщения. |
Параметры 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) | Название вложения (изображения, файла, видео, аудио). Максимальная длина — 25 символов. |
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 | Параметры отображения свернутого push-уведомления. |
small.title | string (optional) | Заголовок свернутого push-уведомления. |
small.text | string | Текст свернутого push-уведомления. |
small.imageUrl | string (optional) | Иконка (логотип) для отображения в свернутом push-уведомлении. Рекомендуемое соотношение сторон — 1×1. Pазмер — не более 1024×1024. |
big | object (optional) | Параметры отображения расширенного push-уведомления. |
big.title | string (optional) | Заголовок развернутого push-уведомления. |
big.text | string (optional) | Текст развернутого push-уведомления. |
big.imageUrl | string (optional) | Большое изображение для развернутого push-уведомления. Рекомендуются изображения с соотношениями сторон 2×1, где основная визуальная масса остается при обрезке до 1,79×1 и 2,5×1 (ограничения Андроид). |
action | string (optional) | Ссылка, которая будет передана приложению при переходе пользователя по push-уведомлению. |
buttons | object (optional) | Параметры отображения кнопок. Вместе с уведомлением можно отобразить до двух кнопок. |
buttons.text | string (optional) | Название кнопки. Пользователи увидят это название на кнопке в уведомлении. |
buttons.url | string (optional) | Ссылка кнопки. Будет передана приложению при нажатии пользователя на кнопку. |
effects | object (optional) | Звук, вибрация, имя notification channel и цвет мигания светодиода на устройстве пользователя при получении push-уведомления. |
effects.sound | string (optional) | Имя файла со звуком без расширения. Файл с таким именем должен находиться в каталоге res/raw приложения Андроид и в корневом каталоге Xcode приложения iOS. |
effects.lights | string (optional) | Цвет LED при получении push-уведомления (только Андроид). На некоторых смартфонах Андроид есть сигнальный светодиод. С помощью этого параметра можно задать цвет мигания этого светодиода при получении push-уведомления. |
effects.vibrate | string (optional) | Последовательность промежутков бездействия и вибрации мотора при получении push-уведомления в миллисекундах (только Андроид). Первое значение – бездействие. Например, при паттерне [300,500,300,500] на устройстве будет 300 мс бездействия, 500 мс вибрации, 300 мс бездействия, 500 мс вибрации. |
effects .androidNotificationChannel | string (optional) | Название канала уведомлений для Андроид. Пользователи увидят это название в настройках смартфона. Изменить параметры канала (звук, вибрацию и цвет светодиода) возможно только для новых получателей push-уведомлений. |
iosSettings | object (optional) | Уровень прерывания и категория ContentExtension (только для iOS). |
iosSettings | string (optional) | Уровень прерывания определяет вид уведомления на iOS 15 и выше. |
iosSettings.category | string (optional) | Категория для вызова ContentExtension. Параметр обрабатывается на стороне iOS и определяет, как отрисовывается расширенное push-уведомление. |
attributes | object (optional) | Дополнительные параметры push-сообщения. Внутри JSON таблица «ключ-значение». |
Параметры vkNotifyContent
Параметр | Тип данных | Описание |
messageMatcherId | integer | Идентификатор шаблона сообщения. |
contentType | string | Тип содержимого сообщения. |
text | string | Текст сообщения. |
keyboard | object (optional) | Кнопки в сообщении. |
keyboard.buttons | object | Массив объектов, в каждом из которых определяется кнопка. |
buttons.text | string | Название кнопки. |
buttons.buttonType | string | Тип кнопки: QUICK_REPLY , URL , LOCATION , VK_MINI_APPS . |
buttons.payload | string | Код кнопки. |
buttons.color | string | Цвет кнопки. |
buttons.url | string | URL-адрес для кнопки типа URL . |
buttons.hash | string | Хеш для навигации в приложении. Указывается, если поле определено при регистрации шаблона. Для кнопки типа VK_MINI_APPS . |
buttons.appId | integer | Идентификатор приложения, которое открывается после нажатия кнопки. Для кнопки типа VK_MINI_APPS . |
buttons.ownerId | integer | Идентификатор сообщества социальной сети Вконтакте, если приложение необходимо открыть в контексте сообщества. Для кнопки типа VK_MINI_APPS . |
Параметры okNotifyContent
Параметр | Тип данных | Описание |
contentType | string | Тип содержимого сообщения. |
text | string | Текст сообщения. |
Кавычки в тексте
Необходимо быть внимательным к выделению слов в кавычки. Если вы используете знак двойные кавычки “ или одиночные кавычки ‘ в отправляемом сообщении, то их обязательно нужно отделять знаком \ (обратный слеш).
Правильно:
"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 МБ |
Подробнее про форматы медиавложений для WhatsApp смотрите в документации WhatsApp*.