> ## Documentation Index > Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Управление шаблонами WhatsApp > Безопасное создание, версионирование, проверка, публикация и вывод из эксплуатации шаблонов сообщений WhatsApp. ## Что это такое Шаблоны WhatsApp — это предварительно одобренные структуры сообщений, используемые для начала или продолжения диалогов за пределами окна обслуживания клиентов. Шаблон идентифицируется по WABA, имени и языку. Используйте это руководство для управления жизненным циклом API и поддержания стабильности рабочих шаблонов между командами, версиями и локалями. ## Перед началом работы * Подключите WABA, которой будет принадлежать шаблон. * Выберите категорию шаблона, [поддерживаемый язык](/ru/api-reference/guides/whatsapp-platform/supported-whatsapp-template-languages), имя и компоненты. * Подготовьте репрезентативные примеры переменных и медиафайлов, необходимые для проверки. * Соблюдайте правила Meta для аутентификационного, сервисного (utility) и маркетингового контента. * Настройте конечную точку Webhook, способную принимать события `whatsapp.template.reviewed`. ## Как это работает 1. Создайте шаблон в WABA. 2. Сохраните его имя, язык, категорию и текущий `status`. 3. Дождитесь одобрения, если требуется проверка. 4. Получайте данные шаблона или список шаблонов для отслеживания изменений статуса. 5. Отправляйте только те шаблоны, которые подходят для целевого сценария использования и находятся в статусе, допускающем отправку. 6. Редактируйте или удаляйте шаблон при изменении его контента или жизненного цикла. Редактирование полностью заменяет существующее содержимое шаблона. Включайте каждый компонент, который должен остаться после редактирования. ## Запрос `POST /whatsapp/templates` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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"]] } } ] }' ``` Имена шаблонов должны быть стабильными идентификаторами приложения. Используйте переменные только в позициях, поддерживаемых выбранным компонентом. ## Ответ ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "wabaId": "WABA_ID", "name": "order_ready", "language": "en_US", "category": "UTILITY", "status": "PENDING", "components": [ { "type": "BODY", "text": "Order {{0}} is ready for pickup." } ] } ``` Ответ подтверждает создание шаблона и его текущее состояние. `PENDING` не означает, что шаблон уже можно отправлять. ## Определение стабильного идентификатора ресурса Рассматривайте каждую комбинацию WABA, имени шаблона и языка как единый ресурс. Ведите реестр ресурсов с указанием владельца `wabaId`, постоянного имени, точного кода локали, назначения, владельца, контракта переменных, текущего статуса API, состояния развертывания и версии для замены. Используйте предсказуемые имена, например `__v`: * `auth_login_otp_v1` * `orders_pickup_ready_v2` * `growth_summer_offer_v3` Увеличивайте мажорную версию, если изменение затрагивает позиции переменных, типы компонентов, кнопки, категорию или смысл сообщения. Не привязывайте имена к названиям команд и датам. ## Выбор категории перед написанием контента Выбирайте категорию исходя из причины, по которой клиент получает сообщение. | Категория | Когда использовать | | - | - | | `AUTHENTICATION` | Аутентификация пользователя с помощью одноразового пароля для верификации, восстановления доступа или проверки безопасности. | | `UTILITY` | Выполнение конкретного запроса пользователя или предоставление обновления по согласованной транзакции. | | `MARKETING` | Отправка спецпредложения, промоакции, приглашения или другого контента, не относящегося к аутентификации или сервисному обслуживанию. | Если шаблон объединяет транзакционную информацию с рекламой, оформите его как маркетинговый или разделите цели на отдельные шаблоны. ## Фиксация контракта переменных Определите переменные как контракт API до того, как копирайтеры или переводчики приступят к работе. Для каждой переменной зафиксируйте ее позицию, смысловое значение, формат, источник, репрезентативный пример и поведение по умолчанию (fallback). Например, `Order {{0}} is ready at {{1}}.` может использовать следующий контракт: | Позиция | Значение | Формат | Пример для проверки | | - | - | - | - | | `{{0}}` | `order_reference` | Короткая строка для клиента | `A-10001` | | `{{1}}` | `pickup_location` | Локализованное название магазина | `Central Store` | Сохраняйте значение каждой позиции неизменным в разных версиях и локалях. Создайте новую версию, если вам необходимо изменить порядок или назначение переменных. Перед отправкой: * Предоставьте безопасный репрезентативный образец для каждой переменной в тексте сообщения (body) или текстовом заголовке. * Проверьте URL-адреса, форматы и размеры файлов медиазаголовков. * Используйте не более одной переменной в текстовом заголовке и укажите ее образец. * Убедитесь, что переменные в кнопках-ссылках (URL) используются только там, где это разрешено API, и приложите полный образец URL. * Никогда не используйте учетные данные, одноразовые коды, персональные данные или приватные медиафайлы в примерах для проверки. ## Организация локалей в рамках одного релиза Повторно используйте одно и то же версионированное имя для всех локалей в одном релизе, но управляйте каждой парой `name` и `language` как отдельным ресурсом. Сохраняйте согласованность значений переменных и действий кнопок, даже если порядок слов меняется. Утверждайте и выпускайте каждую локаль независимо. Никогда не перенаправляйте пользователя на другой язык только потому, что эта локаль уже одобрена. Используйте точный, чувствительный к регистру код локали в запросах на создание, получение, редактирование, удаление и отправку. ## Ограничение отправки по статусу шаблона Используйте получение данных или Webhook-уведомления `whatsapp.template.reviewed` для обработки одобрения, отклонения, приостановки, отключения, архивации и других изменений жизненного цикла. Сохраняйте точное имя и язык, используемые в запросах сообщений. Храните API-`status` отдельно от состояния развертывания. Направляйте рабочие отправки только на тот шаблон, чей текущий статус — `APPROVED`, а состояние развертывания — активное. | Статус | Действие в рабочей среде | | - | - | | `PENDING` | Блокируйте отправки, пока идет проверка. | | `APPROVED` | Разрешайте отправки после успешного прохождения контрактных тестов и согласования развертывания. | | `REJECTED` | Блокируйте отправки, проверяйте причину и корректируйте контент или контракт. | | `PAUSED` или `DISABLED` | Остановите новые отправки и используйте утвержденный резервный вариант, если он доступен. | | `IN_APPEAL` | Держите отправки заблокированными, пока статус не изменится на `APPROVED`. | | `ARCHIVED` или `DELETED` | Удалите шаблон из маршрутизации. | Успешный ответ на создание или редактирование не дает разрешения на отправку в рабочей среде. ## Синхронизация состояния Используйте 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 проверена, идемпотентна и синхронизирована с получением данных через API. * [ ] Процесс развертывания позволяет восстановить предыдущую одобренную версию. * [ ] Очереди, кампании, конфигурации, тесты и регламенты используют нужную версию. Выберите точный код языка и региональной локали для шаблона. Адаптируйте шаблоны аутентификации, маркетинга, служебных уведомлений, коммерции, Flow и звонков. Ознакомьтесь с полной схемой компонентов. Обрабатывайте изменения статуса проверки и жизненного цикла. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.