Если само template-сообщение пришло, а кнопка не работает, не начинайте с повторной отправки. Откройте утверждённую версию шаблона и определите тип кнопки: call-to-action, quick reply или Flow требуют разных данных и дают разный результат. Подпись на экране не заменяет component contract.

Проверять нужно именно шаблон из того WABA, с тем именем и language code, который указан в запросе. Черновик в локальной админке или визуально похожая локаль могут иметь другой порядок кнопок. Сохраните request ID, template name, language code и безопасный payload без access token и номера получателя.

Одно слово «кнопка» скрывает разные контракты

Тип кнопкиЧто делаетЧто проверить
quick replyвозвращает подготовленный ответ/payloadsub_type, index и webhook обработки
dynamic URLдобавляет параметр к prefix из шаблонаtext parameter и итоговый адрес
static URLоткрывает адрес из approved templateв запросе может не быть динамического параметра
phone CTAпредлагает звонок на заданный номерномер и тип в версии шаблона
Flowоткрывает настроенный flowaction, flow token и данные сценария

Официальный пример Meta для interactive template использует component type=button, sub_type quick_reply и index 0. В SDK Meta URL-button описан иначе: переданный text добавляется к заранее заданному URL prefix. Поэтому один общий объект «buttonValue» без типа почти неизбежно перепутает payload и URL suffix.

Approved template — это исполняемый контракт

Имя шаблона, его язык, статус и список components должны быть прочитаны из Business Platform, а не восстановлены по памяти. После редактирования и повторного approval обновите кэш интеграции. Если провайдер-обёртка синхронизирует шаблоны с задержкой, сравните её представление с Meta и зафиксируйте source of truth.

  • Убедиться, что отправляется точный template name, а не отображаемое название.
  • Сверить language code и policy выбора локали без автоматической подмены.
  • Проверить фактическое количество и порядок button components.
  • Не отправлять параметры для статической части, если контракт их не ожидает.
  • Не считать HTTP 200 доказательством клика: это только результат отправки запроса.

Валидация должна падать до вызова API, если component отсутствует либо параметр не соответствует схеме сохранённого шаблона. Это даёт понятную ошибку в вашем журнале вместо сообщения, которое доставилось с неожиданным поведением.

Параметр отправляется в нужный component и index

Index — позиция кнопки в шаблоне, обычно с нуля. Он не является ID кампании, порядковым номером всех components или видимым label. Для dynamic URL передают text-параметр суффикса; для quick reply — payload. Используйте типы SDK или собственную строгую схему, чтобы эти варианты нельзя было случайно поменять местами.

{
  "type": "template",
  "template": {
    "name": "order_ready_v3",
    "language": {"code": "ru"},
    "components": [{
      "type": "button",
      "sub_type": "url",
      "index": "0",
      "parameters": [{"type": "text", "text": "orders/8421"}]
    }]
  }
}

Пример показывает форму динамической URL-кнопки, но реальные name, language и suffix берутся из вашего approved template. Access token помещается только в Authorization header и не попадает в логи. Номер телефона и идентификатор заказа в диагностической копии маскируют.

URL suffix кодируется один раз

Для dynamic URL выясните, ожидает ли prefix путь, код или query fragment. Передавайте только переменную часть, предусмотренную шаблоном. Полный URL вместо suffix способен дать дублированный адрес; двойное percent-encoding ломает slash, пробелы и кириллицу. После сборки разрешайте только HTTPS и доверенные hosts.

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

Приёмка проверяет устройство и webhook

  1. Отправить шаблон на тестовые Android и iOS устройства с одной версией payload.
  2. Проверить видимость кнопки, label и итоговый URL либо quick reply.
  3. Сохранить wamid исходящего сообщения и связать его со статусами доставки.
  4. Для quick reply подтвердить входящий webhook и идемпотентную обработку.
  5. Повторить тест после смены локали и после обновления approved template.

Исправление принято, когда один и тот же approved contract воспроизводимо работает на целевых клиентах, а клик наблюдаем по ожидаемому каналу. Для эскалации подготовьте WABA/template identifiers, язык, sanitized payload, API response, wamid и webhook fragment. Никогда не отправляйте access token, полный номер клиента или рабочую ссылку с секретом.

Проверенные источники