Создание операторских шаблонов

KB Home
API
API edna Pulse
Шаблоны
Создание операторских шаблонов

Для запроса на создание операторского шаблона используется метод api/message-matchers.

Вызов метода api/message-matchers

Чтобы вызвать метод api/message-matchers, отправьте POST-запрос на URL-адрес https://app.edna.ru/api/message-matchers.

Если запрос выполнен успешно, создается операторский шаблон и метод возвращает ответ с кодом 200. Если запрос выполнен неуспешно, метод возвращает код ошибки.

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

{
    "name": "string",
    "channelType": "SMS",
    "language": "string",
    "content": {
        "attachment": {
            "fileUrl": "string",
            "originalFileName": "string"
        },
        "action": "string",
        "caption": "string",
        "header": {
            "headerType": "TEXT",
            "text": "string",
            "attachment": {
                "fileUrl": "string",
                "originalFileName": "string"
            },
            "headerExampleTextParam": "string",
            "headerExampleMediaUrl": "string"
        },
        "text": "string",
        "footer": {
            "text": "string"
        },
        "keyboard": {
            "rows": [
                {
                    "buttons": [
                        {
                            "text": "string",
                            "buttonType": "PHONE",
                            "url": "string",
                            "urlPostfix": "string",
                            "phone": "string",
                            "payload": "string",
                            "urlTextExample": "string"
                        }
                    ]
                }
            ]
        },
        "textExampleParams": [
            "string"
        ],
        "contentType": "TEXT",
        "category": "ACCOUNT_UPDATE",
        "type": "OPERATOR"
    },
    "subjectIds": [
        0
    ],
    "smsProviderIds": [
        0
    ]
}

Общие параметры запроса

Параметр	Тип данных	Характер	Описание
`name`	string	Обязательный	Название шаблона. В нем могут быть только латинские буквы, цифры и подчеркивание (_). Максимальное количество символов — 60.
`channelType`	string	Обязательный	Тип канала, для которого надо создать операторский шаблон. Возможные значения: • `WHATSAPP` — канал WhatsApp; • `VIBER` — канал Viber; • `SMS` — канал SMS.
`subjectIds`	integer	Обязательный	Массив идентификаторов подписи, для которых создается шаблон. Чтобы узнать идентификатор подписи канала, используйте метод получения списка каналов.

Параметры запроса для канал WhatsApp

Параметр	Тип данных	Характер	Описание
`language`	string	Обязательный	Язык шаблона в формате WhatsApp Business Platform. Список поддерживаемых языков смотрите на официальном сайте Meta*.
`content`	object	Обязательный	Объект с содержимым шаблона.
`content.attachment`	object	Необязательный	Объект с информацией о вложении.
`content.attachment. fileUrl`	string	Необязательный	URL-адрес файла.
`content.attachment. originalFileName`	string	Необязательный	Имя файла.
`content.header`	object	Необязательный	Объект с информацией о заголовке.
`content.header.headerType`	string	Обязательный (внутренний API-интерфейс) Необязательный (публичный API-интерфейс)	Тип заголовка. Возможные значения: • `TEXT` — текст; • `IMAGE` — изображение; • `VIDEO` — видео; • `DOCUMENT` — файл.
`content.header.text`	string	Необязательный	Текст заголовка.
`content.header.attachment`	object	Необязательный	Объект с информацией о файле в заголовке.
`content.header.attachment. fileUrl`	string	Необязательный	URL-адрес файла в заголовке.
`content.header.attachment. originalFileName`	string	Необязательный	Имя файла в заголовке.
content.header. headerExampleTextParam	string	Обязательный, если `headerType` = `TEXT`	Пример текста заголовка.
`content.header. headerExampleMediaUrl`	string	Обязательный, если `headerType` = `IMAGE`, `VIDEO` или `DOCUMENT`	URL-адрес примера файла заголовка.
`content.text`	string	Обязательный	Текст сообщения.
`content.footer`	object	Необязательный	Объект с информацией о подписи.
`content.footer.text`	string	Необязательный	Текст подписи.
`content.keyboard.rows. buttons`	object	Необязательный	Объект с информацией о кнопках.
`content.keyboard.rows. buttons.text`	string	Необязательный	Название кнопки.
`content.keyboard.rows. buttons.buttonType`	string	Необязательный	Тип кнопки. Возможные значения: • `PHONE` — кнопка-звонок; • `URL` — кнопка-ссылка; • `QUICK_REPLY` — кнопка быстрого ответа.
`content.keyboard.rows. buttons.url`	string	Обязательный, если `buttonType` = `URL`	URL-адрес, который открывается при нажатии кнопки.
`content.keyboard.rows. buttons.urlPostfix`	string	Необязательный	Динамическая часть ссылки URL-адреса кнопки.
`content.keyboard.rows. buttons.phone`	string	Обязательный, если `buttonType` = `PHONE`	Номер телефона, который набирается при нажатии кнопки.
`content.keyboard.rows. buttons.payload`	string	Обязательный, если `buttonType` = `QUICK_REPLY`	Текст быстрого ответа.
`content.keyboard.rows. buttons.urlTextExample`	string	Обязательный, если `buttonType` = `URL`	Пример URL-адреса для кнопки-ссылки.
`content.textExampleParams`	array of strings	Обязательный, если `channelType` = `WHATSAPP` и `content.text` содержит переменные	Пример на каждую переменную в параметре `content.text`.
`contentType`	string	Необязательный	Тип содержимого. Возможные значения: • `TEXT` — текстовое сообщение; • `IMAGE` — изображение; • `BUTTON` — кнопка; • `DOCUMENT` — файл, вложенный в сообщение; • `LOCATION` — сообщение с координатами, адресом и описанием места (координаты преобразуются в снимок Google Maps); • `AUDIO` — сообщение с аудио; • `VIDEO` — сообщение с видео; • `AUTHENTICATION` — сообщение с одноразовым паролем.
`category`	string	Обязательный	Категория шаблона. Возможные значения: • `MARKETING` — новости о компании, предложения с акциями и скидками, информация о мероприятиях и вебинарах; • `AUTHENTICATION` — коды для личного кабинета или приложения для безопасного доступ к учетным записям пользователей, обновление данных или настроек учетной записи, окончание подписки, изменение пароля; • `UTILITY` — информация об изменениях в учетной записи, статусе заказа или программе лояльности, уведомление о получении платежа, подтверждение денежных переводов, прочие транзакции в сфере финансовых услуг. Создание шаблонов категории `AUTHENTICATION` временно ограничено.
`type`	string	Обязательный	Тип шаблона. Возможные значения: • `OPERATOR` — операторский шаблон, зарегистрированный у оператора связи; • `USER` — пользовательский шаблон, созданный пользователем на основе операторского. Поддерживается только тип шаблона `OPERATOR`.

Валидация шаблонов WhatsApp

При создании операторских шаблонов WhatsApp учитывайте следующие ограничения:

Ограничение	Описание
Каналы	Созданный шаблон можно использовать на всех каналах, привязанных к выбранному аккаунту WhatsApp Business.
Название шаблона	В названии можно использовать только латинские буквы, цифры и символ (_). Использование пробелов и других символов не допускается.
Вложения	Возможные типы вложений: • изображение (JPEG, JPG, PNG); • видео (MP4, 3GPP, 3GPP); • документ (PDF). Можно выбрать только один тип вложения для отправки в шаблоне.
Текст сообщения шаблона	• Поле с текстом обязательно для заполнения. • Максимальное количество символов в тексте сообщения с учетом текста в строке символов — 1024. В дополнение к тексту допускается использование переменных. • Текст не должен содержать символов новой строки. • Текст не должен содержать символов 4-х и более последовательных пробелов.
Переменные в тексте сообщения	• Переменная не должна содержать перенос строки. При использовании переноса изменения не сохраняются. • Максимальное количество символов в значении переменной — 512. • Переменные должны быть указаны с двумя двойными фигурными скобками в начале и в конце. • Использование одинарных скобок не допускается.
Текстовый заголовок	• Поля с текстом и типом заголовка обязательны для заполнения. • Максимальное количество символов в текстовом заголовке — 60. • В текстовый заголовок можно добавить одну переменную. • В начале и в конце заголовка нельзя использовать пробелы.
Подпись	• Поле с подписью обязательно для заполнения. • Максимальное количество символов в подписи — 60. • Использование переменных не допускается. • В начале и в конце подписи нельзя использовать пробелы.
Кнопки	• Максимальное количество символов в названии кнопки — 25. • При добавлении кнопки должен быть указан ее тип, все поля обязательны для заполнения.
Кнопка Быстрый ответ (`QUICK_REPLY`)	• Название кнопки согласуется вместе с текстом шаблона без возможности изменения в настройках. • Максимальное количество символов в коде кнопки — 250. • В одном шаблоне может быть не более 3 кнопок этого типа. • Эту кнопку нельзя использовать вместе с кнопками типа Ссылка или Номер. • После нажатия открывается 24-часовое окно. • Нажатие расценивается как ответное сообщение с возможностью открыть переписку. • Кнопку можно нажать только один раз.
Кнопка Ссылка (`URL`)	• Максимальное количество символов в ссылке — 2000. • Доступна проверка работоспособности URL. • При нажатии выполняется переход по заранее согласованной ссылке. • В рамках одного шаблона этот тип кнопок совместим только с кнопками типа Номер. • Нажатие на кнопку не расценивается как ответ пользователя. • Кнопку можно использовать несколько раз.
Кнопка Номер (`PHONE_NUMBER`)	• При нажатии происходит набор указанного номера телефона. • Номер телефона должен быть указан в международном формате (символ «+» в начале), допустимое количество цифр в номере — 10–19. • Звонить можно только через мобильное приложение WhatsApp. • В рамках одного шаблона этот тип кнопок совместим только с кнопками типа Ссылка. • Нажатие на кнопку не расценивается как ответ пользователя. • Кнопку можно использовать несколько раз.
Текст-заполнитель	Максимальное количество текстов-заполнителей — 5.

Параметры запроса для канала Viber

Параметр	Тип данных	Характер	Описание
`language`	string	Обязательный	Язык шаблона в формате ISO 639-1.
`content`	object	Обязательный	Объект с содержимым шаблона.
`content.action`	string	Необязательный	URL-адрес кнопки.
`content.caption`	string	Необязательный	Название кнопки.
`content.text`	string	Обязательный	Текст сообщения.
`contentType`	string	Необязательный	Тип содержимого. Возможные значения: • `TEXT` — текстовое сообщение.
`category`	string	Обязательный	Категория шаблона. Возможные значения: • `ACCOUNT_UPDATE` • `PAYMENT_UPDATE` • `PERSONAL_FINANCE_UPDATE` • `SHIPPING_UPDATE` • `RESERVATION_UPDATE` • `ISSUE_RESOLUTION` • `ISSUE_UPDATE` • `APPOINTMENT_UPDATE` • `TRANSPORTATION_UPDATE` • `TICKET_UPDATE` • `ALERT_UPDATE` • `AUTO_REPLY`
`type`	string	Обязательный	Тип шаблона. Возможные значения: • `OPERATOR` — операторский шаблон, зарегистрированный у оператора связи; • `USER` — пользовательский шаблон, созданный пользователем на основе операторского; • `CUSTOM` — свободный шаблон с разрешенным для указанного канала контентом. Поддерживается только тип `OPERATOR`.

Параметры запроса для канала SMS

Параметр	Тип данных	Характер	Описание
`content`	object	Обязательный	Объект с содержимым шаблона.
`content.text`	string	Обязательный	Текст сообщения.
`type`	string	Обязательный	Тип шаблона. Возможные значения: • `OPERATOR` — операторский шаблон, зарегистрированный у оператора связи.
`smsProviderCodes`	string	Обязательный	Названия операторов связи, для которых регистрируется шаблон SMS. Возможные значения: • `mts` — МТС; • `megafon` — Мегафон; • `tele2`— Тele2; • `beeline` — Билайн; • `motiv` — Мотив.
`category`	string	Обязательный	Категория шаблона. Возможные значения: • `AUTHORIZATION` — авторизационный шаблон; • `TEMPLATE_ADV` — шаблонируемая реклама; • `SERVICE` — сервисный шаблон.

Примеры шаблонов

WhatsApp HSM с переменными в тексте шаблона:

{
    "messageMatcher": {
        "name": "new_matcher",
        "channelType": "WHATSAPP",
        "language": "RU",
        "content": {
            "header": {
                "text": "Ваша компания {{1}}",
                "headerExampleTextParam": "Солнышко"
            },
            "text": "Здравствуйте, {{1}}! Спасибо, что выбрали нас {{2}}",
            "textExampleParams": [
                "Николай",
                "Пример"
            ],
            "keyboard": {
                "rows": [
                    {
                        "buttons": [
                            {
                                "text": "Сайт",
                                "buttonType": "URL",
                                "url": "https://edna.ru/{{1}}",
                                "urlTextExample": "https://edna.ru/test"
                            },
                            {
                                "text": "Позвонить",
                                "buttonType": "PHONE",
                                "phone": "+7900000000"
                            }
                        ]
                    }
                ]
            },
            "footer": {
                "text": "Спасибо за интерес"
            }
        },
        "category": "MARKETING",
        "type": "OPERATOR"
    },
    "subjectIds": [
        20526
    ]
}

WhatsApp HSM с кнопками:

{
    "messageMatcher": {
        "name": "new_matcher",
        "channelType": "WHATSAPP",
        "language": "RU",
        "content": {
            "header": {
                "text": "Ваш чат с edna"
            },
            "text": "Здравствуйте! Спасибо, что выбрали нас.",
            "keyboard": {
                "rows": [
                    {
                        "buttons": [
                            {
                                "text": "Да",
                                "buttonType": "QUICK_REPLY",
                                "payload": "1"
                            },
                            {
                                "text": "Нет",
                                "buttonType": "QUICK_REPLY",
                                "payload": "2"
                            },
                            {
                                "text": "Не знаю",
                                "buttonType": "QUICK_REPLY",
                                "payload": "3"
                            }
                        ]
                    }
                ]
            }
        },
        "category": "MARKETING",
        "type": "OPERATOR"
    },
    "subjectIds": [
        20526
    ]
}

Viber:

{
    "messageMatcher": {
        "name": "new_matcher",
        "channelType": "VIBER",
        "language": "RU",
        "content": {
            "text": "Здравствуйте, %w{1,5}! Спасибо, что выбрали нас."
        },
        "category": "TRANSACTIONAL",
        "type": "OPERATOR"
    },
    "subjectIds": [
        2234
    ]
}

SMS:

{
    "messageMatcher": {
        "name": "new_matcher",
        "channelType": "SMS",
        "language": "RU",
        "content": {
            "text": "Здравствуйте, %w{1,5}! Спасибо, что выбрали нас."
        },
        "category": "MARKETING",
        "type": "OPERATOR",
        "createdAt": "2022-05-05T11:34:34.844Z",
        "updatedAt": "2022-05-05T11:34:34.844Z"
    },
    "subjectIds": [
        2234
    ],
    "smsProviderCodes": "beeline"
}

{{1}}, [\s\w]+ и %w{1,n} — это символы элементов автоподстановки, то есть строки символов, вместо которых можно указывать любые значения. У каждого провайдера свои правила использования этих элементов. Подробнее читайте в статьях SMS, Viber, WhatsApp.

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

Формат ответа

В ответ на запрос возвращается JSON-объект, содержащий код выполнения запроса.

Коды ответов на запрос

Код	Описание
`ok`	Запрос выполнен успешно.
`must not be null`	Не указана категория шаблона WhatsApp.
`message-matcher-category-invalid`	Указана неверная категория шаблона WhatsApp. Возможные категории: • `MARKETING` • `AUTHENTICATION` • `UTILITY`
`message-matcher.saving.bad-request`	Пример динамической ссылки для шаблона WhatsApp не указан или указан неверно.
`message-matcher-name-already-exists`	Шаблон с таким названием уже существует.
`message-matcher.saving.already-exists`	Шаблон с таким содержанием уже существует.
`invalid language`	Указан неверный код языка шаблона.
`validation failure`	Ошибка валидации шаблона WhatsApp.

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

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