📱 WhatsApp Cloud API
WhatsApp подключается через Cloud API от Meta — официальный API с бесплатным уровнем, который позволяет отправлять и получать сообщения WhatsApp с вашего собственного сервера. Сторонний BSP (Business Solution Provider) не требуется.
Предварительные требования
- Аккаунт разработчика Meta на developers.facebook.com
- Аккаунт Meta Business (также известный как Business Manager)
- Номер телефона для WhatsApp, не зарегистрированный в личном WhatsApp (можно использовать SIM-карту, виртуальный номер или стационарный телефон)
Шаги настройки
1. Создание приложения Meta
- Перейдите на developers.facebook.com/apps
- Нажмите Create App
- Выберите тип Business
- Введите имя и подключите ваш Business-аккаунт
2. Добавление продукта WhatsApp
- В панели вашего приложения прокрутите до Add Products to Your App
- Нажмите Set Up на WhatsApp
- Выберите ваш Business-аккаунт
3. Получение учётных данных
Перейдите в WhatsApp → API Setup в панели приложения:
| Учётные данные | Где найти |
|---|---|
| Phone Number ID | В разделе "From" — числовой ID вида 123456789012345 |
| Access Token | Временный токен, показанный на этой странице. Для продакшена сгенерируйте постоянный токен через System Users. |
| App Secret | Панель приложения → Settings → Basic → App Secret |
| Verify Token | Строка, которую вы придумываете сами — любая случайная строка, например my_secret_verify_token_2024 |
4. Добавление канала в PulseHub
- Перейдите в Каналы → Добавить канал
- Выберите WhatsApp
- Заполните все четыре поля
- Нажмите Сохранить канал
- Скопируйте URL вебхука, показанный на карточке канала
5. Настройка вебхука в Meta
- В вашем приложении Meta перейдите в WhatsApp → Configuration
- Нажмите Edit рядом с разделом Webhook
- Callback URL: вставьте URL вебхука PulseHub
- Verify Token: введите ту же строку, что указали в PulseHub
- Нажмите Verify and Save
Meta отправит GET-запрос на URL вашего вебхука с ?hub.mode=subscribe&hub.verify_token=...&hub.challenge=.... PulseHub проверяет токен и возвращает challenge.
- В Webhook Fields подпишитесь на: messages
6. Тестирование
Отправьте сообщение WhatsApp на ваш бизнес-номер. Оно должно появиться как новая беседа в папке входящих PulseHub в течение нескольких секунд.
Проверка подписи
Meta включает заголовок X-Hub-Signature-256 в каждый вебхук:
X-Hub-Signature-256: sha256=abc123...
PulseHub проверяет его с помощью HMAC-SHA256 и вашего App Secret. Если проверка не проходит, вебхук возвращает 401 Signature mismatch.
Отправка сообщений
Когда агент отправляет ответ из папки входящих, PulseHub вызывает WhatsApp Cloud API:
POST https://graph.facebook.com/v18.0/{phone_number_id}/messages
Authorization: Bearer {access_token}
{
"messaging_product": "whatsapp",
"to": "{recipient_phone}",
"type": "text",
"text": {"body": "Ваш ответ здесь"}
}
Доступ к продакшену
Приложение Meta по умолчанию находится в режиме Development — оно может отправлять сообщения только на номера, добавленные как тестовые. Для выхода в продакшен:
- Завершите верификацию бизнеса в Meta Business Manager
- Отправьте ваш сценарий использования WhatsApp на проверку Meta
- После одобрения ваше приложение получит доступ для отправки сообщений всем пользователям WhatsApp
Частые проблемы
| Симптом | Вероятная причина |
|---|---|
| Проверка не проходит при настройке вебхука | verify_token в PulseHub не совпадает с введённым в Meta |
| Ошибка несоответствия подписи в логах | Неверный app_secret — скопируйте из App Settings → Basic, а не из API Setup |
| Сообщения не приходят | Поле вебхука messages не подписано в панели Meta |
Invalid phone number при отправке | Формат номера должен быть E.164 без + (например, 15551234567) |
| Ошибка приложения в режиме Development | Только верифицированные тестовые номера могут получать сообщения в режиме dev |