> For the complete documentation index, see [llms.txt](https://help.1msg.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.1msg.io/docs/russkii/api-1msg/shablony-waba.md). # Шаблоны 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" } ```