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

19 February 2025

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

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

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

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

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

{
    "messageMatcher": {
        "id": 0,
        "name": "string",
        "channelType": "SMS",
        "language": "string",
        "content": {
            "attachment": {
                "id": 0,
                "fileUrl": "string",
                "originalFileName": "string",
                "size": 0
            },
            "action": "string",
            "caption": "string",
            "header": {
                "headerType": "TEXT",
                "text": "string",
                "attachment": {
                    "id": 0,
                    "fileUrl": "string",
                    "originalFileName": "string",
                    "size": 0
                },
                "headerExampleTextParam": "string",
                "headerExampleMediaUrl": "string"
            },
            "text": "string",
            "footer": {
                "text": "string"
            },
            "keyboard": {
                "rows": [
                    {
                        "buttons": [
                            {
                                "text": "string",
                                "buttonType": "PHONE",
                                "otpType": "COPY_CODE",
                                "url": "string",
                                "urlPostfix": "string",
                                "phone": "string",
                                "payload": "string",
                                "urlTextExample": "string",
                                "color": "string",
                                "requestContact": true,
                                "requestLocation": true,
                                "autofillText": "string",
                                "packageName": "string",
                                "hash": "string",
                                "appId": 0,
                                "ownerId": 0
                            }
                        ]
                    }
                ]
            },
            "securityRecommendation": true,
            "codeExpirationMinutes": 0,
            "textExampleParams": [
                "string"
            ],
            "vkAttachments": [
                {
                    "id": 0,
                    "fileUrl": "string",
                    "originalFileName": "string",
                    "size": 0
                }
            ],
            "vkTwoWayEnabled": true
        },
        "contentType": "TEXT",
        "category": "ACCOUNT_UPDATE",
        "status": "string",
        "locked": true,
        "type": "OPERATOR",
        "createdAt": "2024-07-08T13:47:37.602Z",
        "updatedAt": "2024-07-08T13:47:37.602Z"
    },
    "subjectIds": [
        0
    ],
    "smsProviderCodes": [
        "string"
    ]
}

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

ПараметрТип данныхХарактерОписание
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Обязательный, если передается content.headerТип заголовка.

Возможные значения:
• 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		array of objectsНеобязательныйМассив объектов с информацией о кнопках.
Максимально допустимое количество кнопок в шаблоне — 10.
content.keyboard.rows.
buttons.text		stringНеобязательныйНазвание кнопки.
content.keyboard.rows.
buttons.buttonType		stringНеобязательныйТип кнопки.

Возможные значения:
• PHONE — кнопка-звонок;
• URL — кнопка-ссылка;
• QUICK_REPLY — кнопка быстрого ответа.

Максимально допустимое количество кнопок-ссылок в шаблоне — 2.
Максимально допустимое количество кнопок-звонков в шаблоне — 1.
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Код или текст кнопки быстрого ответа. Максимальное количество символов – 128.
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 — сообщение с видео.
categorystringОбязательныйКатегория шаблона.

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

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

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

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

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

ОграничениеОписание
КаналыСозданный шаблон можно использовать на всех каналах, привязанных к выбранному аккаунту WhatsApp Business.
Название шаблонаВ названии можно использовать только латинские буквы, цифры и символ (_). Использование пробелов и других символов не допускается.
ВложенияВозможные типы вложений:
• изображение (JPEG, JPG, PNG);
• видео (MP4, 3GPP, 3GPP);
• документ (PDF).

Можно выбрать только один тип вложения для отправки в шаблоне.
Текст сообщения шаблона• Поле с текстом обязательно для заполнения.
• Максимальное количество символов в тексте сообщения с учетом текста в строке символов — 1024. В дополнение к тексту допускается использование переменных.
• Текст не должен содержать символов новой строки.
• Текст не должен содержать символов 4-х и более последовательных пробелов.
Переменные в тексте сообщения• Переменная не должна содержать перенос строки. При использовании переноса изменения не сохраняются.
• Максимальное количество символов в значении переменной — 512. 
• Переменные должны быть указаны с двумя двойными фигурными скобками в начале и в конце.
• Использование одинарных скобок не допускается.
Текстовый заголовок• Поля с текстом и типом заголовка обязательны для заполнения.
• Максимальное количество символов в текстовом заголовке — 60.
• В текстовый заголовок можно добавить одну переменную.
• В начале и в конце заголовка нельзя использовать пробелы.
Подпись• Поле с подписью обязательно для заполнения.
• Максимальное количество символов в подписи — 60.
• Использование переменных не допускается.
• В начале и в конце подписи нельзя использовать пробелы.
Кнопки• Максимальное количество символов в названии кнопки — 25.
• При добавлении кнопки должен быть указан ее тип, все поля обязательны для заполнения.
Кнопка Быстрый ответ (QUICK_REPLY)• Название кнопки согласуется вместе с текстом шаблона без возможности изменения в настройках.
• Максимальное количество символов в коде кнопки — 128.
• В одном шаблоне может быть не более 10 кнопок этого типа.
• После нажатия открывается 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}}",
                "headerType":"TEXT",
                "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",
                "headerType": "TEXT"
            },
            "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-объект, содержащий код выполнения запроса.

Ошибки

КодОшибкаОписание
400must not be nullНе указана категория шаблона WhatsApp.
400message-matcher-category-invalidУказана неверная категория шаблона WhatsApp.

Возможные категории:
• MARKETING
• UTILITY
400message-matcher.saving.bad-requestНекорректно заполнены поля в запросе.
Возможные комментарии:

• Пример динамической ссылки для шаблона WhatsApp не указан или указан неверно.
• Field content.buttons.payload - QUICK_REPLY button payload length must not exceed 128 – Превышена длина поля кода кнопки быстрого ответа payload, максимальное количество символов — 128.
400message-matcher-name-already-existsШаблон с таким названием уже существует. Возможный комментарий:

• Message matcher with specified channel type, tenantId and name already exists
Шаблон с таким типом канала и именем уже существует.
400message-matcher.saving.already-existsШаблон с таким содержанием уже существует.
400invalid languageУказан неверный код языка шаблона.
400validation failureОшибка валидации шаблона WhatsApp.

Возникает, если в шаблоне WhatsApp превышено максимально допустимое количество кнопок. Возможные комментарии:

• Field content.buttons - Buttons max allowed count is 10
Максимальное количество кнопок в шаблоне — 10.
• Field content.buttons - URL buttons max allowed count is 2
Максимальное количество кнопок-ссылок в шаблоне — 2.
• Field content.buttons - PHONE buttons max allowed count is 1
Максимальное количество кнопок-звонков в шаблоне — 1.
* Деятельность компании Meta запрещена на территории Российской Федерации.
In this article
In this article