Интеграция WhatsApp Business — API, чат-бот, синхронизация с CRM

Триггеры и действия WhatsApp Business

Триггеры (что можно ловить)

Действия (что можно инициировать)

Incoming Message: GET /messages (webhook). Фиксация входящего текста от клиента в CRM. Message Status Update: GET /statuses. Отслеживание доставки (delivered) и прочтения (read). Media Download: GET /media/{id}. Получение файлов, отправленных клиентом, по media_id. Account Review: GET /v18.0/{phone-number-id}/business_profile. Мониторинг статуса верификации аккаунта. Template Status Change: GET /message_templates. Уведомление о переходе шаблона в статус Approved. Phone Number Update: PATCH /phone_numbers. Отслеживание изменения качества (Quality Rating). Conversation Started: Webhook тип conversation. Определение начала 24-часового окна диалога.

Send Message: POST /{phone-number-id}/messages. Базовая отправка текста, медиа или кнопок. Mark as Read: POST /{phone-number-id}/messages (с параметром message_id). Отметка сообщения как прочитанного. Send Template: POST /{phone-number-id}/messages (type: template). Отправка pre-approved шаблона вне окна. Update Profile: POST /{phone-number-id}/whatsapp_business_profile. Автоматическое обновление описания и URL компании. Delete Media: DELETE /media/{media_id}. Очистка хранилища после обработки файла. Create Template: POST /{phone-number-id}/message_templates. Программная подача новых шаблонов на модерацию. Reaction: POST /{phone-number-id}/messages (type: reaction). Постановка эмодзи-реакции на сообщение клиента.

Техническая настройка WhatsApp Business API

1. Аутентификация: Создайте System User в Meta Business Suite, сгенерируйте Permanent Access Token. Если используете BSP (Green-API, Wazzup и др.), токен генерируется в их личном кабинете, который проксирует запросы к Graph API.
2. Основные Endpoints: Работа ведется через https://graph.facebook.com/v19.0/{phone-number-id}/messages. Все запросы требуют Content-Type: application/json и Bearer-авторизацию.
3. Обработка ошибок: Реализуйте обработку кодов: 401 (срок токена истек), 403 (недостаточно прав), 429 (превышение Rate Limit). При 429 используйте экспоненциальную задержку (backoff).
4. Лимиты: Уровни доступа (Tier) определяют количество диалогов в день (1k, 10k, 100k+). Рост лимита происходит автоматически при высоком качестве отправки сообщений.
5. 24h Window: После последнего ответа пользователя открывается сессия. Вне её отправка возможна только через платные шаблоны (Message Templates).
6. Тестирование: Используйте Test Number в панели разработчика Meta для отладки вебхуков без затрат на реальные диалоги.
7. Мониторинг: Настройте логирование ответов HTTP 200. При сбоях доставки сообщений используйте логи errors и warnings в ответе API для диагностики.

Часто задаваемые вопросы о WhatsApp Business

Какие типы событий поддерживает API?

Поддерживаются события получения текстовых сообщений, медиа-файлов, реакций, статусов доставки (sent, delivered, read) и уведомления об изменении статуса шаблонов.

Есть ли песочница для тестов?

Да, Meta предоставляет тестовый номер (Test Number) в панели разработчика, который позволяет проверять входящие и исходящие запросы без подключения реального бизнес-аккаунта.

Как получить API-ключ?

Ключ генерируется в Meta Business Suite в разделе «Приложения» (System User). Для работы через BSP ключ выдается в интерфейсе провайдера.

Как обойти лимиты (Rate Limits)?

Ограничения зависят от Tier аккаунта. Основной способ повышения — соблюдение правил Meta по качеству контента, что автоматически увеличивает лимит отправки сообщений в сутки.

Что делать при ошибке 429?

Ошибка означает превышение частоты запросов. Необходимо внедрить механизм Retry-After: приостановить отправку на время, указанное в заголовке ответа, или использовать очередь с задержкой.

Совместимость с коробкой и SaaS?

WhatsApp Business API — это облачное решение (Cloud API), поэтому оно совместимо с любой архитектурой, способной выполнять HTTP-запросы (REST API), будь то self-hosted CRM или облачный сервис. Настроить интеграцию WhatsApp Business под ключ с гарантией — flowframe.ru, от 40 000 ₽, срок 7-21 день.