Создание шаблона через API

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

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

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

Пример:

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

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

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

HEADER

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

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

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

Укажите "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}}
    ]
  }
}

Укажите "format": "IMAGE", чтобы в заголовке вывести изображение. Обязательно выводить объект "example" с указанием ссылки на картинку в "header_handle".

{
  "type": "HEADER",
  "format": "IMAGE",
  "example": {
      "header_handle": [
      "https://img-example-link.com/delicious-orange-23.jpg"
    ]
  }
}

Укажите "format": "VIDEO", чтобы в заголовке вывести видео. Обязательно выводить объект "example" с указанием ссылки на видео в "header_handle".

 {
      "type": "HEADER",
      "format": "VIDEO",
      "example": {
        "header_handle": [
          "https://video-example-link.com//banner.mp4"
        ]
      }
  }

Укажите "format": "DOCUMENT", чтобы в заголовке вывести документ. Обязательно выводить объект "example" с указанием ссылки на документ в "header_handle".

{
      "type": "HEADER",
      "format": "DOCUMENT",
      "example": {
        "header_handle": [
          "https://doc-example-link.com/reyshi.pdf"
        ]
    }
}

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 в начале, потом добавить кнопку URL и снова Quick Reply.

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

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

Свойство "text" - текст на кнопке. Максимальное количество символов - 25.

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

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

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

{
    "type": "URL",
    "text": "Shop Now",
    "url": "https://www.luckyshrub.com/shop?promo={{1}}",
    "example": [ // заполняется, если добавлена переменная в url 
        "summer2023" // переменная {{1}}
   ]
}

phone_number - номер рабочего телефона, на который будет совершен звонок, когда пользователь нажимает кнопку. Максимальное количество символов - 20.

text - текст на кнопке. Максимальное количество символов - 25.

phone_number и text - обязательны для заполнения.

{
  "type": "PHONE_NUMBER",
  "text": "my number",
  "phone_number": "77777777777"
}

В шаблоне "Каталог" можно добавить только одну кнопку. В "text" обязательно необходимо писать "View catalog". В зависимости от языка шаблона текст кнопки будет переводиться на указанный язык.

 {
   "type": "CATALOG",
   "text": "View 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 фиксирован от Meta, не заполняйте свойство "text".

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

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

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

FOOTER не обязателен к заполнению .

В footer можно добавить текст о времени истечения кода в минутах. Для этого укажите целое число в "code_expiration_minutes". Можно указать минуты от 1 до 90.

Если этот параметр опущен, предупреждение об истечении срока действия кода не будет отображаться в доставленном сообщении

{
  "type": "FOOTER", 
  "code_expiration_minutes": 5
}

Шаблоны аутентификации должны включать либо кнопку копирования кода, либо кнопку автозаполнения в одно касание. У данных кнопок "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 - хэш ключа подписи вашего приложения.

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

   {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "OTP",
          "otp_type": "COPY_CODE",
          "text": "Скопировать"
        }
      ]
    }

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

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

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

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

Last updated 5 months ago