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

Обновлено: 7 октября 2026

Для запроса на создание операторского шаблона используется метод /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"
    ]
}

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

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

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

Параметр	Тип данных	Характер	Описание
language	string	Обязательный	Язык шаблона в формате WhatsApp Business Platform. Поддерживаемые языки перечислены в документации 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, number	Необязательный	Время жизни сообщения 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

Параметр	Тип данных	Характер	Описание
messageMatcher.language	string	Обязательный	Язык шаблона в формате ISO 639-1. localizely.com
messageMatcher.content	object	Обязательный	Объект с информацией о содержимом шаблона сообщения. В операторских шаблонах Viber поддерживаются только текст и текст с переменными. Другие типы контента не поддерживаются.
messageMatcher.content.text	string	Обязательный	Текст шаблона сообщения.
messageMatcher.type	string	Обязательный	Тип шаблона. Возможные значения: - OPERATOR — операторский шаблон, зарегистрированный у оператора или провайдера. Поддерживается только значение OPERATOR.
messageMatcher.variableNames	array of strings	Обязательный, если messageMatcher.content.text содержит переменные	Переменные в тексте шаблона сообщения.
messageMatcher.textExampleParams	array of strings	Обязательный, если messageMatcher.content.text содержит переменные	Пример для каждой переменной в тексте шаблона сообщения.

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

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

Текст сообщения

• В операторском шаблоне можно использовать только текст и текст с переменными. Кнопки, изображения и файлы не поддерживаются.
• Максимальная длина текста шаблона — 1000 символов.
• В начале и конце текста шаблона нельзя помещать переменную или символы /, #, (, +, %, '.
• Перед переменной должен быть пробел.

Переменные в тексте сообщения

• Переменные обозначаются в шаблоне как {1}, {2}, {3} и т. д.
• В одном шаблоне можно использовать не более 8 переменных.
• Рекомендуемая длина значения вместо переменной — не более 125 символов.
• Не рекомендуется использовать ссылки вместо переменных.

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

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.io/{{1}}",
                                "urlTextExample": "https://edna.io/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": "viber_template",
        "channelType": "VIBER",
        "language": "RU",
        "content": {
        "text": "Добрый день, {{1}}. Ваш заказ {{2}} будет доставлен {{3}}. Спасибо, что выбрали нас!",
        "variableNames": ["name", "order", "date"],
        "textExampleParams": ["Василий", "56128793", "01.02"]
        },
        "type": "OPERATOR"
    },
    "subjectIds": [
        308
    ]
}

к сведению

{1}, {2} и {3} — это переменные в шаблоне. Они используются для передачи изменяемых значений, например, имени получателя, номера заказа или даты доставки. Правила использования переменных зависят от провайдера канала.

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

Примеры ответов

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

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

{
    "id": 17,
    "name": "viber_template",
    "channelType": "VIBER",
    "language": "RU",
    "content": {
        "attachment": null,
        "action": null,
        "caption": null,
        "header": null,
        "text": "Добрый день, {{1}}. Ваш заказ {{2}} будет доставлен {{3}}. Спасибо, что выбрали нас!",
        "footer": null,
        "keyboard": {
            "rows": []
        },
        "securityRecommendation": null,
        "codeExpirationMinutes": null,
        "textExampleParams": [
            "Alex",            
            "56128793",
            "01.02" 
        ],
        "variableNames": [
            "name",            
            "order",
            "date"
        ],
        "vkAttachments": null,
        "vkTwoWayEnabled": null,
        "requestCallPermission": null
    },
    "category": null,
    "status": "PENDING",
    "locked": false,
    "type": "OPERATOR",
    "createdAt": "2026-10-06T14:48:41.295Z",
    "updatedAt": "2026-10-06T14:48:41.295Z",
    "messageTtl": null,
    "contentType": "TEXT"
} 

Коды ошибок

Код	Ошибка	Описание	Возможные комментарии
400	must not be null	Не указана категория шаблона WhatsApp.	—
400	message-matcher-category-invalid	Указана неверная категория шаблона WhatsApp.	—
400	message-matcher.saving.bad-request	Некорректно заполнены поля в запросе.	- Field content.variableNames - Variable names and examples count must match the number of variables (N) — Количество имён переменных и их примеров должно соответствовать количеству переменных в тексте шаблона (N). - Field content.text - Maximum 8 variables allowed — Превышено максимально допустимое количество переменных в тексте шаблона. В одном шаблоне можно использовать не более 8 переменных. - Field content.text - Variables cannot be placed at the beginning or end of the text — Недопустимо размещать переменную в начале или в конце текста шаблона. - Field content.text - Text must not start or end with # ( + % ', Field content.text - Invalid symbols in text — Недопустимо использовать специальные символы #, (, +, %, ' в начале или в конце текста шаблона; также в тексте шаблона обнаружены недопустимые символы. - Field content.variableNames - Variable name [N] must contain only latin letters — Имя переменной [N] должно содержать только латинские буквы. - Field content.variableNames - Variable name [N] is not unique — Имена переменных [N] должны быть уникальными в рамках шаблона. - Field content.variableNames - Variable example [N] must not contain links — Значение примера переменной [N] не должно содержать ссылки. - Field content.text - Each variable must be preceded by a space — Перед и после каждой переменной должен стоять пробел. - 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.
400	message-matcher-category-not-allowed-for-viber	Для шаблонов Viber не должна быть указана категория.	- Category must not be specified for VIBER message-matcher [category:X;tenantId:1] — Для шаблона Viber не должна быть указана категория.
400	message-matcher-subject-invalid	В запросе используются некорректные идентификаторы каналов.	- Some of provided subjects are invalid (i.e. incorrect channel type or status) — Некоторые из указанных идентификаторов каналов недопустимы, например, из-за неподходящего типа или статуса канала.
400	message-matcher-type-not-supported-for-sms	Указанный тип шаблона не поддерживается для канала SMS.	- Only OPERATOR-type is supported for SMS message-matcher [tenantId:1;type:CUSTOM] — Для канала SMS по API можно зарегистрировать только операторский тип шаблона.