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

KB Home
API
API edna Pulse
Сообщения
Отправка сообщений

Метод schedule используется для отправки сообщений в каналы WhatsApp, Viber, SMS, Push и Notify.

Сообщения отправляются через каскад — сценарий последовательной рассылки в несколько каналов. При регистрации канала каскад для него создается автоматически. Создать каскад из нескольких каналов можно в личном кабинете edna Pulse. Подробнее:

Вы можете протестировать отправку сообщений с помощью API edna Pulse для канала WhatsApp, не регистрируя канал. Подробнее в статье.

edna Pulse не позволяет отправлять дубликаты сообщения в течение 20 минут после его отправки.

Метод `schedule`

Чтобы обратиться к методу 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	Обязательный	Идентификатор сообщения. Генерируется вашей системой, после чего значение должно быть передано в запрос. Максимальная длина строки — 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`). Если `type` — это `PHONE`, то `address` — номер телефона клиента. Например: `"subscriberFilter":` `{ "address": "79000000000", "type": "PHONE" }`
`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	Обязательный	Содержит информацию о местонахождении.
`location.longitude`	string	Обязательный, если объект `location` не пустой	Координаты (долгота).
`location.latitude`	string	Обязательный, если объект `location` не пустой	Координаты (широта).
`location.address`	string	Обязательный, если объект `location` не пустой	Адрес на карте.
`location.name`	string	Обязательный, если объект `location` не пустой	Название объекта, адрес которого передается.
`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. identifier`	string	Обязательный, если объект `listPicker` не пустой	Сквозной для всего сообщения ID элемента, вернется в ответном сообщении пользователя.
`listPicker.sections.items. title`	string	Обязательный, если объект `listPicker` не пустой	Название элемента.
`listPicker.sections.items. subtitle`	string	Обязательный	Подзаголовок элемента.
`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 .interruptionLevel`	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 запрещена на территории Российской Федерации.

Войти с единой учетной записью edna

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

Метод schedule

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

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

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

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

Параметры whatsappContent

Параметры viberContent

Параметры smsContent

Параметры pushContent

Параметры vkNotifyContent

Параметры okNotifyContent