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

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

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

Метод schedule

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

Информация о результате отправки сообщения адресату придет на установленный вами вебхук. Дополнительные сведения см. в статье Получение статусов сообщений.

В случае успешной отправки сообщения вернется статус sent, затем delivered, read или undelivered (в зависимости от канала). Если статус сообщения failed, то сообщение обработано с ошибкой и не отправлено. Если сервер не вернул статус сообщения, возможно, что сообщение не удалось доставить адресату. В этом случае необходимо обратиться в службу технической поддержки.

Полный список статусов см. в статье Получение статусов сообщений.

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

Чтобы обратиться к методу schedule, отправьте 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Текстовый комментарий в сообщении. Значение параметра отображается в детальном отчете.
cascadeIdstringдаИдентификатор каскада.
При создание канала автоматически создается каскад с отправкой сообщения по этому каналу. Для того, чтобы узнать идентификатор нужного вам каскада, используйте метод API по получению информации о каскадах (см поле id).
subscriberFilterobjectдаПолучатель сообщения: ID в edna Pulse, 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* — Идентификатор клиента в Instagram*, состоящий из 16 числовых символов. Этот идентификатор создаётся на стороне Facebook*, когда клиент первым взаимодействует с Instagram* аккаунтом бизнеса. Это значение может быть разным и меняться для одного и того же Instagram* клиента.
• FACEBOOK_ID*
• DEVICE_APP_ID — Идентификатор пуш-устройства клиента
• 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
startTimestringВремя, раньше которого сообщение не будет отправлено. Используется при отложенной отправке. Формат:

• 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Тип содержимого сообщения. Возможные значения (необходимо указывать в верхнем регистре):

• TEXT — текстовое сообщение
• IMAGE — изображение
• DOCUMENT — документ, вложенный в сообщение
• VIDEO — сообщение, содержащее видео
• AUDIO — сообщение, содержащее звук
• BUTTON — кнопка
• LOCATION — сообщение с координатами, адресом и описанием места. Координаты преобразуются в снимок Google maps
• LIST_PICKER — Кнопки интерактивного меню (WhatsApp)
• AUTHENTICATION — сообщение с одноразовым паролем и кнопкой копирования
textstringда, если contentType = TEXT or AUTHENTICATIONТекст сообщения, если contentType = TEXT.
Одноразовый пароль, если contentType = AUTHENTICATION.
attachmentobjectСодержит информацию о вложении.
ВАЖНО! Если при отправке чат-сообщения WhatsApp указано поле attachment, то поле text игнорируется. Отправляется только вложение.
attachment.urlstringда, если объект attachment не пустойСсылка на вложение (изображение, файл, видео, аудио)
attachment.namestringНазвание вложения (изображения, файла, видео, аудио). Максимальная длина — 70 символов.
attachment.sizestringРазмер вложения
headerstring Заголовок сообщения. Можно выбрать один из следующих вариантов заголовка: текст, изображение, документ. Для текстового заголовка нужно указать сам текст заголовка, заголовок может содержать одну переменную. Сам заголовок отображается жирным текстом перед сообщением. Для мультимедиа заголовка можно указать ссылку на документ или изображение
footerstring Подпись. Отображается под сообщением приглушенным цветом текста
locationobject Содержит информацию о местонахождении
location.longitudestringда, если объект location не пустойКоординаты (долгота)
location.latitudestringда, если объект location не пустойКоординаты (широта)
location.addressstringАдрес на карте
buttonsobjectМассив объектов, в каждом из которых определяется кнопка.
buttons.typestringВид кнопки:
• 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.textstringТекст кнопки. Максимальная длина — 20 символов
buttons.urlstringURL-адрес, который открывается при нажатии кнопки
buttons.urlPostfixstringДинамическая часть ссылки URL-адреса кнопки
buttons.phonestringНомер телефона, который набирается при нажатии кнопки
buttons.payloadstringТекст быстрого ответа
listPickerobject Объект списка элементов. Содержит в себе параметр button и объект sections, который содержит объекты section.
listPicker.buttonstringда, если объект listPicker не пустой
Наименование кнопки для интерактивного списка
listPicker.sections.titlestringда, если объект 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Подзаголовок элемента
messageMatcherIdintegerда, если contentType = AUTHENTICATIONИдентификатор шаблона для данного авторизационного сообщения

Параметры 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)Название вложения (изображения, файла, видео, аудио). Максимальная длина — 25 символов.
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

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

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

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