Что это такое
Шаблоны WhatsApp — это предварительно утвержденные структуры сообщений, используемые для начала или продолжения диалогов за пределами окна поддержки клиентов. Шаблон идентифицируется по WABA, имени и языку. Используйте это руководство для управления жизненным циклом API и поддержания стабильности рабочих шаблонов между командами, версиями и локалями.Перед началом работы
- Подключите WABA, которой будет принадлежать шаблон.
- Выберите категорию шаблона, поддерживаемый язык, имя и компоненты.
- Подготовьте репрезентативные примеры переменных и медиафайлов, необходимые для проверки.
- Соблюдайте правила Meta в отношении контента аутентификации, сервисных сообщений и маркетинга.
- Настройте эндпоинт Webhook, способный принимать события
whatsapp.template.reviewed.
Как это работает
- Создайте шаблон в WABA.
- Сохраните его имя, язык, категорию и текущий
status. - Дождитесь одобрения, если требуется проверка.
- Получайте отдельный шаблон или список шаблонов, чтобы отслеживать изменения статуса.
- Отправляйте только тот шаблон, который подходит для целевого сценария использования и находится в доступном для отправки статусе.
- Редактируйте или удаляйте шаблон при изменении его контента или жизненного цикла.
MARKETING вы можете добавить или обновить Max Price с помощью bidSpec. При редактировании опустите bidSpec или отправьте null, чтобы сохранить цену, либо отправьте {}, чтобы удалить ее. См. руководство по интеграции Max Price, где приведены суммы, коэффициенты для стран и полные примеры редактирования.
Запрос
POST /whatsapp/templates
Ответ
PENDING не означает, что шаблон уже готов к отправке.
Определение стабильного идентификатора ресурса
Рассматривайте каждую комбинацию WABA, имени шаблона и языка как единый ресурс. Ведите реестр ресурсов, содержащий владельца (wabaId), стабильное имя, точный код локали, назначение, ответственного, контракт переменных, текущий статус API, состояние развертывания и версию для замены.
Используйте предсказуемые имена, такие как <domain>_<purpose>_v<major>:
auth_login_otp_v1orders_pickup_ready_v2growth_summer_offer_v3
Выбор категории перед написанием контента
Выбирайте категорию исходя из причины, по которой клиент получает сообщение.
Если шаблон объединяет транзакционную информацию с рекламой, оформите его как маркетинговый или разделите эти цели на отдельные шаблоны.
Фиксация контракта переменных
Определите переменные как контракт API до того, как копирайтеры или переводчики приступят к работе. Для каждой переменной укажите позицию, смысловое значение, формат, источник, репрезентативный пример и логику резервного поведения. Например,Order {{0}} is ready at {{1}}. может использовать следующий контракт:
Сохраняйте значение каждой позиции неизменным для всех версий и локалей. Создайте новую версию, если требуется изменить порядок или назначение переменных.
Перед отправкой на проверку:
- Предоставьте корректный и репрезентативный пример для каждой переменной в теле сообщения или текстовом заголовке.
- Проверьте URL, форматы и размеры файлов для медиазаголовков.
- Ограничьте текстовый заголовок максимум одной переменной и добавьте для нее пример.
- Убедитесь, что переменные в кнопках-ссылках (URL) используются только там, где это разрешено API, и укажите полный пример URL.
- Никогда не используйте учетные данные, одноразовые коды, персональные данные или приватные медиафайлы в примерах для проверки.
Организация локалей в единый релиз
Используйте одно и то же версионированное имя для каждой локали в рамках одного релиза, но управляйте каждой паройname и language как отдельным ресурсом. Сохраняйте значения переменных и действия кнопок единообразными, даже если меняется порядок слов.
Утверждайте и публикуйте каждую локаль независимо. Никогда не направляйте пользователя на другой язык только потому, что эта локаль уже утверждена. Используйте точный, чувствительный к регистру код локали в запросах на создание, получение, редактирование, удаление и отправку.
Ограничение отправки по статусу шаблона
Используйте запросы получения или вебхукиwhatsapp.template.reviewed для обработки одобрения, отклонения, приостановки, отключения, архивации и других изменений жизненного цикла. Сохраняйте точное имя и язык, используемые в запросах на отправку сообщений.
Храните API status отдельно от состояния развертывания. Направляйте боевые отправки только по шаблону, текущий статус которого — APPROVED, а состояние развертывания — активно.
Успешный ответ на создание или редактирование не дает разрешения на отправку в продакшене.
Синхронизация состояния
Используйте Webhook для оперативных обновлений, а API получения или списков — для сверки:- Проверяйте подпись каждого события
whatsapp.template.reviewed. - Выполняйте дедупликацию доставок по
idсобытия. - Определяйте ресурс по
wabaId,nameиlanguage. - Сохраняйте как событие обновления, так и текущий
status. - Немедленно прекращайте маршрутизацию, если текущий статус не
APPROVED. - Запрашивайте шаблон, если событие отсутствует, задерживается или конфликтует с более новым состоянием реестра.
- Запускайте регулярную постраничную сверку списков для выявления расхождений.
Поведение при редактировании и удалении
- Редактируйте только те шаблоны, которые находятся в поддерживаемом эндпоинтом состоянии.
- Включайте в запрос на редактирование полный требуемый набор компонентов.
- Удаление по названию удаляет все языковые версии с этим именем.
- Удаление по названию и языку удаляет только данный локализованный шаблон.
- Архивированные шаблоны по-прежнему могут отображаться в списках и результатах поиска.
Выпуск, откат и вывод версий из эксплуатации
Для существенных изменений предпочтительнее использовать параллельную версию:- Создайте новое версионированное имя для каждой требуемой локали. Текущую утвержденную версию оставьте без изменений.
- Дождитесь, пока каждая целевая локаль перейдет в статус
APPROVED, затем проверьте ее переменные, медиафайлы, кнопки, категорию и отображаемый контент. - Направьте контролируемую долю подходящих отправок на новую версию и отслеживайте доставку, качество, ответы и обновления статуса.
- Переводите оставшийся трафик только после того, как новая версия будет соответствовать вашим критериям развертывания.
Ограничения и устранение неполадок
- Запрос на отправку завершается сбоем, если шаблон не утвержден или его компоненты не соответствуют параметрам сообщения.
- Шаблоны аутентификации используют ограниченные предопределенные структуры.
- Категория и контент шаблона должны соответствовать политике Meta.
- Изучите подробности отклонения, прежде чем создавать тот же контент повторно.
- Используйте новое название, если удаленный или существенно измененный шаблон нельзя безопасно восстановить.
Контрольный список перед запуском
- Название, назначение, владелец, категория и версия зафиксированы.
- Каждая переменная имеет одно значение, формат, безопасный пример и правило резервного значения.
- Медиафайлы и кнопки проходят проверку формата, назначения и примеров.
- Каждая требуемая локаль независимо переведена в статус
APPROVED. - Маршрут отправки отклоняет любой статус, кроме
APPROVED. - Обработка Webhook проверена, идемпотентна и сверена с данными получения.
- Процесс развертывания позволяет восстановить предыдущую утвержденную версию.
- Очереди, кампании, конфигурации, тесты и инструкции используют нужную версию.
Поддерживаемые языки
Выберите точный язык и региональный код локали для шаблона.
Примеры создания шаблонов
Адаптируйте шаблоны аутентификации, маркетинговые, сервисные, коммерческие шаблоны, шаблоны Flow и звонков.
API создания шаблонов
Ознакомьтесь с полной схемой компонентов.
Webhook проверки шаблонов
Обрабатывайте изменения статуса проверки и жизненного цикла.

