Управление шаблонами WhatsApp

​

Что это такое

​

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

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

​

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

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

​

Запрос

curl --request POST https://api.ycloud.com/v2/whatsapp/templates \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "wabaId": "WABA_ID",
    "name": "order_ready",
    "language": "en_US",
    "category": "UTILITY",
    "components": [
      {
        "type": "BODY",
        "text": "Order {{0}} is ready for pickup.",
        "example": {
          "body_text": [["A-10001"]]
        }
      }
    ]
  }'

​

Ответ

{
  "wabaId": "WABA_ID",
  "name": "order_ready",
  "language": "en_US",
  "category": "UTILITY",
  "status": "PENDING",
  "components": [
    {
      "type": "BODY",
      "text": "Order {{0}} is ready for pickup."
    }
  ]
}

​

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

• auth_login_otp_v1
• orders_pickup_ready_v2
• growth_summer_offer_v3

​

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

​

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

• Предоставьте безопасный репрезентативный образец для каждой переменной в тексте сообщения (body) или текстовом заголовке.
• Проверьте URL-адреса, форматы и размеры файлов медиазаголовков.
• Используйте не более одной переменной в текстовом заголовке и укажите ее образец.
• Убедитесь, что переменные в кнопках-ссылках (URL) используются только там, где это разрешено API, и приложите полный образец URL.
• Никогда не используйте учетные данные, одноразовые коды, персональные данные или приватные медиафайлы в примерах для проверки.

​

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

​

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

​

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

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

​

Особенности редактирования и удаления

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

​

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

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

​

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

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

​

Чек-лист перед запуском

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