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

Last updated 11 months ago

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

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

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

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

name

Название шаблона. name может содержать только строчные латинские буквы, цифры и символ подчеркивания.

allow_category_change

Флажок "Разрешить изменение категории". Вместо отклонения шаблона мы изменим его тип категории автоматически.

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

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, 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.

Кнопка быстрого ответа - текстовая кнопка, при клике на которую сразу отправляется в чат с вами ответ с текстом, повторяющим текст кнопки. Текст кнопки можно писать любой. Максимальное количество символов - 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"
        }
      ]
    }
  ]
}