Создание шаблонов и управление ими

Шаблоны используются при отправке сообщений через облачный API на хостинге Meta или локальный API. Облачный API проверяет шаблоны и переменные параметры для защиты безопасности и целостности своих сервисов. Это делается с применением машинного обучения. Когда облачный API проверяет шаблоны и переменный текст, никакая информация в WhatsApp не передается.

Шаблоны можно создавать с помощью Business Management API или WhatsApp Business Manager. Количество возможных шаблонов в аккаунте WhatsApp Business определяется компанией, к которому он относится. Если компания не подтверждена, каждый аккаунт WhatsApp Business может иметь до 250 шаблонов. Если же компания подтверждена и по крайней мере один аккаунт WhatsApp Business использует номер телефона компании и имеет подтвержденное отображаемое имя, каждый аккаунт WhatsApp Business может иметь до 6000 шаблонов.

Прежде чем начать

Вам понадобится:

• Маркер доступа системного пользователя, связанный с компанией.
• Разрешение whatsapp_business_management
• ID аккаунта WhatsApp Business компании.
• Дескриптор медиаобъекта документа, изображения или видео (для шаблонов с медиафайлами). Чтобы получить дескриптор медиаобъекта, необходимо загрузить медиаобъект через Resumable Upload API.

Ограничения

• Максимальная длина для поля name в шаблоне сообщений — 512 символов.
• Максимальная длина для поля content в шаблоне сообщений — 1 024 символа.
• Шаблон можно редактировать, только когда он имеет статус Утвержден, Отклонен или Приостановлен. Шаблон можно редактировать один раз в день и до 10 раз в месяц.
• Аккаунты WhatsApp Business могут создавать не более 100 шаблонов сообщений в час.
• Шаблоны, в которых используется от 4 кнопок или кнопка быстрого ответа и одна или несколько кнопок другого типа, нельзя просматривать в клиентах WhatsApp для ПК. Пользователям WhatsApp, получившим одно из таких сообщений с шаблоном, будет предложено просмотреть его на телефоне.

Локализация

При создании шаблона можно добавить его вариант на определенном языке. Эти шаблоны учитываются в общем ограничении на количество шаблонов. Соблюдайте единообразие при переводе. См. статью об ошибках Structure Unavailable (Структура недоступна) в обратном вызове в Справочном центре.

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

Чтобы создать шаблон, отправьте запрос POST к конечной точке WhatsApp Business Account > Шаблоны сообщений.

Синтаксис запроса

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates

Тело публикации

{
  "name": "<NAME>",
  "category": "<CATEGORY>",
  "allow_category_change": <ALLOW_CATEGORY_CHANGE>,
  "language": "<LANGUAGE>",
  "components": [<COMPONENTS>]
}

Свойства тела

Категории шаблонов

Шаблоны должны быть распределены с использованием следующих категорий. Категории влияют на расценки, и категория, которую вы укажете, будет подтверждена во время создания шаблона.

• AUTHENTICATION
• MARKETING
• UTILITY

См. документ Категории шаблонов для определения, какую категорию выбрать при создании шаблонов.

Компоненты шаблонов

В зависимости от потребностей компании шаблоны могут содержать текст, медиафайлы и интерактивные компоненты. Список всех доступных компонентов, требования к их использованию, а также примеры переменных и запросов см. в документации по компонентам шаблонов.

При создании шаблона необходимо определить компоненты, назначив массив объектов компонентов свойству "компоненты" в теле запроса.

Например, массив, содержащий компонент тела с текстом с двумя переменными и примерами переменных, компонент кнопки с номером телефона и компонент кнопки с URL:

[
  {
    "type": "BODY",
    "text": "Thank you for your order, {{1}}! Your confirmation number is {{2}}. If you have any questions, please use the buttons below to contact support. Thank you for being a customer!",
    "example": {
      "body_text": [
        [
          "Pablo","860198-230332"
        ]
      ]
    }
  },
  {
    "type": "BUTTONS",
    "buttons": [
      {
        "type": "PHONE_NUMBER",
        "text": "Call",
        "phone_number": "15550051310"
      },
      {
        "type": "URL",
        "text": "Contact Support",
        "url": "https://www.luckyshrub.com/support"
      }
    ]
  }
]

Список всех доступных компонентов, требования к их использованию, а также примеры переменных и запросов см. в документации по компонентам шаблонов.

Обратите внимание, что в шаблонах категории AUTHENTICATION предусмотрены уникальные требования к компонентам. См. документацию по шаблонам категории "Аутентификация".

Проверка шаблона

Когда вы отправите запрос на создание шаблона, мы автоматически подтвердим его категорию при помощи руководства по Категоризации шаблонов.

• Если мы согласны с категорией, которую вы указали, мы создадим шаблон и установим его status на PENDING. Далее шаблон пройдет процесс проверки шаблона.
• При несогласии с вашим назначением мы создадим шаблон, но установим его статус status на REJECTED и запустим Webhooks обновление статуса шаблона сообщения и установим reason на INCORRECT_CATEGORY. Мы рекомендуем прослушивать этот Webhooks, чтобы определять отклоненные шаблоны или запрашивать поле rejected_reason для вновь созданных шаблонов со значением TAG_CONTENT_MISMATCH.

В обоих случаях первичный статус шаблона будет показан как часть ответа API.

Если же в результате подтверждения категории для вашего шаблона установлен статус REJECTED, у вас есть несколько вариантов:

• Редактировать компоненты шаблона, чтобы они соответствовали нашему руководству.
• Редактировать категорию шаблона, чтобы они соответствовали нашему руководству.
• Создание нового шаблона.

Автоматическая категоризация

Вы можете включить свойство allow_category_change в свой запрос, чтобы мы автоматически назначили категорию для вашего шаблона на основании его содержимого и нашего руководства по категориям шаблонов. Это может предотвратить ситуацию, при которой в качестве статуса вашего шаблона сразу же устанавливается REJECTED из-за неправильной категории.

Обратите внимание, что автоматические категории возможны только при создании шаблона.

Обзор шаблона

Статус PENDING означает, что шаблон на стадии проверки. Мы проверяем содержимое каждого нового созданного шаблона, чтобы убедиться, что он соответствует нашему руководству и политике. На основании выводов этой проверки мы автоматически изменим его статус на APPROVED или REJECTED, который запустит Webhooks обновления статуса шаблона сообщения.

Статус шаблона

На основании выводов подтверждения категории и проверки шаблона будет установлен или изменен status вашего шаблона на одно из следующих значений:

• APPROVED — шаблон прошел проверку шаблона и был одобрен и теперь его можно отправить в шаблоны сообщений.
• PENDING — шаблон прошел подтверждение категории и находится на стадии проверки шаблона.
• REJECTED — шаблон не прошел подтверждение категории или проверку шаблона. Вы можете запросить поле rejected_reason на шаблон и узнать причину.

См. эту справку по конечным точкам Шаблон сообщения WhatsApp для всех возможных полей и статусов.

Ответ

В случае успеха API возвращает ID, статус и категорию созданного шаблона. Возможны три результата:

• Мы согласны с указанной вами категорией, и шаблон проходит проверку (установлен statusPENDING).
• Мы не согласны с указанной вами категорией (установлен statusREJECTED)
• Мы автоматически одобрили шаблон (установлен statusAPPROVED). Это возможно только для шаблонов категории "Аутентификация" с кнопками одноразовых паролей.

{
    "id": "<ID>",
    "status": "<STATUS>",
    "category": "<CATEGORY>"
}

Свойства ответа

Пример запроса

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

• текстовый заголовок;
• тело;
• нижний колонтитул;
• две кнопки быстрого ответа.

Дополнительные примеры см. в этом разделе.

curl 'https://graph.facebook.com/v21.0/102290129340398/message_templates' \
-H 'Authorization: Bearer EAAJB...' \
-H 'Content-Type: application/json' \
-d '
{
  "name": "seasonal_promotion",
  "language": "en_US",
  "category": "MARKETING",
  "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"
        }
      ]
    }
  ]
}'

Пример ответа

{
    "id": "572279198452421",
    "status": "PENDING",
    "category": "MARKETING"
}

Отправка шаблонов

Для отправки шаблонов сообщений используйте облачный или локальный API.

Время жизни (TTL): настройка, значения по умолчанию, минимальные и максимальные значения и совместимость

Если нам не удается доставить сообщение пользователю WhatsApp, мы продолжаем попытки в течение некоторого времени. Оно называется временем жизни (TTL) или периодом действия сообщения.

Вы можете настроить используемое по умолчанию время жизни для шаблонов категорий "Аутентификация", "Услуги" и "Маркетинг".

Желательно, чтобы для всех шаблонов категории "Аутентификация" время жизни не выходило за рамки срока действия кода, чтобы клиенты получали сообщения, только если код ещё можно использовать.

Таблица значений по умолчанию, минимальных и максимальных значений и совместимых компонентов

Настройка времени жизни для шаблона

Чтобы указать пользовательское время жизни для шаблона категории "Аутентификация", "Услуги" или "Маркетинг", добавьте в вызов POST /<PHONE_NUMBER_ID>/messages свойство message_send_ttl_seconds и задайте в нем нужное значение.

Время жизни можно настраивать с шагом в 1 секунду.

Допустимые значения свойства message_send_ttl_seconds

• Шаблоны категории "Аутентификация": от 30 до 900 секунд (от 30 секунд до 15 минут).
• Шаблоны категории "Услуги": от 30 до 43200 секунд (от 30 секунд до 12 часов).
• Шаблоны категории "Маркетинг": от 43200 до 2592000 (от 12 часов до 30 дней).

Для шаблонов категорий "Аутентификация" и "Услуги" для свойства message_send_ttl_seconds можно указать значение -1. В этом случае будет установлено пользовательское время жизни продолжительностью 30 дней.

Если время жизни превышено: сброшенные сообщения

Сообщения, которые не удается доставить в течение установленного по умолчанию или настроенного пользователем времени жизни, сбрасываются.

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

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

Рекомендации для шаблонов категории "Маркетинг"

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

Рекомендуем добавлять в шаблоны категории MARKETINGкнопку быстрого ответа. Так пользователям будет проще подписываться на маркетинговые сообщения или отписываться от них, не блокируя вашу компанию. В результате вы сможете масштабировать переписки быстрее. Подробнее о преимуществах кнопки отказа от маркетинговой рассылки см. в этой статье.

Получение шаблонов

Чтобы получить список шаблонов, владельцем которых является аккаунт WhatsApp Business, отправьте запрос GET к конечной точке Аккаунт WhatsApp Business > Шаблоны сообщений.

Синтаксис запроса

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?fields=<FIELDS>
  &limit=<LIMIT>

Параметры строки запроса

Пример запроса

curl 'https://graph.facebook.com/v21.0/102290129340398/message_templates?fields=name,status&limit=3' \
-H 'Authorization: Bearer EAAJB...'

Пример ответа

{
  "data": [
    {
      "name": "seasonal_promotion_text_only",
      "status": "APPROVED",
      "id": "564750795574598"
    },
    {
      "name": "seasonal_promotion_video",
      "status": "PENDING",
      "id": "1252715608684590"
    },
    {
      "name": "seasonal_promotion_image_header",
      "status": "PENDING",
      "id": "1372429296936443"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MgZDZD"
    },
    "next": "https://graph.facebook.com/v21.0/102290129340398/message_templates?fields=name%2Cstatus&limit=3&after=MgZDZD"
  }
}

Пример запроса (отклоненные шаблоны)

Чтобы можете вернуть только шаблоны с определенными значениями полей, добавьте в запрос поле и нужное значение. Например, чтобы получить только отклоненные запросы, укажите status=REJECTED.

curl 'https://graph.facebook.com/v21.0/104996122399160/message_templates?fields=name,status&status=REJECTED' \
-H 'Authorization: Bearer EAAJB...'

Пример ответа

{
  "data": [
    {
      "name": "seasonal_promotion_text_only_v4",
      "status": "REJECTED",
      "id": "564750795574598"
    },
    {
      "name": "discount_qualifier",
      "status": "REJECTED",
      "id": "163917509772674"
    },
    {
      "name": "limited_time_offer_tuscan_getaway_2023",
      "status": "REJECTED",
      "id": "202389039167147"
    },
    {
      "name": "2023_mar_promo_2",
      "status": "REJECTED",
      "id": "1116034925734553"
    },
    {
      "name": "2023_mar_promo",
      "status": "REJECTED",
      "id": "952600926095321"
    }
  ]
}

Получение пространства имен шаблона

Для отправки сообщений с помощью шаблонов необходимо пространство имен шаблонов сообщений.

Чтобы получить пространство имен для шаблона, отправьте запрос GET к конечной точке /{whatsapp-business-account-ID} и укажите поле message_template_namespace.

Пример запроса

curl -i -X GET "https://graph.facebook.com/v21.0/{whatsapp-business-account-ID}
  ?fields=message_template_namespace
  &access_token={system-user-access-token}"

В случае успеха возвращается объект JSON с ID аккаунта WhatsApp Business и пространством имен:

{
    "id": "1972385232742141",
    "message_template_namespace": "12abcdefghijk_34lmnop" 
}

Редактирование шаблонов

Чтобы отредактировать шаблон, отправьте запрос POST к конечной точке Шаблон сообщения WhatsApp. Кроме того, отредактировать шаблон можно вручную на панели WhatsApp Manager > Инструменты для управления аккаунтом > Шаблоны сообщений.

Ограничения

• Шаблоны сообщений можно редактировать, только если они имеют статус APPROVED, REJECTED или PAUSED.
• Вы можете изменить для шаблона только свойство category или components.
• Свойство category одобренного шаблона изменить нельзя.
• Одобренные шаблоны можно редактировать до 10 раз в течение 30 дней или 1 раз в 24 часа. Отклоненные и приостановленные шаблоны можно редактировать неограниченное количество раз.
• После редактирования утвержденный или приостановленный шаблон будет автоматически утвержден, если пройдет проверку.

Синтаксис запроса

POST /<WHATSAPP_MESSAGE_TEMPLATE_ID>

Тело публикации

{
  "category": "<CATEGORY>",
  "components": [<COMPONENTS>]
}

Свойства

Пример запроса (редактирование компонентов)

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

curl 'https://graph.facebook.com/v21.0/564750795574598' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our {{1}} is on!",
      "example": {
        "header_text": [
          "Spring 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 April",
            "25OFF",
            "25%"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Use the buttons below to manage your marketing subscriptions"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Unsubcribe from Promos"
        },
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe from All"
        }
      ]
    }
  ]
}'

Пример запроса (изменение только категории)

Пример запроса на изменение категории шаблона с UTILITY на MARKETING.

curl 'https://graph.facebook.com/v21.0/1252715608684590' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "category": "MARKETING"
}'

Пример ответа

Пример ответа в случае успеха.

{
  "success": true
}

Удаление шаблонов

Для удаления шаблона по его имени или по ID используйте конечную точку Аккаунт WhatsApp Business > Шаблоны сообщений.

Примечания

• Если вы удаляете шаблон, который был отправлен в сообщении с шаблоном, но ещё не был доставлен (например, по причине того, что телефон клиента выключен), для статуса такого шаблона будет установлено PENDING_DELETION, а мы будем пытаться отправить это сообщение в течение 30 дней. По истечении этого периода времени у вас отобразится ошибка "Structure Unavailable" (Структура недоступна), а клиент не получит сообщение.
• Названия утвержденного шаблона, который был удален, нельзя повторно использовать в течение 30 дней.

Удаление по имени

При удалении шаблона по его имени будут удалены все шаблоны, которые соответствуют этому имени (имеются в виду шаблоны с одинаковым именем, однако также будут удалены шаблоны на других языках).

Синтаксис запроса

DELETE /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?name=<NAME>

Пример запроса

curl -X DELETE 'https://graph.facebook.com/v16.0/102290129340398/message_templates?name=order_confirmation' \
-H 'Authorization: Bearer EAAJB...'

Пример ответа

{
  "success": true
}

Удаление по ID

Чтобы удалить шаблон по его ID, добавьте в свой запрос ID шаблона вместе с его именем; при этом будет удален только шаблон с соответствующим ID.

Синтаксис запроса

DELETE /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
  ?hsm_id=<HSM_ID>,
  &name=<NAME>

Пример запроса

curl -X DELETE 'https://graph.facebook.com/v21.0/102290129340398/message_templates?hsm_id=1407680676729941&name=order_confirmation' \
-H 'Authorization: Bearer EAAJB...'

Пример ответа

{
  "success": true
}

Статьи по теме

Дальнейшие действия

• Начало работы с облачным API для отправки сообщений