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

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

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

Чтобы вызвать метод api/message-matchers, отправьте POST-запрос на URL-адрес https://app.edna.by/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
    ]
}

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

ПараметрТип данныхХарактерОписание
namestringОбязательныйНазвание шаблона. В нем могут быть только латинские буквы, цифры и подчеркивание (_).

Максимальное количество символов — 60.
channelTypestringОбязательныйТип канала, для которого надо создать операторский шаблон.

Возможные значения:
WHATSAPP — канал WhatsApp;
VIBER — канал Viber;
SMS — канал SMS.
subjectIdsintegerОбязательныйМассив идентификаторов подписи, для которых создается шаблон. Чтобы узнать идентификатор подписи канала, используйте метод получения списка каналов.

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

ПараметрТип данныхХарактерОписание
languagestringОбязательныйЯзык шаблона в формате WhatsApp Business Platform.

Список поддерживаемых языков смотрите на официальном сайте Meta*.
contentobjectОбязательныйОбъект с содержимым шаблона.
content.attachmentobjectНеобязательныйОбъект с информацией о вложении.
content.attachment.
fileUrl
stringНеобязательныйURL-адрес файла.
content.attachment.
originalFileName
stringНеобязательныйИмя файла.
content.headerobjectНеобязательныйОбъект с информацией о заголовке.
content.header.headerTypestringОбязательный (внутренний API-интерфейс)
Необязательный (публичный API-интерфейс)
Тип заголовка.

Возможные значения:
• TEXT — текст;
• IMAGE — изображение;
• VIDEO — видео;
• DOCUMENT — файл.
content.header.textstringНеобязательныйТекст заголовка.
content.header.attachmentobjectНеобязательныйОбъект с информацией о файле в заголовке.
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.textstringОбязательныйТекст сообщения.
content.footerobjectНеобязательныйОбъект с информацией о подписи.
content.footer.textstringНеобязательныйТекст подписи.
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 = URLURL-адрес, который открывается при нажатии кнопки.
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.textExampleParamsarray of stringsОбязательный, если channelType = WHATSAPP и content.text содержит переменныеПример на каждую переменную в параметре content.text.
contentTypestringНеобязательныйТип содержимого.

Возможные значения:
• TEXT — текстовое сообщение;
• IMAGE — изображение;
• BUTTON — кнопка;
• DOCUMENT — файл, вложенный в сообщение;
• LOCATION — сообщение с координатами, адресом и описанием места (координаты преобразуются в снимок Google Maps);
• AUDIO — сообщение с аудио;
• VIDEO — сообщение с видео;
• AUTHENTICATION — сообщение с одноразовым паролем.
categorystringОбязательныйКатегория шаблона.

Возможные значения:
MARKETING — новости о компании, предложения с акциями и скидками, информация о мероприятиях и вебинарах;
AUTHENTICATION — коды для личного кабинета или приложения для безопасного доступ к учетным записям пользователей, обновление данных или настроек учетной записи, окончание подписки, изменение пароля;
UTILITY — информация об изменениях в учетной записи, статусе заказа или программе лояльности, уведомление о получении платежа, подтверждение денежных переводов, прочие транзакции в сфере финансовых услуг.

Создание шаблонов категории AUTHENTICATION временно ограничено.
typestringОбязательныйТип шаблона.

Возможные значения:
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

ПараметрТип данныхХарактерОписание
languagestringОбязательныйЯзык шаблона в формате ISO 639-1.
contentobjectОбязательныйОбъект с содержимым шаблона.
content.actionstringНеобязательныйURL-адрес кнопки.
content.captionstringНеобязательныйНазвание кнопки.
content.textstringОбязательныйТекст сообщения.
contentTypestringНеобязательныйТип содержимого.

Возможные значения:
TEXT — текстовое сообщение.
categorystringОбязательныйКатегория шаблона.

Возможные значения:
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
typestringОбязательныйТип шаблона.

Возможные значения:
OPERATOR — операторский шаблон, зарегистрированный у оператора связи;
USER — пользовательский шаблон, созданный пользователем на основе операторского;
• CUSTOM — свободный шаблон с разрешенным для указанного канала контентом.

Поддерживается только тип OPERATOR.

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

ПараметрТип данныхХарактерОписание
contentobjectОбязательныйОбъект с содержимым шаблона.
content.textstringОбязательныйТекст сообщения.
typestringОбязательныйТип шаблона.

Возможные значения:
OPERATOR — операторский шаблон, зарегистрированный у оператора связи.
smsProviderCodesstringОбязательныйНазвания операторов связи, для которых регистрируется шаблон SMS.

Возможные значения:
mts — МТС;
megafon — Мегафон;
tele2— Тele2;
beeline — Билайн;
motiv — Мотив.
categorystringОбязательныйКатегория шаблона.

Возможные значения: 
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} — это символы элементов автоподстановки, вместо которых можно указывать любые значения. У каждого провайдера свои правила использования этих элементов.

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

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

В ответ на запрос возвращается 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.