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

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

Создание шаблона описано в документации API в методе /addTemplate.

Вы также можете создать шаблон через раздел в личном кабинете "Кабинет разработчика" → "Тестирование запросов".

Общая часть запроса:

name	Название шаблона. name может содержать только строчные латинские буквы, цифры и символ подчеркивания.
allow_category_change	Флажок "Разрешить изменение категории". Вместо отклонения шаблона мы изменим его тип категории автоматически.
category	Тип шаблона: маркетинг (MARKETING), услуга (UTILITY) или аутентификация (AUTHENTICATION)
language	Язык шаблона. Выбранный язык должен совпадать с текстом внутри создаваемого шаблона, иначе шаблон Meta может отклонить.
components	Массив компонентов Шаблона

Пример:

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

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

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

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

HEADER

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

• Заголовок необязателен к заполнению

• Можно выбрать только один из типов: TEXT, IMAGE, VIDEO или DOCUMENT

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

TEXT

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

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

• text - может содержать до 60 символов.

• В text можно добавить только одну переменную.

• Если заголовок имеет переменную, то обязательно нужно указывать пример example в header_text.

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

{
    "type": "HEADER",
    "format": "TEXT",
    "text": "Hello"
}

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

{
  "type": "HEADER",
  "format": "TEXT",
  "text": "Our {{1}} is on!",
  "example": {
    "header_text": [
      "Summer Sale" // пример переменной {{1}}
    ]
  }
}

IMAGE

VIDEO

DOCUMENT

BODY

Тело сообщения представляет собой только текстовые компоненты и необходим для всех шаблонов. Шаблон ограничен одним компонентом BODY.

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

• Обязателен для заполнения.

• text - может содержать до 1024 символов.

• Если есть переменные в text, то необходимо обязательно указать примеры переменных в "example" в массив "body_text". Количество строк внутриbody_text должно соответствовать количеству переменных, включенных в строку text.

• от Meta нет ограничений на количество переменных.

• Нельзя указывать в тексте только переменную, т.е. Meta не примет формат текста "text": "{{1}}"

{
  "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 символов.

{
    "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.

QUICK REPLY

Кнопка быстрого ответа - текстовая кнопка, при клике на которую сразу отправляется в чат с вами ответ с текстом, повторяющим текст кнопки. Текст кнопки можно писать любой. Максимальное количество символов - 25.

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

URL

PHONE NUMBER

CATALOG

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

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

• текстовый заголовок с переменной и примером значения

• текстовое тело с переменными и примерами значений

• текстовый нижний колонтитул

• две кнопки быстрого ответа

{
  "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. Кнопки могут быть двух видов: кнопка копирования кода либо кнопка автозаполнения в одно касание.

BODY

Текст в BODY фиксирован от Meta, не заполняйте свойство "text".

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

Если хотите добавить текст "Из соображений безопасности не сообщайте код никому" , выставьте "add_security_recommendation": true. Установите значение false, чтобы исключить строку.

{
    "type": "BODY", 
    "add_security_recommendation": true
}

FOOTER

BUTTONS

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

{
  "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 в методе /sendTemplate.

Вы также можете отправить шаблон через раздел в личном кабинете "Кабинет разработчика" →"Тестирование запросов". Чтобы отправить шаблон, необходимо знать 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.

{
  "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-кнопка без переменной.

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

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

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

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

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