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

Обновлено: 15 июля 2025

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

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

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

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

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

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

Параметр	Тип данных	Характер	Описание
language	string	Обязательный	Язык шаблона в формате WhatsApp Business Platform. WhatsApp Поддерживаемые языки перечислены в документации Meta*. developers.facebook.com
content	object	Обязательный	Объект с содержимым шаблона.
content.attachment	object	Необязательный	Объект с информацией о вложении.
content.attachment.fileUrl	string	Необязательный	URL-адрес файла.
content.attachment.originalFileName	string	Необязательный	Имя файла.
content.header	object	Необязательный	Объект с информацией о заголовке.
content.header.headerType	string	Обязательный, если передается content.header	Тип заголовка: 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	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 = 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	Код или текст кнопки быстрого ответа. Максимальное количество символов – 128.
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 — сообщение с видео.
category	string	Обязательный	Категория шаблона. - MARKETING — новости о компании, предложения с акциями и скидками, информация о мероприятиях и вебинарах; - UTILITY — информация об изменениях в учетной записи, статусе заказа или программе лояльности, уведомление о получении платежа, подтверждение денежных переводов, прочие транзакции в сфере финансовых услуг.
type	string	Обязательный	Тип шаблона. - OPERATOR — операторский шаблон, зарегистрированный у оператора связи; - USER — пользовательский шаблон, созданный пользователем на основе операторского. Поддерживается только тип шаблона OPERATOR.
messageTtl	string, integer	Необязательный	Время жизни сообщения WhatsApp, установленное в шаблоне. Только для шаблона категории UTILITY. Поддерживаемые типы данных: - строка или число для записи в секундах (например, 3600); - строка в формате даты ISO 8601 durations (например, «PT10H15M48S»). Возможные значения — от 30 секунд до 12 часов. Значение по умолчанию, установленное на стороне Meta* — 30 суток. Чтобы применить его, оставьте поле пустым. WhatsApp Подробнее про TTL для шаблонных сообщений читайте в документации Meta*: developers.facebook.com

подсказка

Если вы зарегистрируете на один бизнес-аккаунт два и более одинаковых по содержанию шаблона, но с разными значениями TTL, то при отправке сообщений из личного кабинета edna Pulse и по методу API api/cascade/schedule сообщения будут сопоставляться с тем шаблоном, который был создан раньше остальных.

Чтобы избежать таких ситуаций, войдите в личный кабинет Facebook Business Manager* и отключите неиспользуемый шаблон или отправьте запрос на отключение шаблона в службу поддержки edna с пояснением причины.

Валидация шаблонов 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

Параметр	Тип данных	Характер	Описание
language	string	Обязательный	Язык шаблона в формате ISO 639-1. localizely.com
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}}",
                "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
    ]
}

WhatsApp HSM с параметром TTL

{
    "messageMatcher": {
        "name": "utility_test",
        "channelType": "WHATSAPP",
        "language": "RU",
        "content": {
            "text": "Привет! Заберите заказ в пункте выдачи"
        },
        "category": "UTILITY",
        "type": "OPERATOR",
        "messageTtl": 36000
    },
    "subjectIds": [
        145
    ]
}

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

Операторские шаблоны для WhatsAppОператорские шаблоны для ViberОператорские шаблоны для SMS

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

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

Ответ на запрос создания операторского шаблона WhatsApp HSM с параметром TTL:

{
    "id": 10,
    "name": "utility_test",
    "channelType": "WHATSAPP",
    "language": "RU",
    "content": {
        "attachment": null,
        "action": null,
        "caption": null,
        "header": null,
        "text": "Привет! Заберите заказ в пункте выдачи",
        "footer": null,
        "keyboard": {
            "rows": []
        },
        "securityRecommendation": null,
        "codeExpirationMinutes": null,
        "textExampleParams": null,
        "vkAttachments": null,
        "vkTwoWayEnabled": null
    },
    "contentType": "TEXT",
    "category": "UTILITY",
    "status": "PENDING",
    "locked": false,
    "type": "OPERATOR",
    "createdAt": null,
    "updatedAt": null,
    "messageTtl": "PT10H"
}

Коды ошибок

Код	Ошибка	Описание	Возможные комментарии
400	must not be null	Не указана категория шаблона WhatsApp.	—
400	message-matcher-category-invalid	Указана неверная категория шаблона WhatsApp.	—
400	message-matcher.saving.bad-request	Некорректно заполнены поля в запросе.	- Пример динамической ссылки для шаблона WhatsApp не указан или указан неверно. - Field content.buttons.payload - QUICK_REPLY button payload length must not exceed 128 — Превышена длина поля кода кнопки быстрого ответа payload. Максимальное количество символов — 128. - Field content.text - Invalid symbols in text. More than 2 consecutive \n or \r — Превышено количество символов новой строки (переносов) в тексте шаблона. Максимальное количество переносов — не более двух подряд.
400	message-matcher-name-already-exists	Шаблон с таким названием уже существует.	Message matcher with specified channel type, tenantId and name already exists — Шаблон с таким типом канала и именем уже существует.
400	message-matcher.saving.already-exists	Шаблон с таким содержанием уже существует.	—
400	invalid language	Указан неверный код языка шаблона.	—
400	validation 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 запрещена на территории Российской Федерации.