Перейти к основному содержанию

Что это такое

Шаблоны WhatsApp — это предварительно утвержденные структуры сообщений, используемые для начала или продолжения диалогов за пределами окна поддержки клиентов. Шаблон идентифицируется по WABA, имени и языку. Используйте это руководство для управления жизненным циклом API и поддержания стабильности рабочих шаблонов между командами, версиями и локалями.

Перед началом работы

  • Подключите WABA, которой будет принадлежать шаблон.
  • Выберите категорию шаблона, поддерживаемый язык, имя и компоненты.
  • Подготовьте репрезентативные примеры переменных и медиафайлов, необходимые для проверки.
  • Соблюдайте правила Meta в отношении контента аутентификации, сервисных сообщений и маркетинга.
  • Настройте эндпоинт Webhook, способный принимать события whatsapp.template.reviewed.

Как это работает

  1. Создайте шаблон в WABA.
  2. Сохраните его имя, язык, категорию и текущий status.
  3. Дождитесь одобрения, если требуется проверка.
  4. Получайте отдельный шаблон или список шаблонов, чтобы отслеживать изменения статуса.
  5. Отправляйте только тот шаблон, который подходит для целевого сценария использования и находится в доступном для отправки статусе.
  6. Редактируйте или удаляйте шаблон при изменении его контента или жизненного цикла.
Редактирование полностью заменяет существующее содержимое шаблона. Включайте каждый компонент, который должен остаться после редактирования. Для шаблонов MARKETING вы можете добавить или обновить Max Price с помощью bidSpec. При редактировании опустите bidSpec или отправьте null, чтобы сохранить цену, либо отправьте {}, чтобы удалить ее. См. руководство по интеграции Max Price, где приведены суммы, коэффициенты для стран и полные примеры редактирования.

Запрос

POST /whatsapp/templates
Имена шаблонов должны быть стабильными идентификаторами приложения. Используйте переменные только в тех позициях, которые поддерживаются выбранным компонентом.

Ответ

Ответ подтверждает создание шаблона и его текущее состояние. PENDING не означает, что шаблон уже готов к отправке.

Определение стабильного идентификатора ресурса

Рассматривайте каждую комбинацию WABA, имени шаблона и языка как единый ресурс. Ведите реестр ресурсов, содержащий владельца (wabaId), стабильное имя, точный код локали, назначение, ответственного, контракт переменных, текущий статус API, состояние развертывания и версию для замены. Используйте предсказуемые имена, такие как <domain>_<purpose>_v<major>:
  • auth_login_otp_v1
  • orders_pickup_ready_v2
  • growth_summer_offer_v3
Увеличивайте мажорную версию, если изменение затрагивает позиции переменных, типы компонентов, кнопки, категорию или смысл сообщения. Не привязывайте имена к названиям команд и датам.

Выбор категории перед написанием контента

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

Фиксация контракта переменных

Определите переменные как контракт API до того, как копирайтеры или переводчики приступят к работе. Для каждой переменной укажите позицию, смысловое значение, формат, источник, репрезентативный пример и логику резервного поведения. Например, Order {{0}} is ready at {{1}}. может использовать следующий контракт: Сохраняйте значение каждой позиции неизменным для всех версий и локалей. Создайте новую версию, если требуется изменить порядок или назначение переменных. Перед отправкой на проверку:
  • Предоставьте корректный и репрезентативный пример для каждой переменной в теле сообщения или текстовом заголовке.
  • Проверьте URL, форматы и размеры файлов для медиазаголовков.
  • Ограничьте текстовый заголовок максимум одной переменной и добавьте для нее пример.
  • Убедитесь, что переменные в кнопках-ссылках (URL) используются только там, где это разрешено API, и укажите полный пример URL.
  • Никогда не используйте учетные данные, одноразовые коды, персональные данные или приватные медиафайлы в примерах для проверки.

Организация локалей в единый релиз

Используйте одно и то же версионированное имя для каждой локали в рамках одного релиза, но управляйте каждой парой name и language как отдельным ресурсом. Сохраняйте значения переменных и действия кнопок единообразными, даже если меняется порядок слов. Утверждайте и публикуйте каждую локаль независимо. Никогда не направляйте пользователя на другой язык только потому, что эта локаль уже утверждена. Используйте точный, чувствительный к регистру код локали в запросах на создание, получение, редактирование, удаление и отправку.

Ограничение отправки по статусу шаблона

Используйте запросы получения или вебхуки whatsapp.template.reviewed для обработки одобрения, отклонения, приостановки, отключения, архивации и других изменений жизненного цикла. Сохраняйте точное имя и язык, используемые в запросах на отправку сообщений. Храните API status отдельно от состояния развертывания. Направляйте боевые отправки только по шаблону, текущий статус которого — APPROVED, а состояние развертывания — активно. Успешный ответ на создание или редактирование не дает разрешения на отправку в продакшене.

Синхронизация состояния

Используйте Webhook для оперативных обновлений, а API получения или списков — для сверки:
  1. Проверяйте подпись каждого события whatsapp.template.reviewed.
  2. Выполняйте дедупликацию доставок по id события.
  3. Определяйте ресурс по wabaId, name и language.
  4. Сохраняйте как событие обновления, так и текущий status.
  5. Немедленно прекращайте маршрутизацию, если текущий статус не APPROVED.
  6. Запрашивайте шаблон, если событие отсутствует, задерживается или конфликтует с более новым состоянием реестра.
  7. Запускайте регулярную постраничную сверку списков для выявления расхождений.
Не используйте Webhook в качестве единственного источника данных об инвентаре и не опрашивайте API перед каждым сообщением.

Поведение при редактировании и удалении

  • Редактируйте только те шаблоны, которые находятся в поддерживаемом эндпоинтом состоянии.
  • Включайте в запрос на редактирование полный требуемый набор компонентов.
  • Удаление по названию удаляет все языковые версии с этим именем.
  • Удаление по названию и языку удаляет только данный локализованный шаблон.
  • Архивированные шаблоны по-прежнему могут отображаться в списках и результатах поиска.

Выпуск, откат и вывод версий из эксплуатации

Для существенных изменений предпочтительнее использовать параллельную версию:
  1. Создайте новое версионированное имя для каждой требуемой локали. Текущую утвержденную версию оставьте без изменений.
  2. Дождитесь, пока каждая целевая локаль перейдет в статус APPROVED, затем проверьте ее переменные, медиафайлы, кнопки, категорию и отображаемый контент.
  3. Направьте контролируемую долю подходящих отправок на новую версию и отслеживайте доставку, качество, ответы и обновления статуса.
  4. Переводите оставшийся трафик только после того, как новая версия будет соответствовать вашим критериям развертывания.
Выполняйте откат путем переключения маршрутизации на предыдущие утвержденные название и язык. Не используйте экстренное редактирование в качестве отката. Выводите предыдущую версию из эксплуатации только после того, как на нее перестанут ссылаться очереди, кампании, конфигурации, тесты и окна отката.

Ограничения и устранение неполадок

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

Контрольный список перед запуском

  • Название, назначение, владелец, категория и версия зафиксированы.
  • Каждая переменная имеет одно значение, формат, безопасный пример и правило резервного значения.
  • Медиафайлы и кнопки проходят проверку формата, назначения и примеров.
  • Каждая требуемая локаль независимо переведена в статус APPROVED.
  • Маршрут отправки отклоняет любой статус, кроме APPROVED.
  • Обработка Webhook проверена, идемпотентна и сверена с данными получения.
  • Процесс развертывания позволяет восстановить предыдущую утвержденную версию.
  • Очереди, кампании, конфигурации, тесты и инструкции используют нужную версию.

Поддерживаемые языки

Выберите точный язык и региональный код локали для шаблона.

Примеры создания шаблонов

Адаптируйте шаблоны аутентификации, маркетинговые, сервисные, коммерческие шаблоны, шаблоны Flow и звонков.

API создания шаблонов

Ознакомьтесь с полной схемой компонентов.

Webhook проверки шаблонов

Обрабатывайте изменения статуса проверки и жизненного цикла.