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

Используйте этот метод для отправки сообщений по каналам мессенджеров WhatsApp и Viber, SMS, push, а также VK Notify и OK Notify.

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

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

Метод 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"
                }
            }
        }
    }

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

Ниже представлен полный набором параметров и их описание. Примеры запросов по каждому каналу и типу содержимого доступны здесь.

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

ПараметрТип данныхОбяза-
тельный
Описание
requestIdstringдаИдентификатор сообщения. Генерируется вашей системой, после чего значение должно быть передано в запрос. Допускается любая длинна строки до 36 символов.
commentstringТекстовый комментарий в сообщении. Значение параметра отображается в детальном отчете.
cascadeIdstringдаИдентификатор каскада. При создании канала автоматически создается каскад для отправки сообщений по этому каналу. Чтобы узнать идентификатор нужного вам каскада, используйте метод API по получению информации о каскадах (см. поле id).
subscriberFilterobjectдаПолучатель сообщения: ID в edna Pulse, номер телефона клиента, а также другие 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 — Идентификатор 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
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даМожет содержать объекты whatsappContent, viberContent, smsContent, pushContent, vkNotifyContent и okNotifyContent.

Параметры 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 символов.
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 символов.
locationobject (optional)Содержит информацию о местонахождении.
location.longitudestringКоординаты (долгота).
location.latitudestringКоординаты (широта).
location.addressstring (optional)Адрес на карте.
captionstring (optional)Название кнопки.
actionstring (optional)Ссылка для кнопки.

Параметры smsContent

ПараметрТип данныхОписание
textstringТекст сообщения.

Параметры pushContent

ПараметрТип данныхОписание
smallobjectПараметры отображения свернутого push-уведомления.
small.titlestring
(optional)
Заголовок свернутого push-уведомления.
small.textstringТекст свернутого push-уведомления.
small.imageUrlstring
(optional)
Иконка (логотип) для отображения в свернутом push-уведомлении. Рекомендуемое соотношение сторон — 1×1. Pазмер — не более 1024×1024.
bigobject (optional)Параметры отображения расширенного push-уведомления.
big.titlestring (optional)Заголовок развернутого push-уведомления.
big.textstring (optional)Текст развернутого push-уведомления.
big.imageUrlstring (optional)Большое изображение для развернутого push-уведомления. Рекомендуются изображения с соотношениями сторон 2×1, где основная визуальная масса остается при обрезке до 1,79×1 и 2,5×1 (ограничения Андроид).
actionstring (optional)Ссылка, которая будет передана приложению при переходе пользователя по push-уведомлению.
buttonsobject (optional)Параметры отображения кнопок. Вместе с уведомлением можно отобразить до двух кнопок.
buttons.textstring (optional)Название кнопки. Пользователи увидят это название на кнопке в уведомлении.
buttons.urlstring (optional)Ссылка кнопки. Будет передана приложению при нажатии пользователя на кнопку.
effectsobject (optional)Звук, вибрация, имя notification channel и цвет мигания светодиода на устройстве пользователя при получении push-уведомления.
effects.soundstring (optional)Имя файла со звуком без расширения. Файл с таким именем должен находиться в каталоге res/raw приложения Андроид и в корневом каталоге Xcode приложения iOS.
effects.lightsstring (optional)Цвет LED при получении push-уведомления (только Андроид). На некоторых смартфонах Андроид есть сигнальный светодиод. С помощью этого параметра можно задать цвет мигания этого светодиода при получении push-уведомления.
effects.vibratestring (optional)Последовательность промежутков бездействия и вибрации мотора при получении push-уведомления в миллисекундах (только Андроид). Первое значение – бездействие. Например, при паттерне [300,500,300,500] на устройстве будет 300 мс бездействия, 500 мс вибрации, 300 мс бездействия, 500 мс вибрации.
effects
.androidNotificationChannel
string (optional)Название канала уведомлений для Андроид. Пользователи увидят это название в настройках смартфона. Изменить параметры канала (звук, вибрацию и цвет светодиода) возможно только для новых получателей push-уведомлений.
iosSettingsobject (optional)Уровень прерывания и категория ContentExtension (только для iOS).
iosSettings
.interruptionLevel
string (optional)Уровень прерывания определяет вид уведомления на iOS 15 и выше.
iosSettings.categorystring (optional)Категория для вызова ContentExtension. Параметр обрабатывается на стороне iOS и определяет, как отрисовывается расширенное push-уведомление.
attributesobject (optional)Дополнительные параметры push-сообщения. Внутри JSON таблица «ключ-значение».

Параметры vkNotifyContent

ПараметрТип данныхОписание
messageMatcherIdintegerИдентификатор шаблона сообщения.
contentTypestringТип содержимого сообщения.
textstringТекст сообщения.
keyboardobject (optional)Кнопки в сообщении.
keyboard.buttonsobjectМассив объектов, в каждом из которых определяется кнопка.
buttons.textstringНазвание кнопки.
buttons.buttonTypestringТип кнопки: QUICK_REPLY, URL, LOCATION, VK_MINI_APPS.
buttons.payloadstringКод кнопки.
buttons.colorstringЦвет кнопки.
buttons.urlstringURL-адрес для кнопки типа URL.
buttons.hashstringХеш для навигации в приложении. Указывается, если поле определено при регистрации шаблона. Для кнопки типа VK_MINI_APPS.
buttons.appIdintegerИдентификатор приложения, которое открывается после нажатия кнопки. Для кнопки типа VK_MINI_APPS.
buttons.ownerIdintegerИдентификатор сообщества социальной сети Вконтакте, если приложение необходимо открыть в контексте сообщества. Для кнопки типа VK_MINI_APPS.

Параметры okNotifyContent

ПараметрТип данныхОписание
contentTypestringТип содержимого сообщения.
textstringТекст сообщения.

Кавычки в тексте

Необходимо быть внимательным к выделению слов в кавычки. Если вы используете знак двойные кавычки “ или одиночные кавычки ‘ в отправляемом сообщении, то их обязательно нужно отделять знаком \ (обратный слеш).

Правильно:

"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/png.5 МБ
audioaudio/aac, audio/mp4, audio/amr, audio/mpeg, audio/ogg; Кодек=opus (NWB) и ACC.16 МБ
videovideo/mp4, video/3gpp. Внимание: Поддерживается только формат MPEG 4 и 3GPP c кодеком H.264 (MPEG-4 Part 10) и AAC для аудио.16 МБ

Подробнее про форматы медиавложений для WhatsApp смотрите в документации WhatsApp*.

*Деятельность компании «Meta» запрещена на территории РФ.