Шаблоны

Общее

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

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

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

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

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

2. Шаблоны WABA (WhatsApp Business API)

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

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

Эти шаблоны используются в окне чатов в личном кабинете Radist.Web. Вы также можете их использовать в своих продуктах.

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

• Обычные сообщения (type=text, video, image, document)

• Интерактивные сообщения WhatsApp Business API (type=waba_interactive)

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

Подробная информация доступна здесь.

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

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

• Тела (body) - обязательная часть. Текст сообщения.

• Блока действий (action) - обязательная часть. Кнопки/списки.

• Заголовка - необязательная часть. Может содержать текст, картинку, видео или документ.

• Подписи - необязательная часть. Нижний колонтитул сообщения.

Примеры

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

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

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

Сначала загрузим файл.

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

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

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

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

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

Шаблоны 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.

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

Основные параметры шаблонов: язык, имя шаблона, категория (маркетинг, услуги, аутентификация), компоненты.

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

• Тела/body (текст с переменными). Обязательный компонент. Остальные опциональны.

• Заголовка/header (текст с переменными или файл)

• Подписи/footer (текст)

• Кнопок/buttons (текст, ссылка, номер телефона)

Методы

1. GET /messaging/waba_templates/ Содержит минимально необходимый набор инфоормации для отправки шаблонов. Рекомендуем использовать его, если вы только отправляете шаблонные сообщения. Кэшируется и работает быстрее, чем те, что ниже.

2. Раздел /messaging/templates/waba_templates/ - используется для управления шаблонами. Всегда запрашивает актуальную информацию из FB и работает ощутимо медленнее.

Примеры

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

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

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

Сначала загружаем файл для подстановки в примеры. Примеры для шаблонов с файлами обязательны.

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

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

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

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

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": "[phone]"
        },
        {
          "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": "[phone]"
                },
                {
                    "type": "URL",
                    "text": "Управление записью",
                    "url": "https://example.org/demo/{{1}}"
                }
            ]
        }
    ]
}