Интеграция API WhatsApp: архитектура, лимиты и инструменты
API WhatsApp предоставляет разработчикам инструменты интеграции мессенджера через Cloud API, Graph API и вебхуки для автоматизации рассылок, звонков и поддержки.
Оглавление
Основные интерфейсы платформы
WhatsApp Business Platform включает несколько специализированных API для решения бизнес-задач:
- WhatsApp Cloud API: Основной интерфейс для отправки текстов, rich media (изображения, видео, документы), интерактивных сообщений и совершения звонков. Поддерживает end-to-end шифрование и работу с групповыми чатами. Используется для OTP, подтверждений заказов и напоминаний.
- Business Management API: Инструмент для управления бизнес-аккаунтом (WABA). Позволяет добавлять телефонные номера, создавать шаблоны, получать аналитику доставляемости и детализацию тарификации.
- Marketing Messages API: Специализированный интерфейс для маркетинговых кампаний. Обеспечивает автоматическую оптимизацию креативов, предоставляет бенчмарки производительности и измеряет конверсии (добавление в корзину, оформление заказа).
- Meta Business Agent: AI-агенты для автономного ведения диалогов. Могут использовать базы знаний (FAQ, каталоги товаров) и интегрироваться с внешними системами через коннекторы.
Технические требования и протоколы
Платформа построена на базе Graph API и использует HTTP-протокол. Запросы формируются с учетом параметров пути, тела и заголовков, а ответы возвращаются исключительно в формате JSON.
- Аутентификация: Применяется OAuth (не OAuth 2.0) access tokens. Система разрешений ограничивает доступ к конкретным ресурсам WABA.
- Webhooks: Критически важный компонент для асинхронного взаимодействия. На ваш сервер доставляются JSON-пейлоады с уведомлениями о статусах сообщений, входящими текстами и ошибками. Все входящие сообщения передаются только через вебхуки.
Лимиты и ограничения отправки
Для предотвращения спама и управления нагрузкой платформа использует строгую систему квот.
| Тип лимита | Значение | Описание |
|---|---|---|
| Rate Limit (базовый) | 200 запросов/час | Ограничение по умолчанию на приложение для WABA. |
| Rate Limit (активный WABA) | 5000 запросов/час | Доступно для верифицированных аккаунтов с зарегистрированным номером. |
| Ограниченные эндпоинты | 200 запросов/час | Жесткий лимит для методов управления шаблонами, номерами и подписками. |
| Pair Rate Limit | 1 сообщение / 6 сек | Лимит отправки одному пользователю (~10 сообщений/мин или 600/час). |
Превышение Pair Rate Limit (более 1 сообщения в 6 секунд одному контакт-лицу) вызывает ошибку 131056. Для неверифицированных WABA также действуют дополнительные тестовые лимиты емкости.
Работа с шаблонами сообщений
Шаблоны (Message Templates) — это обязательные активы бизнес-аккаунта для инициирования массовых рассылок.
- Модерация: Каждый шаблон требует предварительного одобрения Meta.
- Категории: Делятся на утилитарные, маркетинговые и аутентификационные.
- Функционал: Поддерживают переменные для персонализации и кнопки действий (Call-to-Action).
- Управление: Создание, редактирование, удаление и проверка статуса одобрения доступны через Business Management API.
Этапы подключения и тестирования
Процесс интеграции требует прохождения нескольких обязательных шагов:
- Верификация бизнеса: Подтверждение легальности компании в экосистеме Meta.
- Настройка окружения: Регистрация и получение доступов в Developer Hub.
- Регистрация номера: Привязка телефонного номера к WABA.
- Создание шаблонов: Разработка структур сообщений и отправка на модерацию.
- Настройка webhooks: Конфигурация endpoint'ов на вашем сервере для приема пейлоадов.
- Тестирование: Использование sandbox-среды и тестовых номеров.
- Активация production: Переход на рабочий режим и подключение реальных клиентов.
Для ускорения старта и обхода части бюрократических сложностей разработчики часто используют сторонних BSP (Business Solution Providers), таких как Twilio, GREEN-API или Unipile, которые предлагают готовые обертки над API и упрощенную аутентификацию.
Пример структуры тела запроса (JSON) для отправки текста:
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "+16505555555",
"type": "text",
"text": {
"preview_url": true,
"body": "Here's the info you requested!"
}
}
Частые ошибки
- Ошибка 131056: Возникает при спам-рассылках, когда нарушается Pair Rate Limit (отправка чаще 1 раза в 6 секунд одному пользователю).
- Потеря входящих сообщений: Происходит при некорректной настройке webhook-эндпоинтов или отсутствии асинхронной обработки ошибок на стороне сервера.
- Блокировка шаблонов: Попытка использовать маркетинговые формулировки в утилитарных категориях или отсутствие явного opt-in (согласия) от пользователей перед началом коммуникации.
- Превышение квот API: Попытки массового парсинга или управления WABA без учета базового лимита в 200 запросов в час для специфических эндпоинтов.
FAQ
Как тарифицируются сообщения в API? Платформа использует модель оплаты за разговоры (conversation-based pricing). Стоимость зависит от категории диалога: маркетинг, утилитарные уведомления, аутентификация или сервисное обслуживание. Гранулярная аналитика доступна через Business Management API.
Какой протокол аутентификации поддерживается? Используется OAuth (не OAuth 2.0) access tokens. Токены и права доступа строго ограничивают возможность приложения взаимодействовать с конкретными ресурсами бизнес-аккаунта.
Можно ли автоматизировать поддержку с помощью ИИ? Да, Meta Business Agent позволяет внедрять AI-агентов для автономного ведения диалогов. Агенты могут опираться на загруженные базы знаний, FAQ и каталоги, а также обращаться к внешним API через коннекторы.
Что делать, если нет ресурсов на самостоятельную разработку? Вы можете подключить BSP (Business Solution Providers). Провайдеры вроде Twilio, GREEN-API или Unipile предлагают управляемые сервисы, no-code интеграции и берут на себя часть технических требований к инфраструктуре и шифрованию данных.