# Шаблоны WABA —  создание и отправка шаблона

## Создание шаблона

Создание шаблона описано[ в документации API ](https://1msg-docs.web.app/ru#tag/Shablony/operation/addTemplate)в методе /addTemplate.

Вы также можете создать шаблон через раздел в личном кабинете "Кабинет разработчика" → ["Тестирование запросов"](https://my.1msg.io/testing/test-requests).&#x20;

Общая часть запроса:&#x20;

<table data-header-hidden><thead><tr><th width="276"></th><th></th></tr></thead><tbody><tr><td>name</td><td>Название шаблона. name может содержать только строчные латинские буквы, цифры и символ подчеркивания. </td></tr><tr><td>allow_category_change</td><td>Флажок "Разрешить изменение категории". Вместо отклонения шаблона мы изменим его тип категории автоматически.</td></tr><tr><td>category</td><td>Тип шаблона:  маркетинг (MARKETING), услуга (UTILITY) или аутентификация (AUTHENTICATION)</td></tr><tr><td>language</td><td>Язык шаблона. Выбранный язык должен совпадать с текстом внутри создаваемого шаблона, иначе шаблон Meta может отклонить.</td></tr><tr><td>components</td><td>Массив компонентов Шаблона</td></tr></tbody></table>

Пример:&#x20;

```json
{
  "token": "{{token}}",
  "name": "test_marketing_2024",
  "allow_category_change": false,
  "category": "MARKETING",
  "language": "ru",
  "components": [
    //тут объекты тела шаблона 
  ]
}
```

Рассмотрим далее структуру категории шаблонов.&#x20;

### Шаблоны Маркетинг и Услуги&#x20;

<figure><img src="https://1775018921-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoCNwQHK1ya1FkEe495Vr%2Fuploads%2FkrVD5EpPjmsG5IsmTZ8S%2Fimage.png?alt=media&#x26;token=f40ab9a1-69a9-4cbc-9a0d-ad13b167b324" alt=""><figcaption><p>Структура шаблона</p></figcaption></figure>

#### HEADER

Правила заполнения заголовка

* Заголовок необязателен к заполнению
* Можно выбрать только один из типов: `TEXT`, `IMAGE`, `VIDEO` или `DOCUMENT`

Далее в нижней таблице опишем каждый тип.

{% tabs %}
{% tab title="TEXT" %}
Укажите "format": "TEXT",  чтобы определить заголовок в виде текста. Сам текст заполняется в свойстве "text ".

Правила заполнения текстового заголовка:

* text - может содержать до 60 символов.
* В text можно добавить только одну переменную.
* Если заголовок имеет переменную, то обязательно нужно указывать пример example в header\_text.&#x20;

Пример текста без переменной:

<pre class="language-json"><code class="lang-json">{
<strong>    "type": "HEADER",
</strong>    "format": "TEXT",
    "text": "Hello"
}
</code></pre>

Пример текста с переменной:

```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.&#x20;

Правила заполнения BODY:

* Обязателен для заполнения.
* text - может содержать до 1024 символов.
* Если есть переменные в text, то необходимо обязательно указать примеры переменных в  `"example"` в  массив `"body_text"`. Количество строк внутри`body_text` должно соответствовать количеству переменных, включенных в строку text.
* от Meta нет ограничений на количество переменных.&#x20;
* Нельзя указывать в тексте только переменную, т.е. 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 кнопок, но есть ограничения на использование определенных типов кнопок, а также ограничения на комбинации.

**Какие бывают кнопки:**

* **Кнопка быстрого ответа.**&#x20;

  Текстовая  кнопка, при клике на которую сразу отправляется в чат с вами ответ с текстом, повторяющим текст кнопки. Текст кнопки можно писать любой.
* **Кнопка с ссылкой.**&#x20;

  Кнопка при клике ведет на url, который вы укажите. Ссылка может быть полностью статичной либо содержать переменную. Если вы указываете переменную, то она обязательно должна быть в конце url-ссылки. URL-ссылка не поддерживает кириллицу, но текст самой кнопки - поддерживает.
* **Кнопка с номером телефона.**&#x20;

  При нажатии производится вызов на указанный номер телефона.
* **Кнопка каталог** (доступен только в категории Маркетинг).

  &#x20;Кнопка, при клике на которую открывается ваш каталог. Ваш клиент сможет сделать заказ, список отправленных товаров или услуг появится у вас в чате. &#x20;

Кнопка с ссылками и номером телефона при клике не отправляет ответ в чат, как это делает кнопка быстрого ответа.

**Ограничение на количество:**&#x20;

* Максимальное количество кнопок типа Quick Reply - 10 кнопок.
* Максимальное количество кнопок типа URL - 2 кнопки.
* Максимальное количество кнопок типа Phone - 1 кнопка.
* В шаблоне "Каталог" можно использовать только одну кнопку - кнопку каталога.
* Всего в шаблоне может быть не более 10 кнопок.

Комбинации описаны ниже:

<table><thead><tr><th width="445">Как можно</th><th>Как нельзя</th></tr></thead><tbody><tr><td><ul><li>Quick Reply, Quick Reply, Quick Reply</li><li>Quick Reply, Quick Reply, Quick Reply, URL, Phone</li><li>URL, Phone, Quick Reply, Quick Reply</li></ul></td><td><ul><li>Quick Reply, URL, Quick Reply</li><li>URL, Quick Reply, URL</li></ul></td></tr></tbody></table>

Как видно, необходимо учитывать последовательность ввода типа кнопок и допустимое количество. Т.е. нельзя добавить кнопку Quick Reply в начале, потом добавить кнопку URL и снова Quick Reply.

{% tabs %}
{% tab title="QUICK REPLY" %}
Кнопка быстрого ответа - текстовая  кнопка, при клике на которую сразу отправляется в чат с вами ответ с текстом, повторяющим текст кнопки. Текст кнопки можно писать любой. Максимальное количество символов - 25.&#x20;

```json
 {
    "type": "QUICK_REPLY",
    "text": "Yes"
 }
```

{% endtab %}

{% tab title="URL" %}
Свойство "text" - текст на кнопке.  Максимальное количество символов - 25.

Свойство "url" может быть полностью статичной либо содержать одну переменную. Если вы указываете переменную, то она обязательно должна быть в конце url-ссылки. Максимальное количество символов - 2000.

Свойство  "url"  не поддерживает кириллицу.

Если указываете переменную, обязательно нужно указать пример в "example".&#x20;

```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 %}

<details>

<summary>Полный пример создания маркетингового шаблона</summary>

Пример запроса на создание маркетингового шаблона со следующими компонентами:

* текстовый заголовок с переменной и примером значения&#x20;
* текстовое тело с переменными и примерами значений&#x20;
* текстовый нижний колонтитул&#x20;
* две кнопки быстрого ответа

```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"
        }
      ]
    }
  ]
}'
```

</details>

### Шаблон Аутентификации

<figure><img src="https://1775018921-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoCNwQHK1ya1FkEe495Vr%2Fuploads%2FrFHeRyRs2peoa2w0cKcS%2Fimage.png?alt=media&#x26;token=b8843285-a32c-4daf-b1da-45d65c9b59ec" alt=""><figcaption><p>Структура шаблона</p></figcaption></figure>

Шаблон аутентификации должен включать обязательно BODY и BUTTONS. Кнопки могут быть двух видов:  кнопка копирования кода  либо кнопка автозаполнения в одно касание.

{% tabs %}
{% tab title="BODY" %}
Текст в BODY фиксирован от Meta,  не заполняйте свойство "text". &#x20;

Язык текста, отображаемый у пользователя, зависит от выбранного языка шаблона.

Если хотите добавить текст "Из соображений безопасности не сообщайте код никому" , выставьте  "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 %}

<details>

<summary>Полный пример отправки шаблона Аутентификация</summary>

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

</details>

## Отправка шаблона

Отправка шаблона описана в [документации API ](https://1msg-docs.web.app/ru#tag/Shablony/operation/sendTemplate)в методе /sendTemplate.

Вы также можете отправить шаблон через раздел в личном кабинете "Кабинет разработчика" →["Тестирование запросов". ](https://my.1msg.io/testing/test-requests)Чтобы отправить шаблон, необходимо знать namespace, name и language шаблона. Чтобы получить эти данные, вызовите метод "Получить список шаблонов" (/templates).&#x20;

Некоторые свойства, которые могут вызвать вопросы в методе /sendTemplate.

| Свойства               | Описание                                                                                                                                                                                                                           |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| template               | Это name шаблона                                                                                                                                                                                                                   |
| language               | <p>policy: записывайте deterministiс</p><p>code: код language из метода /templates</p>                                                                                                                                             |
| Объект с type "body"   | Текстовое сообщение. Можно опустить, если в тексте нет переменных.                                                                                                                                                                 |
| Объект с type "button" | <p>Вам нужно указывать в теле только кнопки с sub\_type "url" либо "catalog". Остальные типы кнопок при отправке шаблона можно опустить.</p><p>Положение кнопок для каждой карточки в шаблоне "Карусель" должно быть одинаково</p> |

### Отправить шаблоны Маркетинга или Услуги

В запросах нужно отправлять только те объекты, которые указаны в созданном шаблоне. Например, если в шаблоне изначально нет объекта header, то и указывать его при отправке не надо. А также опускаются объекты, если:

* Объект header с типом `text` без переменной;
* Body без переменной;
* Кнопки быстрого ответа и Кнопка с номером опускаются всегда;
* URL-кнопка без переменной.

В header с типом `IMAGE`, `VIDEO`, `DOCUMENT` всегда указывается полная ссылка на медиа-документ. Обратите внимание, что ссылка на медиа-документ должна содержать формат документа.&#x20;

<details>

<summary>Пример отправки <strong>Документа</strong> с <strong>URL</strong> кнопкой</summary>

Структура:&#x20;

* Заголовок содержит документ
* тело сообщения содержит 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}}"
}
```

</details>

<details>

<summary>Пример отправки <strong>Текстового</strong> заголовка со всеми типами кнопок</summary>

Структура:&#x20;

* Текстовый заголовок с одной переменной
* Тело сообщения не содержит переменной. Поэтому в запросе опущен.
* 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}}"
}
```

&#x20;

</details>

### Отправить шаблон Аутентификации&#x20;

<details>

<summary>Пример отправки шаблона Аутентификации</summary>

Пример отправки кнопки копирования кода

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

</details>
