# Шаблоны

## Общее

Swagger: <https://api.radist.online/v2/docs#/Messaging/MessagingListMessageTemplates>

Необходимые права доступа (`scopes`) для работы с API: `messaging`

## Виды шаблонов

Шаблоны в API бывают двух типов:

1. Шаблоны личного кабинета Radist.Web
2. Шаблоны WABA (WhatsApp Business API)

## Шаблоны личного кабинета Radist.Web

### Общая информация

Эти шаблоны [используются](https://docs.radist.online/radist.online-docs/nashi-produkty/radist-web/shablony) в окне чатов в личном кабинете [Radist.Web](https://app.radist.online/). Вы также можете их использовать в своих продуктах.&#x20;

Есть 2 типа шаблонов:

* Обычные сообщения (type=text, video, image, document)
* Интерактивные сообщения WhatsApp Business API (type=waba\_interactive)

### Интерактивные сообщения WhatsApp Business API

Подробная информация доступна [здесь](https://developers.facebook.com/docs/whatsapp/guides/interactive-messages/).

Интерактивные сообщения WABA -- это сообщения с дополнительными интерактивными элементами, такими как: кнопки, списки, товары, запросы геолокации. Это **не** шаблонные сообщения. Они не требуют модерации и отправлять их можно только в рамках уже открытой 24-часовой диалоговой сессии.

Интерактивные сообщения состоят из:

* Тела (body) - **обязательная часть.** Текст сообщения.
* Блока действий (action) - **обязательная часть.** Кнопки/списки.
* Заголовка - необязательная часть. Может содержать текст, картинку, видео или документ.
* Подписи - необязательная часть. Нижний колонтитул сообщения.

### Примеры

<details>

<summary>Создание текстового шаблона</summary>

```json
POST /companies/5/messaging/templates/

{
  "name": "text demo",
  "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas condimentum sed libero id cursus. Integer mi metus, fermentum id ligula nec, pellentesque sollicitudin enim. In ut enim nisl.",
  "type": "text"
}


Response

{
    "id": 3244,
    "company_id": 5,
    "type": "text",
    "name": "text demo",
    "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas condimentum sed libero id cursus. Integer mi metus, fermentum id ligula nec, pellentesque sollicitudin enim. In ut enim nisl.",
    "file_url": null,
    "params": {}
}
```

</details>

<details>

<summary>Создание шаблона с файлом (с картинкой)</summary>

Сначала [загрузим файл.](https://api.radist.online/v2/docs#/Messaging/MessagingUploadFile)

```json
{
    "url": "https://ams3.digitaloceanspaces.com/radist2/user_uploads/b2162e41-d322-4a52-bb28-887a0d809e44/images.jfif"
}
```

Потом используем ссылку на файл при создании шаблона. Обратите внимание, что передаётся `type=text`, а настоящий формат (картинка, видео, документ) будет определён автоматически после создания шаблона.

```json
POST /companies/5/messaging/templates/

{
  "name": "test",
  "text": "test",
  "type": "text",
  "file_url": "https://ams3.digitaloceanspaces.com/radist2/user_uploads/b2162e41-d322-4a52-bb28-887a0d809e44/images.jfif"
}


Response

{
    "id": 3243,
    "company_id": 5,
    "type": "image",
    "name": "test",
    "text": "test",
    "file_url": "https://ams3.digitaloceanspaces.com/radist2/user_uploads/b2162e41-d322-4a52-bb28-887a0d809e44/images.jfif",
    "params": {}
}
```

</details>

<details>

<summary>Создание интерактивного сообщения WhatsApp Business API </summary>

```json
POST /companies/5/messaging/templates/

{
  "type": "waba_interactive",
  "name": "Демо",
  "waba_interactive": {
    "type": "button",
    "header": {
      "type": "text",
      "text": "Текст заголовка"
    },
    "body": "Текст тела сообщения",
    "footer": "Подпись сообщения",
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "title": "Кнопка 1"
          }
        },
        {
          "type": "reply",
          "reply": {
            "title": "Кнопка 2"
          }
        },
        {
          "type": "reply",
          "reply": {
            "title": "Кнопка 3"
          }
        }
      ]
    }
  }
}


Response

{
    "id": 3245,
    "company_id": 5,
    "type": "waba_interactive",
    "name": "Демо",
    "text": "Текст заголовка\nТекст тела сообщения\n Подпись сообщения",
    "file_url": null,
    "params": {
        "body": "Текст тела сообщения",
        "type": "button",
        "action": {
            "buttons": [
                {
                    "type": "reply",
                    "reply": {
                        "id": null,
                        "title": "Кнопка 1"
                    }
                },
                {
                    "type": "reply",
                    "reply": {
                        "id": null,
                        "title": "Кнопка 2"
                    }
                },
                {
                    "type": "reply",
                    "reply": {
                        "id": null,
                        "title": "Кнопка 3"
                    }
                }
            ],
            "sections": null
        },
        "footer": "Подпись сообщения",
        "header": {
            "url": null,
            "text": "Текст заголовка",
            "type": "text",
            "filename": null
        }
    }
}
```

</details>

## Шаблоны WABA

### Рекомендации к прочтению

1. <https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates> - первоисточник в FB. В разделе Templates описаны все виды шаблонов, из чего они состоят, как выглядят и  т.п.
2. <https://docs.360dialog.com/partner/messaging/template-messages> - дополнительная информация от 360DIalog.

### Общая информация

Основные параметры шаблонов: [язык](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/supported-languages), имя шаблона, [категория](https://developers.facebook.com/docs/whatsapp/updates-to-pricing/new-template-guidelines/) (маркетинг, услуги, аутентификация), компоненты.

Шаблон может состоять из 4 компонентов:

* Тела/body (текст с переменными). Обязательный компонент. Остальные опциональны.
* Заголовка/header (текст с переменными или файл)
* Подписи/footer (текст)
* Кнопок/buttons (текст, ссылка, номер телефона)

### Методы

1. [GET /messaging/waba\_templates/](https://api.radist.online/v2/docs#/Messaging/MessagingListMessagingWabaTemplates) Содержит минимально необходимый набор инфоормации для отправки шаблонов. Рекомендуем использовать его, если вы только отправляете шаблонные сообщения. Кэшируется и работает быстрее, чем те, что ниже.
2. [Раздел /messaging/templates/waba\_templates/](https://api.radist.online/v2/docs#/Messaging/MessagingListWabaTemplates) - используется для управления шаблонами. Всегда запрашивает актуальную информацию из FB и работает ощутимо медленнее.

### Примеры

<details>

<summary>Шаблон авторизации с кнопкой копирования кода</summary>

```json
POST /companies/5/messaging/templates/waba_templates/

{
  "connection_id": 31147,
  "custom_name": "demo auth",
  "category": "AUTHENTICATION",
  "allow_category_change": false,
  "components": [
    {
      "type": "BODY",
      "add_security_recommendation": true
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "COPY_CODE",
          "text": "Копировать"
        }
      ]
    }
  ],
  "template_locale": "el",
  "examples": {}
}


Response

{
  "name": "demo_auth_b9905b",
  "locale": "el",
  "status": "SUBMITTED",
  "category": "AUTHENTICATION",
  "created_at": "2024-07-01T13:16:08Z",
  "updated_at": "2024-07-01T13:16:15Z",
  "rejected_reason": "",
  "custom_name": "demo auth",
  "components": [
    {
      "type": "BODY",
      "text": "{{1}}",
      "add_security_recommendation": true
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "COPY_CODE",
          "text": "Копировать",
          "autofill_text": "",
          "package_name": null,
          "signature_hash": null
        }
      ]
    }
  ]
}
```

</details>

<details>

<summary>Шаблон с заголовком с файлом (картинкой)</summary>

Сначала [загружаем файл](https://api.radist.online/v2/docs#/Files/FilesUploadWabaTemplateFile) для подстановки в примеры. Примеры  для шаблонов с файлами **обязательны**.

```json
{
    "url": "https://radist2.cdn.radist.online/tmp/user_uploads/ae790a0e8df14ab0900e2a2df44c18ae.jpg"
}
```

Потом создаём шаблон

```json
POST /companies/5/messaging/templates/waba_templates/

{
  "connection_id": 31147,
  "custom_name": "header demo",
  "category": "MARKETING",
  "allow_category_change": true,
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE"
    },
    {
      "type": "BODY",
      "text": "Осталось 4 штуки. Спешите, пока не раскупили!"
    }
  ],
  "template_locale": "ru",
  "examples": {
    "header_url": "https://radist2.cdn.radist.online/tmp/user_uploads/ae790a0e8df14ab0900e2a2df44c18ae.jpg"
  }
}


Response

{
  "name": "header_demo_c5e5a2",
  "locale": "ru",
  "status": "SUBMITTED",
  "category": "MARKETING",
  "created_at": "2024-07-01T19:45:44Z",
  "updated_at": "2024-07-01T19:45:49Z",
  "rejected_reason": "",
  "custom_name": "header demo",
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE",
      "text": ""
    },
    {
      "type": "BODY",
      "text": "Осталось 4 штуки. Спешите, пока не раскупили!",
      "add_security_recommendation": null
    }
  ]
}
```

</details>

<details>

<summary>Шаблон с заголовком, телом, подписью и кнопками</summary>

```json
POST /companies/5/messaging/templates/waba_templates/

{
  "connection_id": 31147,
  "custom_name": "demo vars",
  "category": "UTILITY",
  "allow_category_change": true,
  "components": [
    {
      "type": "HEADER",
      "text": "Здравствуйте, {{1}}!",
      "format": "TEXT"
    },
    {
      "type": "BODY",
      "text": "Напоминаем, что у вас на завтра назначена встреча в {{1}} по адресу {{2}}. "
    },
    {
      "type": "FOOTER",
      "text": "С уважением, Radist.Online"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Нужна помощь"
        },
        {
          "type": "PHONE_NUMBER",
          "text": "Позвонить в офис",
          "phone_number": "+79000000000"
        },
        {
          "type": "URL",
          "text": "Управление записью",
          "url": "https://example.org/demo/{{1}}"
        }
      ]
    }
  ],
  "template_locale": "ru",
  "examples": {
    "header_text": [
      "Владимир"
    ],
    "body_text": [
      "13:00",
      "ул. Подлужная, д. 4"
    ],
    "button_url_text": [
      "064be74f-b999-47d5-87c6-8107edfe3e37"
    ]
  }
}


Response

{
    "name": "demo_vars_619753",
    "locale": "ru",
    "status": "SUBMITTED",
    "category": "UTILITY",
    "created_at": "2024-07-01T19:54:55Z",
    "updated_at": "2024-07-01T19:55:00Z",
    "rejected_reason": "",
    "custom_name": "demo vars",
    "components": [
        {
            "type": "HEADER",
            "format": "TEXT",
            "text": "Здравствуйте, {{1}}!"
        },
        {
            "type": "BODY",
            "text": "Напоминаем, что у вас на завтра назначена встреча в {{1}} по адресу {{2}}. ",
            "add_security_recommendation": null
        },
        {
            "type": "FOOTER",
            "text": "С уважением, Radist.Online",
            "code_expiration_minutes": null
        },
        {
            "type": "BUTTONS",
            "buttons": [
                {
                    "type": "QUICK_REPLY",
                    "text": "Нужна помощь"
                },
                {
                    "type": "PHONE_NUMBER",
                    "text": "Позвонить в офис",
                    "phone_number": "+79000000000"
                },
                {
                    "type": "URL",
                    "text": "Управление записью",
                    "url": "https://example.org/demo/{{1}}"
                }
            ]
        }
    ]
}
```

</details>