Для отправки сообщений в каналы WhatsApp, Viber, SMS, Push и Notify используется метод api/cascade/schedule.
Сообщения отправляются через каскад — сценарий последовательной рассылки в несколько каналов. При регистрации канала каскад для него создается автоматически. Создать каскад из нескольких каналов можно в личном кабинете edna Pulse. Подробнее:
Вы можете протестировать отправку сообщений с помощью API edna Pulse для канала WhatsApp, не регистрируя канал. Подробнее в статье.
edna Pulse не позволяет отправлять дубликаты сообщения в течение 20 минут после его отправки.
Вызов метода api/cascade/schedule
Чтобы вызвать метод api/cascade/schedule, отправьте POST-запрос на URL-адрес https://app.edna.ru/api/cascade/schedule. Запрос выполняется через публичный интерфейс API с авторизацией по API-ключу.
После выполнения запроса программа получает задание на отправку сообщения по каскаду согласно параметрам в теле запроса.
Если запрос принят, сервер возвращает ответ с кодом 200, содержащий JSON-объект с идентификатором запроса. В случае неуспешной проверки запроса возвращается ответ с кодом ошибки.
Информация о результате отправки сообщения приходит на установленный вебхук. Подробнее в статье.
В случае успешной отправки сообщения возвращается статус sent, затем delivered, read или undelivered (в зависимости от канала). Статус сообщения failed означает, что сообщение обработано с ошибкой и не отправлено. Полный список статусов смотрите в статье.
Если сервер не возвращает статус сообщения, отправьте запрос в службу технической поддержки support@edna.ru.
Формат запроса
В теле запроса передается набор параметров каскада, по которому вы хотите отправить сообщение.
Нажмите, чтобы открыть JSON
{
"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",
"name": "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"
} Пример запроса
Ниже приведен пример тела запроса с использованием каскада, по которому клиенту отправляется SMS-сообщение, затем сообщение в канал WhatsApp и сообщение в канал Push.
Нажмите, чтобы открыть JSON
{
"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",
"name": "ООО Компания"
}
},
"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"
}
}
}
}
Параметры запроса
В разделах ниже описаны:
- Общие параметры.
- Параметры
whatsappContent. - Параметры
viberContent. - Параметры
smsContent. - Параметры
pushContent. - Параметры
vkNotifyContent. - Параметры
okNotifyContent.
Примеры запросов по каждому каналу смотрите в статье.
Общие параметры
| Параметр | Тип данных | Характер | Описание |
requestId | string | Обязательный | Идентификатор сообщения. Генерируется вашей системой, после чего значение должно быть передано в запрос. Максимальная длина строки — 256 символов. |
comment | string | Необязательный | Текстовый комментарий в сообщении. Значение параметра отображается в детальном отчете. |
cascadeId | string | Обязательный | Идентификатор каскада. При создании канала автоматически создается каскад для отправки сообщений по этому каналу. Чтобы узнать идентификатор каскада, используйте метод API по получению информации о каскадах (поле id). |
subscriberFilter | object | Обязательный | Получатель сообщения: ID в edna Pulse, номер телефона клиента, а также другие ID для push-сообщений.subscriberFilter включает в себя параметры:• address — значение, которое зависит от type;• type — может быть PHONE, EDNA_ID или ID для push-сообщений (полный список ID доступен ниже в описании параметра type).Если type — это PHONE, то address — номер телефона клиента. Например:"subscriberFilter":{ |
address | string | Обязательный | Значение идентификатора указанного типа type. |
type | string | Обязательный | Тип идентификатора клиента. Возможные значения указываются в верхнем регистре: • INSTAGRAM_ID* — Идентификатор клиента в Instagram* из 16 числовых символов. Этот идентификатор создается на стороне Facebook*, когда клиент первым взаимодействует с Instagram*-аккаунтом бизнеса. Это значение может быть разным и меняться для одного и того же Instagram* клиента.• FACEBOOK_ID* — Идентификатор клиента в Facebook*.• 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 или AUTHENTICATION | Текст сообщения, если contentType = TEXT.Одноразовый пароль, если contentType = AUTHENTICATION. |
attachment | object | Обязательный | Содержит информацию о вложении. Если при отправке чат-сообщения WhatsApp указано поле attachment, то поле text игнорируется и отправляется только вложение. |
attachment.url | string | Обязательный, если объект attachment не пустой | Ссылка на вложение: изображение, файл, видео или аудио. |
attachment.name | string | Обязательный | Название изображения, файла, видео или аудио. Максимальная длина — 70 символов. |
header | string | Обязательный | Заголовок сообщения. Можно выбрать один из следующих вариантов заголовка: текст, изображение, документ. Для текстового заголовка нужно указать сам текст заголовка, заголовок может содержать одну переменную. Сам заголовок отображается жирным текстом перед сообщением. Для мультимедиа заголовка можно указать ссылку на документ или изображение. |
footer | string | Обязательный | Подпись. Отображается под сообщением приглушенным цветом текста. |
location | object | Обязательный | Содержит информацию о геолокации. Отправка сообщения с геолокацией доступна только в рамках 24-часового диалога. |
location.longitude | string | Обязательный | Координаты (долгота). Диапазон значений — от -180 до 180. |
location.latitude | string | Обязательный | Координаты (широта). Диапазон значений — от -90 до 90. |
location.address | string | Необязательный | Адрес на карте. |
location.name | 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 не пустой | Название элемента. Максимальная длина — 24 символа с учетом пробелов. |
listPicker.sections.items. | string | Обязательный | Подзаголовок элемента. Максимальная длина — 24 символа с учетом пробелов. |
messageMatcherId | integer | Обязательный, если contentType = AUTHENTICATION | Идентификатор шаблона для данного авторизационного сообщения. |
Параметры viberContent
| Параметр | Тип данных | Характер | Описание |
contentType | string | Необязательный | Тип содержимого сообщения. Возможные значения указываются в верхнем регистре: • TEXT — текстовое сообщение;• IMAGE — изображение;• DOCUMENT — документ, вложенный в сообщение;• VIDEO — сообщение, содержащее видео;• AUDIO — сообщение, содержащее звук;• BUTTON — кнопка;• LOCATION — сообщение с координатами, адресом и описанием места. Координаты преобразуются в снимок Google maps;• LIST_PICKER — Кнопки интерактивного меню (WhatsApp). |
text | string | Необязательный | Текст сообщения. |
header | object | Необязательный | Заголовок сообщения. Можно выбрать один из следующих вариантов заголовка: текст, изображение, документ. Для текстового заголовка нужно указать сам текст заголовка, заголовок может содержать одну переменную. Сам заголовок отображается жирным текстом перед сообщением. Для мультимедиа заголовка можно указать ссылку на документ или изображение. |
footer | object | Необязательный | Подпись. Отображается под сообщением приглушенным цветом текста. |
attachment | object | Необязательный | Содержит информацию о вложении. |
attachment.url | string | Обязательный | Ссылка на вложение: изображение, файл, видео или аудио. |
attachment.name | string | Необязательный | Название изображения, файла, видео или аудио. Максимальная длина — 25 символов. |
location | object | Необязательный | Содержит информацию о местонахождении. |
location.longitude | string | Обязательный | Координаты (долгота). |
location.latitude | string | Обязательный | Координаты (широта). |
location.address | string | Необязательный | Адрес на карте. |
caption | string | Необязательный | Название кнопки. |
action | string | Необязательный | Ссылка для кнопки. |
Параметры smsContent
| Параметр | Тип данных | Характер | Описание |
text | string | Обязательный | Текст сообщения. |
Параметры pushContent
| Параметр | Тип данных | Характер | Описание |
small | object | Обязательный | Параметры отображения свернутого push-уведомления. |
small.title | string | Необязательный | Заголовок свернутого push-уведомления. |
small.text | string | Обязательный | Текст свернутого push-уведомления. |
small.imageUrl | string | Необязательный | Иконка (логотип) для отображения в свернутом push-уведомлении. Рекомендуемое соотношение сторон — 1×1. Pазмер — не более 1024×1024. |
big | object | Необязательный | Параметры отображения расширенного push-уведомления. |
big.title | string | Необязательный | Заголовок развернутого push-уведомления. |
big.text | string | Необязательный | Текст развернутого push-уведомления. |
big.imageUrl | string | Необязательный | Большое изображение для развернутого push-уведомления. Рекомендуются изображения с соотношениями сторон 2×1, где основная визуальная масса остается при обрезке до 1,79×1 и 2,5×1 (ограничения Android). |
action | string | Необязательный | Ссылка, которая будет передана приложению при переходе пользователя по push-уведомлению. |
buttons | object | Необязательный | Параметры отображения кнопок. Вместе с уведомлением можно отобразить до двух кнопок. |
buttons.text | string | Необязательный | Название кнопки. Пользователи увидят это название на кнопке в уведомлении. |
buttons.url | string | Необязательный | Ссылка кнопки. Будет передана приложению при нажатии пользователя на кнопку. |
effects | object | Необязательный | Звук, вибрация, имя notification channel и цвет мигания светодиода на устройстве пользователя при получении push-уведомления. |
effects.sound | string | Необязательный | Имя файла со звуком без расширения. Файл с таким именем должен находиться в каталоге res/raw приложения Android и в корневом каталоге Xcode приложения iOS. |
effects.lights | string | Необязательный | Цвет LED при получении push-уведомления (только Android). На некоторых смартфонах Android есть сигнальный светодиод. С помощью этого параметра можно задать цвет мигания этого светодиода при получении push-уведомления. |
effects.vibrate | string | Необязательный | Последовательность промежутков бездействия и вибрации мотора при получении push-уведомления в миллисекундах (только Android). Первое значение — бездействие. Например, при паттерне [300,500,300,500] на устройстве будет 300 мс бездействия, 500 мс вибрации, 300 мс бездействия, 500 мс вибрации. |
effects.androidNotificationChannel | string | Необязательный | Название канала уведомлений для Android. Пользователи увидят это название в настройках смартфона. Изменить параметры канала (звук, вибрацию и цвет светодиода) возможно только для новых получателей push-уведомлений. |
iosSettings | object | Необязательный | Уровень прерывания и категория ContentExtension (только для iOS). |
iosSettings | string | Необязательный | Уровень прерывания определяет вид уведомления на iOS 15 и выше. |
iosSettings.category | string | Необязательный | Категория для вызова ContentExtension. Параметр обрабатывается на стороне iOS и определяет, как отрисовывается расширенное push-уведомление. |
attributes | object | Необязательный | Дополнительные параметры push-сообщения. Внутри JSON таблица «ключ-значение». |
Параметры vkNotifyContent
| Параметр | Тип данных | Характер | Описание |
messageMatcherId | integer | Обязательный | Идентификатор шаблона сообщения. |
contentType | string | Обязательный | Тип содержимого сообщения. |
text | string | Обязательный | Текст сообщения. |
keyboard | object | Необязательный | Кнопки в сообщении. |
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*.
* Деятельность компании Meta запрещена на территории Российской Федерации.