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

Обновлено: 19 февраля 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. 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`.

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

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"
}

info

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

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

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

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

Коды ошибок

Код	Ошибка	Описание	Возможные комментарии
`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.
`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.

danger

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

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

Формат запроса​

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

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

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

Каналы​

Название шаблона​

Вложения​

Текст сообщения шаблона​

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

Текстовый заголовок​

Подпись​

Кнопки​

Кнопка Быстрый ответ QUICK_REPLY​

Кнопка Ссылка URL​

Кнопка Номер PHONE_NUMBER​

Текст-заполнитель​

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

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

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

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

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

Viber​

SMS​

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

Коды ошибок​