Как подключить WhatsApp Cloud API: шаблоны сообщений и вебхуки

Короткий ответ

WhatsApp Cloud API — это официальный API от Meta, который размещён на её серверах: свой сервер WhatsApp поднимать не нужно. Подключение состоит из шести шагов:

1. приложение в Meta for Developers с продуктом WhatsApp;
2. подтверждение собственного номера;
3. постоянный токен системного пользователя;
4. шаблоны сообщений и их модерация;
5. вебхук для входящих сообщений и статусов;
6. понимание 24-часового окна и тарификации.

Шаг 1. Приложение в Meta

• Зарегистрируйтесь в Meta for Developers и создайте приложение бизнес-типа.
• Добавьте продукт WhatsApp и привяжите бизнес-портфолио компании (бывший Business Manager).
• В разделе настройки API появятся тестовый номер и временный токен. Добавьте свой телефон в список получателей и отправьте первое тестовое сообщение.

Временный токен живёт недолго. Для продакшна создайте системного пользователя в настройках бизнеса, выдайте ему доступ к приложению и аккаунту WhatsApp и сгенерируйте постоянный токен с разрешениями whatsapp_business_messaging и whatsapp_business_management. Храните токен только на сервере.

Шаг 2. Собственный номер

• Номер должен принимать SMS или звонок с кодом подтверждения.
• Номер, который уже работает в приложении WhatsApp, обычно сначала нужно освободить. Актуальные варианты подключения проверяйте в документации.
• Отображаемое имя проходит проверку и должно соответствовать бренду.
• Верификация бизнеса повышает лимиты на число клиентов, которым можно писать первыми.

Запишите Phone Number ID и WABA ID — они нужны во всех запросах.

Шаг 3. Шаблоны сообщений

Шаблон — заранее согласованный текст, которым компания может написать первой. Категории:

Шаблон состоит из заголовка (текст или медиа), тела с переменными {{1}}, {{2}}, подписи и кнопок. Каждый язык — отдельная версия шаблона. Модерация обычно быстрая, статусы — одобрен, отклонён, приостановлен.

Частые причины отклонения: маркетинговый текст в категории Utility, переменная в самом начале или конце текста, нет примеров значений переменных, расплывчатый смысл.

Отправка одобренного шаблона:

curl -X POST "https://graph.facebook.com/<API_VERSION>/<PHONE_NUMBER_ID>/messages" \
  -H "Authorization: Bearer $WA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "998901234567",
    "type": "template",
    "template": {
      "name": "order_ready",
      "language": { "code": "ru" },
      "components": [
        { "type": "body", "parameters": [ { "type": "text", "text": "1024" } ] }
      ]
    }
  }'

Шаг 4. 24-часовое окно

Когда клиент пишет вам, открывается окно обслуживания на 24 часа. Внутри него можно отправлять любые сообщения: текст, медиа, кнопки, списки. Каждое новое сообщение клиента продлевает окно. Вне окна доступны только одобренные шаблоны.

На практике это значит: отвечайте быстро, а напоминания и уведомления вне окна заранее оформляйте шаблонами.

Шаг 5. Вебхуки

Вебхук — HTTPS-адрес вашего сервера, куда Meta присылает входящие сообщения и статусы доставки. Сначала Meta проверяет адрес GET-запросом:

app.get("/webhook", (req, res) => {
  const mode = req.query["hub.mode"];
  const token = req.query["hub.verify_token"];
  if (mode === "subscribe" && token === process.env.WA_VERIFY_TOKEN) {
    return res.status(200).send(req.query["hub.challenge"]);
  }
  res.sendStatus(403);
});

Дальше события приходят POST-запросами. Подпишитесь на поле messages в настройках вебхука. Важно:

• проверяйте заголовок X-Hub-Signature-256 — HMAC-SHA256 тела запроса с секретом приложения;
• отвечайте 200 сразу, а обработку выносите в очередь;
• дедуплицируйте события по ID сообщения: при сбоях Meta присылает их повторно;
• отслеживайте статусы sent, delivered, read и failed — в failed есть код ошибки.

Шаг 6. Как устроена тарификация

Раньше Meta считала оплату за 24-часовые диалоги по категориям. С середины 2025 года модель изменилась: оплачиваются доставленные шаблонные сообщения, а цена зависит от категории шаблона и страны получателя. Ответы внутри окна обслуживания бесплатны, как и utility-шаблоны, отправленные внутри открытого окна. Meta периодически обновляет правила, поэтому перед расчётом бюджета сверяйтесь с официальной страницей цен.

От чего зависят расходы: доля маркетинговых шаблонов, страны клиентов, частота рассылок и то, успеваете ли вы отвечать внутри окна. Подробности — в документации Cloud API.