# Шаблоны WABA ## Создание шаблона Создание шаблона описано[ в документации API ](https://1msg-docs.web.app/ru#tag/Shablony/operation/addTemplate)в методе /addTemplate. Вы также можете создать шаблон через раздел в личном кабинете "Кабинет разработчика" → ["Тестирование запросов"](https://my.1msg.io/testing/test-requests). Общая часть запроса:
nameНазвание шаблона. name может содержать только строчные латинские буквы, цифры и символ подчеркивания.
allow_category_changeФлажок "Разрешить изменение категории". Вместо отклонения шаблона мы изменим его тип категории автоматически.
categoryТип шаблона: маркетинг (MARKETING), услуга (UTILITY) или аутентификация (AUTHENTICATION)
languageЯзык шаблона. Выбранный язык должен совпадать с текстом внутри создаваемого шаблона, иначе шаблон Meta может отклонить.
componentsМассив компонентов Шаблона
Пример: ```json { "token": "{{token}}", "name": "test_marketing_2024", "allow_category_change": false, "category": "MARKETING", "language": "ru", "components": [ //тут объекты тела шаблона ] } ``` Рассмотрим далее структуру категории шаблонов. ### Шаблоны Маркетинг и Услуги

Структура шаблона

#### HEADER Правила заполнения заголовка * Заголовок необязателен к заполнению * Можно выбрать только один из типов: `TEXT`, `IMAGE`, `VIDEO` или `DOCUMENT` Далее в нижней таблице опишем каждый тип. {% tabs %} {% tab title="TEXT" %} Укажите "format": "TEXT", чтобы определить заголовок в виде текста. Сам текст заполняется в свойстве "text ". Правила заполнения текстового заголовка: * text - может содержать до 60 символов. * В text можно добавить только одну переменную. * Если заголовок имеет переменную, то обязательно нужно указывать пример example в header\_text. Пример текста без переменной: 
{
    "type": "HEADER",
    "format": "TEXT",
    "text": "Hello"
}
Пример текста с переменной: ```json { "type": "HEADER", "format": "TEXT", "text": "Our {{1}} is on!", "example": { "header_text": [ "Summer Sale" // пример переменной {{1}} ] } } ``` {% endtab %} {% tab title="IMAGE " %} Укажите "format": "IMAGE", чтобы в заголовке вывести изображение. Обязательно выводить объект "example" с указанием ссылки на картинку в "header\_handle". ```json { "type": "HEADER", "format": "IMAGE", "example": { "header_handle": [ "https://img-example-link.com/delicious-orange-23.jpg" ] } } ``` {% endtab %} {% tab title="VIDEO" %} Укажите "format": "VIDEO", чтобы в заголовке вывести видео. Обязательно выводить объект "example" с указанием ссылки на видео в "header\_handle". ```json { "type": "HEADER", "format": "VIDEO", "example": { "header_handle": [ "https://video-example-link.com//banner.mp4" ] } } ``` {% endtab %} {% tab title="DOCUMENT" %} Укажите "format": "DOCUMENT", чтобы в заголовке вывести документ. Обязательно выводить объект "example" с указанием ссылки на документ в "header\_handle". ```json { "type": "HEADER", "format": "DOCUMENT", "example": { "header_handle": [ "https://doc-example-link.com/reyshi.pdf" ] } } ``` {% endtab %} {% endtabs %} #### BODY Тело сообщения представляет собой только текстовые компоненты и необходим для всех шаблонов. Шаблон ограничен одним компонентом BODY. Правила заполнения BODY: * Обязателен для заполнения. * text - может содержать до 1024 символов. * Если есть переменные в text, то необходимо обязательно указать примеры переменных в `"example"` в массив `"body_text"`. Количество строк внутри`body_text` должно соответствовать количеству переменных, включенных в строку text. * от Meta нет ограничений на количество переменных. * Нельзя указывать в тексте только переменную, т.е. Meta не примет формат текста "text": "{{1}}" ```json { "type": "BODY", "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.", "example": { // не нужно указывать, если не будет переменных в text "body_text": [ [ "the end of August", // пример первой переменной "25OFF", // пример второй переменной "25%" // пример третьей переменной ] ] } } ``` #### FOOTER Футер или нижний колонтитул — необязательный для заполнения текст, который появляются ниже основного сообщения. Не поддерживает переменные, вмещает до 60 символов. ```json { "type": "FOOTER", "text": "text for footer" } ``` #### BUTTONS Кнопки — это интерактивные компоненты, которые при нажатии выполняют определенные действия. Шаблоны могут содержать до 10 кнопок, но есть ограничения на использование определенных типов кнопок, а также ограничения на комбинации. **Какие бывают кнопки:** * **Кнопка быстрого ответа.** Текстовая кнопка, при клике на которую сразу отправляется в чат с вами ответ с текстом, повторяющим текст кнопки. Текст кнопки можно писать любой. * **Кнопка с ссылкой.** Кнопка при клике ведет на url, который вы укажите. Ссылка может быть полностью статичной либо содержать переменную. Если вы указываете переменную, то она обязательно должна быть в конце url-ссылки. URL-ссылка не поддерживает кириллицу, но текст самой кнопки - поддерживает. * **Кнопка с номером телефона.** При нажатии производится вызов на указанный номер телефона. * **Кнопка каталог** (доступен только в категории Маркетинг). Кнопка, при клике на которую открывается ваш каталог. Ваш клиент сможет сделать заказ, список отправленных товаров или услуг появится у вас в чате. Кнопка с ссылками и номером телефона при клике не отправляет ответ в чат, как это делает кнопка быстрого ответа. **Ограничение на количество:** * Максимальное количество кнопок типа Quick Reply - 10 кнопок. * Максимальное количество кнопок типа URL - 2 кнопки. * Максимальное количество кнопок типа Phone - 1 кнопка. * В шаблоне "Каталог" можно использовать только одну кнопку - кнопку каталога. * Всего в шаблоне может быть не более 10 кнопок. Комбинации описаны ниже:
Как можноКак нельзя
  • Quick Reply, Quick Reply, Quick Reply
  • Quick Reply, Quick Reply, Quick Reply, URL, Phone
  • URL, Phone, Quick Reply, Quick Reply
  • Quick Reply, URL, Quick Reply
  • URL, Quick Reply, URL
Как видно, необходимо учитывать последовательность ввода типа кнопок и допустимое количество. Т.е. нельзя добавить кнопку Quick Reply в начале, потом добавить кнопку URL и снова Quick Reply. {% tabs %} {% tab title="QUICK REPLY" %} Кнопка быстрого ответа - текстовая кнопка, при клике на которую сразу отправляется в чат с вами ответ с текстом, повторяющим текст кнопки. Текст кнопки можно писать любой. Максимальное количество символов - 25. ```json { "type": "QUICK_REPLY", "text": "Yes" } ``` {% endtab %} {% tab title="URL" %} Свойство "text" - текст на кнопке. Максимальное количество символов - 25. Свойство "url" может быть полностью статичной либо содержать одну переменную. Если вы указываете переменную, то она обязательно должна быть в конце url-ссылки. Максимальное количество символов - 2000. Свойство "url" не поддерживает кириллицу. Если указываете переменную, обязательно нужно указать пример в "example". ```json { "type": "URL", "text": "Shop Now", "url": "https://www.luckyshrub.com/shop?promo={{1}}", "example": [ // заполняется, если добавлена переменная в url "summer2023" // переменная {{1}} ] } ``` {% endtab %} {% tab title="PHONE NUMBER" %} phone\_number - номер рабочего телефона, на который будет совершен звонок, когда пользователь нажимает кнопку. Максимальное количество символов - 20. text - текст на кнопке. Максимальное количество символов - 25. phone\_number и text - обязательны для заполнения. ```json { "type": "PHONE_NUMBER", "text": "my number", "phone_number": "77777777777" } ``` {% endtab %} {% tab title="CATALOG" %} В шаблоне "Каталог" можно добавить только одну кнопку. В "text" обязательно необходимо писать "View catalog". В зависимости от языка шаблона текст кнопки будет переводиться на указанный язык. ```json { "type": "CATALOG", "text": "View catalog" } ``` {% endtab %} {% endtabs %}
Полный пример создания маркетингового шаблона Пример запроса на создание маркетингового шаблона со следующими компонентами: * текстовый заголовок с переменной и примером значения * текстовое тело с переменными и примерами значений * текстовый нижний колонтитул * две кнопки быстрого ответа ```json { "token": "{{token}}", "name": "test_marketing_2024", "allow_category_change": false, "category": "MARKETING", "language": "ru", "components": [ { "type": "HEADER", "format": "TEXT", "text": "Our {{1}} is on!", "example": { "header_text": [ "Summer Sale" ] } }, { "type": "BODY", "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.", "example": { "body_text": [ [ "the end of August","25OFF","25%" ] ] } }, { "type": "FOOTER", "text": "Use the buttons below to manage your marketing subscriptions" }, { "type":"BUTTONS", "buttons": [ { "type": "QUICK_REPLY", "text": "Unsubscribe from Promos" }, { "type":"QUICK_REPLY", "text": "Unsubscribe from All" } ] } ] }' ```
### Шаблон Аутентификации

Структура шаблона

Шаблон аутентификации должен включать обязательно BODY и BUTTONS. Кнопки могут быть двух видов: кнопка копирования кода либо кнопка автозаполнения в одно касание. {% tabs %} {% tab title="BODY" %} Текст в BODY фиксирован от Meta, не заполняйте свойство "text". Язык текста, отображаемый у пользователя, зависит от выбранного языка шаблона. Если хотите добавить текст "Из соображений безопасности не сообщайте код никому" , выставьте "add\_security\_recommendation": true. Установите значение false, чтобы исключить строку. ```json { "type": "BODY", "add_security_recommendation": true } ``` {% endtab %} {% tab title="FOOTER" %} FOOTER не обязателен к заполнению . В footer можно добавить текст о времени истечения кода в минутах. Для этого укажите целое число в "code\_expiration\_minutes". Можно указать минуты от 1 до 90. Если этот параметр опущен, предупреждение об истечении срока действия кода не будет отображаться в доставленном сообщении ```json { "type": "FOOTER", "code_expiration_minutes": 5 } ``` {% endtab %} {% tab title="BUTTONS" %} Шаблоны аутентификации должны включать либо кнопку копирования кода, либо кнопку автозаполнения в одно касание. У данных кнопок "type": "OTP" Свойство "otp\_type" - указывает тип кнопки. Установите значение COPY\_CODE, если вы хотите, чтобы в шаблоне использовалась кнопка копирования кода, или ONE\_TAP, чтобы он использовал кнопку автозаполнения одним нажатием. Можно указать только одну кнопку. Свойство "text" обязателен для заполнения и для типа COPY\_CODE и для ONE\_TAP. Если по какой то причине Meta не сможет завалидировать кнопку в одно касание, отправит кнопку с типом COPY\_CODE. Максимальное количество символов - 25. Для типа ONE\_TAP нужно заполнить еще следующие поля: * autofill\_text - текст на кнопке одним касанием. Максимум 25 символов. * package\_name - название пакета вашего Android-приложения * signature\_hash - хэш ключа подписи вашего приложения. Пример кнопки копирования кода: ```json { "type": "BUTTONS", "buttons": [ { "type": "OTP", "otp_type": "COPY_CODE", "text": "Скопировать" } ] } ``` Пример кнопки автозаполнения в одно касание: ```json { "type": "BUTTONS", "buttons": [ { "type": "OTP", "otp_type": "ONE_TAP", "text": "Copy Code", "autofill_text": "Autofill", // One-tap buttons only "package_name": "com.example.myapplication", // One-tap buttons only "signature_hash": "K8a%2FAINcGX7" // One-tap buttons only } ] } ``` {% endtab %} {% endtabs %}
Полный пример отправки шаблона Аутентификация ```json { "token": "{{token}}", "name": "auth_2024", "allow_category_change": false, "category": "AUTHENTICATION", "language": "ru", "components": [ { "type": "BODY", "add_security_recommendation": true }, { "type": "FOOTER", "code_expiration_minutes": 5 }, { "type": "BUTTONS", "buttons": [ { "type": "OTP", "otp_type": "COPY_CODE", "text": "Copy Code" } ] } ] } ```
## Отправка шаблона Отправка шаблона описана в [документации API ](https://1msg-docs.web.app/ru#tag/Shablony/operation/sendTemplate)в методе /sendTemplate. Вы также можете отправить шаблон через раздел в личном кабинете "Кабинет разработчика" →["Тестирование запросов". ](https://my.1msg.io/testing/test-requests)Чтобы отправить шаблон, необходимо знать namespace, name и language шаблона. Чтобы получить эти данные, вызовите метод "Получить список шаблонов" (/templates). Некоторые свойства, которые могут вызвать вопросы в методе /sendTemplate. | Свойства | Описание | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | template | Это name шаблона | | language |

policy: записывайте deterministiс

code: код language из метода /templates

| | Объект с type "body" | Текстовое сообщение. Можно опустить, если в тексте нет переменных. | | Объект с type "button" |

Вам нужно указывать в теле только кнопки с sub\_type "url" либо "catalog". Остальные типы кнопок при отправке шаблона можно опустить.

Положение кнопок для каждой карточки в шаблоне "Карусель" должно быть одинаково

| ### Отправить шаблоны Маркетинга или Услуги В запросах нужно отправлять только те объекты, которые указаны в созданном шаблоне. Например, если в шаблоне изначально нет объекта header, то и указывать его при отправке не надо. А также опускаются объекты, если: * Объект header с типом `text` без переменной; * Body без переменной; * Кнопки быстрого ответа и Кнопка с номером опускаются всегда; * URL-кнопка без переменной. В header с типом `IMAGE`, `VIDEO`, `DOCUMENT` всегда указывается полная ссылка на медиа-документ. Обратите внимание, что ссылка на медиа-документ должна содержать формат документа.
Пример отправки Документа с URL кнопкой Структура: * Заголовок содержит документ * тело сообщения содержит 2 переменные * Две URL-кнопки, вторая URL кнопка содержит переменную. Если URL-кнопка не имеет переменной, опускайте ее из запроса. Например, в этом запросе первая URL-кнопка c индексом 0 пропущена, а вторая - выведена. Обратите также внимание, что индекс второй кнопки уже 1. ```json { "token": "{{token}}", "namespace": "{{namespace}}", "template": "delivery_tracking", "language": { "policy": "deterministic", "code": "ru" }, "params": [ { "type": "header", "parameters": [ { "type": "document", //объект документа "document": { "link": "https://test.com/reyshi.pdf" //ссылка на документ. Обратите внимение, чтобы в ссылке был указан формат документа } } ] }, { "type": "body", "parameters": [ { "type": "text", "text": "Андрей" // первая переменная в BODY }, { "type": "text", "text": "№003478" // вторая переменная в BODY } ] }, { "type": "button", // вторая URL-кнопка "sub_type": "url", "index":1, // индексы нумеруются с нуля, у второй кнопки индекс 1 "parameters": [ { "type": "text", "text": "/reyshi" //переменная ссылки } ] } ], "phone": "{{phone}}" } ```
Пример отправки Текстового заголовка со всеми типами кнопок Структура: * Текстовый заголовок с одной переменной * Тело сообщения не содержит переменной. Поэтому в запросе опущен. * 4 кнопки. Первая кнопка - быстрый ответ, вторая кнопка - звонок, третья кнопка - URL-кнопка с переменной, четвертая кнопка - URL-кнопка без переменной. ```json { "token": "{{token}}", "namespace": "{{namespace}}", "template": "utility_all_buttons_2024_05", "language": { "policy": "deterministic", "code": "en" }, "params": [ { "type": "header", "parameters": [ { "type": "text", "text": "Anna" // переменная заголовка } ] }, { "type": "button", // третья кнопка, URL-кнопка с переменной "sub_type": "url", "index": 2, // индекс третьей кнопки "parameters": [ { "type": "text", "text": "inbox" // переменная ссылки } ] } ], "phone": "{{phone}}" } ```
### Отправить шаблон Аутентификации
Пример отправки шаблона Аутентификации Пример отправки кнопки копирования кода ```json { "token": "{{token}}", "namespace": "{{namespace}}", "template": "auth_2", "language": { "policy": "deterministic", "code": "ru" }, "params": [ { "type": "body", "parameters": [ { "type": "text", "text": "05425" // код, отображаемый в теле сообщения } ] }, { "type": "BUTTON", "sub_type": "URL", "index": 0, "parameters": [ { "type": "TEXT", "text": "05425" // код, который будет скопирован } ] } ], "phone": "+556123122026" } ```
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.1msg.io/docs/russkii/api-1msg/shablony-waba.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.