Вкратце: настройте публичный HTTPS-эндпоинт, зарегистрируйте его как webhook в Whapi.Cloud, и ваш сервер будет получать каждое событие WhatsApp как JSON POST. Проверяйте поле type для маршрутизации логики, затем вызывайте POST /messages/text с параметрами to и body для ответа. Этот двухшаговый цикл — получить событие, отправить реакцию — составляет основу каждой интеграции в данном руководстве. Начните с маршрутизации текстовых сообщений; добавляйте условные ветки по мере роста вашего сценария использования.
Основной принцип: событие → реакция
Интеграция WhatsApp API основана на событиях, а не на SDK для обмена сообщениями. Что-то происходит в WhatsApp, Whapi.Cloud уведомляет ваш сервер через webhook, ваш код решает, как реагировать, и API выполняет это.
Последовательность фиксирована. Пользователь отправляет сообщение на ваш номер WhatsApp. Whapi.Cloud фиксирует это событие и немедленно отправляет HTTP POST на URL вашего webhook с JSON-payload — кто отправил, тип сообщения, содержание. Ваш сервер читает payload, применяет бизнес-логику и вызывает REST API Whapi.Cloud для отправки ответа, обновления записи в CRM или запуска последующего действия. Цикл повторяется для каждого следующего события.
Ваш код никогда не делает polling — Whapi.Cloud доставляет каждое событие WhatsApp на ваш webhook в момент его возникновения. Единственный вопрос, на который отвечает ваша бизнес-логика: учитывая это событие, что происходит дальше?
Уведомления о доставке, реакции на эмодзи, нажатия кнопок, изменения состава групп и события вызовов — все они инициируют webhooks. Входящий текст — один из восьми типов событий. Сопоставление полной таксономии с бизнес-решениями отличает рабочую интеграцию от недоделанной. Разработчики, знакомые с webhooks Stripe или callbacks Twilio, немедленно узнают этот паттерн.
Почему использовать шлюз вместо официального API?
Whapi.Cloud подключается через сокеты веб-сессий. Отсканируйте QR-код и отправьте первое сообщение за считанные минуты — без верификации Meta и одобрения шаблонов.
Официальная платформа WhatsApp Business требует верификации бизнеса, подключения через BSP и предварительно одобренных шаблонов сообщений, прежде чем отправить хотя бы одно проактивное сообщение. Whapi.Cloud взимает фиксированную подписку без поминутных или посессионных сборов. Более 3300 команд разработчиков используют его в продакшене в нескольких странах.
Один реальный компромисс: Whapi.Cloud официально не одобрен Meta, что важно для регулируемых отраслей, требующих формальной документации о соответствии. Для e-commerce, ботов поддержки, HR-инструментов и синхронизации CRM — не является блокирующим ограничением. Руководство по началу работы охватывает всё, что нужно перед первым вызовом API.
Полная таксономия событий WhatsApp
Каждая категория событий соответствует отдельному классу бизнес-решений, которые должна обрабатывать ваша логика маршрутизации — и полная таксономия шире, чем ожидает большинство разработчиков перед первой интеграцией.
Каждое событие, доставляемое Whapi.Cloud, имеет одинаковую внешнюю структуру: JSON POST на ваш webhook с полем type, идентифицирующим категорию события. Ваш обработчик сначала ветвится по type, затем извлекает подполя, специфичные для этой категории.
| Категория события | Конкретные типы событий | Типичная бизнес-реакция |
|---|---|---|
| Входящее сообщение | text, image, audio, video, document, sticker, location, contact card | Маршрутизация в AI-обработчик, пересылка в CRM, автоответ, тег разговора |
| Интерактивное взаимодействие | button reply, quick reply, list selection, template response | Продвижение машины состояний разговора, подтверждение заказа, запуск действия на бэкенде |
| Реакция на эмодзи | reaction added, reaction removed | Запись оценки настроения, запуск следующего шага, обновление метрики удовлетворённости |
| Статус сообщения | sent, delivered, read, played (voice note) | Обновление поля доставки в CRM, отмена таймера повторного вовлечения, запуск follow-up-последовательности |
| Событие звонка | incoming call initiated, call missed, call rejected | Запись пропущенного звонка, отправка автоматического сообщения с запросом обратного звонка |
| Событие группы | participant joined, participant left, admin changed, group created/archived | Обновление списка участников, отправка приветственного сообщения, синхронизация с HR-системой |
| Событие метки | label applied to chat, label removed | Сегментация контакта в CRM, запуск кампании, обновление этапа воронки |
| Событие канала | follower joined channel, channel update published | Отправка подтверждения подписчику, синхронизация аналитики, запуск workflow уведомлений |
Правило маршрутизации одинаково во всех строках: читайте поле type, переходите к соответствующему обработчику, извлекайте подполя, релевантные для этого типа. Сообщение "image" требует другого обработчика, чем взаимодействие "button_reply" — оба приходят как POST-запросы на один и тот же URL webhook, но структура payload и ваша бизнес-логика кардинально отличаются.
Способы интеграции
Пишете ли вы серверный код или настраиваете инструмент визуального workflow, каждая интеграция следует одному и тому же циклу событие→реакция — меняются только инструменты.
| Подход | Технические требования | Время до первого сообщения | Лучше всего подходит для |
|---|---|---|---|
| REST API (Python / Node.js / PHP) | HTTP-клиент, любой бэкенд с публичным URL | ~30 минут | Пользовательская бизнес-логика, AI-чатботы, коннекторы CRM |
| Make (нативный модуль Whapi.Cloud) | Только аккаунт Make | ~10 минут | Не-разработчики, команды маркетинговой автоматизации |
| n8n (self-hosted или облако) | Экземпляр n8n (Docker или облако) | ~15 минут | Технические команды, желающие self-hosted управления workflow |
| cURL / Postman | Ничего, кроме самого инструмента | ~5 минут | Тестирование эндпоинтов, proof of concept |
Пользователи Make и n8n настраивают узел-триггер webhook, который получает тот же JSON-payload, что и пользовательский бэкенд. Узлы затем считывают поля события и вызывают endpoint отправки Whapi.Cloud в качестве реакции. Модель событие→реакция не меняется; бизнес-логика живёт на визуальном canvas вместо кода.
Настройка webhook: принимающая сторона
Настройка webhook в Whapi.Cloud требует трёх вводных данных: URL вашего эндпоинта, типы событий, которые вы хотите получать, и необязательный секрет для верификации запросов. Эндпоинт должен быть публично доступен по HTTPS.
Настройте webhook в параметрах вашего канала Whapi.Cloud. После сохранения Whapi.Cloud начинает пересылать события WhatsApp на ваш URL как HTTP POST-запросы с JSON-телом. События поступают в реальном времени — как правило, в течение нескольких сотен миллисекунд после действия в WhatsApp. Нет интервала опроса для настройки и постоянного соединения для поддержания с вашей стороны. Полный справочник формата payload webhook документирует каждое поле, которое ваш обработчик должен будет разобрать.
Во время разработки ngrok открывает локальный порт для публичного HTTPS URL. Задайте этот URL как временный webhook, запустите обработчик локально и проверяйте live-payload перед развёртыванием на сервере.
Возвращайте HTTP 200 до начала обработки. Это обязательно. Whapi.Cloud повторяет доставку, если ваш эндпоинт не отвечает в пределах тайм-аута. Немедленно подтвердите получение запроса, отправьте payload в фоновый поток или очередь задач и обрабатывайте асинхронно. Смешивание подтверждения и обработки в одном синхронном пути вызывает дублирование событий при медленной бизнес-логике.
От webhook до ответа: рабочий пример кода
Любой язык с HTTP-клиентом — Python, Node.js, PHP, Go — интегрируется одинаково. Без проприетарного SDK, без обёрток для установки. Обработчик ниже маршрутизирует входящие сообщения и отправляет ответы через POST /messages/text.
from flask import Flask, request, jsonify
import requests
import threading
app = Flask(__name__)
WHAPI_TOKEN = "your_channel_token" # from panel.whapi.cloud/dashboard
WHAPI_URL = "https://gate.whapi.cloud/messages/text"
def send_reply(to: str, body: str) -> None:
# Calls sendMessageText — required: to (chat ID), body (message text)
requests.post(
WHAPI_URL,
headers={"Authorization": f"Bearer {WHAPI_TOKEN}"},
json={"to": to, "body": body}
)
def process_event(data: dict) -> None:
for msg in data.get("messages", []):
if msg.get("from_me"):
continue # skip outbound confirmations
sender = msg.get("chat_id") # e.g. "[email protected]"
msg_type = msg.get("type", "")
if msg_type == "text":
text = msg.get("text", {}).get("body", "").lower()
if any(w in text for w in ["hello", "hi", "hey"]):
send_reply(sender, "Hey! How can I help you today?")
elif "price" in text or "pricing" in text:
send_reply(sender, "Check our pricing: https://whapi.cloud/price")
elif "order" in text:
send_reply(sender, "Please share your order number and we'll check its status.")
else:
send_reply(sender, "Thanks! Our team will get back to you shortly.")
elif msg_type == "image":
send_reply(sender, "Got your image — our team will review it.")
elif msg_type == "button_reply":
btn_id = msg.get("button_reply", {}).get("id", "")
send_reply(sender, f"You selected: {btn_id}. Processing your request...")
elif msg_type == "reaction":
# Reactions carry sentiment data — log them, don't reply by default
emoji = msg.get("reaction", {}).get("text", "")
msg_id = msg.get("reaction", {}).get("msg_id", "")
print(f"Reaction {emoji} on message {msg_id} from {sender}")
@app.route("/webhook", methods=["POST"])
def webhook():
data = request.get_json()
# Acknowledge immediately — never block on processing
threading.Thread(target=process_event, args=(data,)).start()
return jsonify({"status": "ok"}), 200
if __name__ == "__main__":
app.run(port=5000)Видны четыре ветки маршрутизации: приветствие по ключевым словам, предложение цены при намерении купить, запрос уточнения по запросам о заказах, логирование реакций для анализа настроений. Та же условная структура масштабируется до сотен веток — или замените всю цепочку if/elif вызовом LLM. Сам обработчик webhook остаётся неизменным. Шаги развёртывания в продакшене с очередями Celery см. в руководстве по боту WhatsApp на Python.
В реальном развёртывании замените фоновый поток очередью задач (Celery, RQ или облачным сервисом очередей) для гарантий повтора и горизонтального масштабирования. Подтверждение webhook и бизнес-логика должны оставаться разделёнными — эта граница является ключевым архитектурным решением в каждой интеграции на масштабе.
Интерактивные типы сообщений как отдельные входные события
Ответы на кнопки, выборы из списков и быстрые ответы — это отдельные типы событий с различными структурами payload. Каждый требует собственной ветки маршрутизации в вашем коде.
Когда пользователь нажимает кнопку в интерактивном сообщении WhatsApp, Whapi.Cloud доставляет событие button_reply. Payload содержит ID кнопки, который вы задали при создании сообщения, а не видимый текст метки. Ваша логика маршрутизации проверяет ID, делая интерактивные потоки детерминированными — никакая формулировка пользователя случайно не активирует неверную ветку.
Типичные особенности:
-
button_reply: Извлекайте
button_reply.id— программатический ID, заданный при создании кнопочного сообщения. Маршрутизируйте к соответствующему обработчику без разбора текста. -
list_reply: Извлекайте как
list_reply.id, так иlist_reply.title— ID управляет логикой, title полезен в подтверждающих сообщениях, отправляемых обратно пользователю. -
reaction: Извлекайте
reaction.text(символ эмодзи) иreaction.msg_id(на какое сообщение была реакция). Сопоставьте с логированием настроений или используйте как лёгкий сигнал удовлетворённости, не прерывая разговор. -
Обновления статуса: Каждое событие статуса содержит
statuses[].statusсо значением"sent","delivered"или"read". Обновите поле в CRM, отмените таймер повторного вовлечения или запустите follow-up-последовательность на основе переходов статуса.
Подтверждения прочтения — это поведенческие данные, а не просто учёт доставки. Потенциальный клиент, читающий ваше ценовое сообщение в 21:00, но не отвечающий, говорит что-то вашей CRM. Маршрутизируйте события статуса в ваш слой данных — это сигналы для действий, а не шум для фильтрации.
Архитектура AI-чатбота в WhatsApp
LLM между webhook и ответом API превращает номер WhatsApp в AI-агента. Архитектура состоит из трёх уровней. Средний уровень — это место, где большинство команд принимают решение, определяющее, будет ли чатбот выглядеть связным или сломанным.
Первый уровень: Whapi.Cloud доставляет входящее сообщение на ваш webhook. Второй уровень: ваш сервер извлекает историю разговора из постоянного хранилища, добавляет новое сообщение, вызывает API LLM с полным контекстом разговора и отправляет ответ обратно через Whapi.Cloud. Третий уровень: провайдер LLM — OpenAI, Anthropic или Gemini — получает подготовленное контекстное окно, а не сырой payload webhook.
Уровень, который большинство команд недооценивает, — это хранилище. Разговоры сохраняют состояние — храните историю с ключом по chat_id, ограничивайте последними 15-20 репликами перед каждым вызовом LLM. Без постоянного хранилища ваш AI читает каждое сообщение так, словно разговор только что начался.
Передача агенту-человеку — второй критический паттерн: никакой AI не решает 100% разговоров корректно. Создайте явный триггер эскалации — совпадение ключевого слова, порог оценки уверенности или лимит реплик разговора — который перенаправляет чат агенту-человеку. Отметьте разговор в вашей CRM, уведомите агента и при необходимости отправьте пользователю подтверждающее сообщение. Ваш webhook продолжает доставлять сообщения во время передачи; логика маршрутизации просто меняет обработчик с AI на очередь людей.
Репозиторий GitHub Whapi.Cloud включает шаблоны ботов на Python и Node.js, реализующие этот трёхуровневый паттерн с уже написанными логикой хранилища, маршрутизации и вызовов API. Клонируйте, настройте токен и учётные данные LLM, и запустите.
Бизнес-кейсы в разных отраслях
Цикл событие→реакция применяется одинаково во всех отраслях, где WhatsApp является активным каналом коммуникации — меняется только бизнес-логика внутри.
-
E-commerce: Подтверждение заказа при событии покупки, напоминание об брошенной корзине при тайм-ауте бездействия, отслеживание подтверждений прочтения для измерения отношения доставок к ответам.
-
Медицинские клиники используют меню с ответами на кнопки для форм первичного приёма, запускают напоминания о приёмах за 24ч и за 2ч до времени слота и отправляют follow-up при неявке, когда приходит подтверждение прочтения без ответа.
-
Недвижимость: Входящий запрос запускает AI-список вариантов по бюджету и местоположению через ответы на кнопки, квалифицированные лиды маршрутизируются в очередь агента с автоматически созданной записью в CRM при том же событии.
-
Для HR и внутренних операций расписание смен рассылается как групповые сообщения, подтверждение сотрудника отслеживается через статус прочтения, а документы онбординга автоматически доставляются из триггерных событий HR-системы.
Производственные соображения
Четыре решения определяют, выдержит ли интеграция реальный трафик. Подтверждайте до обработки и дедуплицируйте по ID сообщения — пропустите любое из этих правил, и часть событий будет обработана дважды.
-
Подтверждать до обработки. Возвращайте HTTP 200 немедленно. Переносите бизнес-логику в фоновый поток или очередь задач. Whapi.Cloud повторяет при тайм-ауте — смешивание подтверждения и обработки в одном синхронном пути порождает дублирующиеся события.
-
ID сообщений — ваш ключ дедупликации. Сохраняйте каждый обработанный ID с коротким TTL (Redis отлично подходит) и пропускайте повторную обработку, когда одно и то же событие приходит дважды. Сетевые условия иногда доставляют дубликаты даже из надёжной инфраструктуры.
-
Регулируйте частоту исходящих отправок на новых номерах. Производственные каналы Whapi.Cloud не имеют жёстких ограничений скорости API. Риск — серверная защита WhatsApp от спама: внезапные всплески объёма на недавно активированных номерах привлекают санкции. Реализуйте очередь отправки с умеренными задержками между сообщениями при рассылке большим спискам с нового номера.
-
Сессии AI-чатбота требуют трёх настроек с первого дня: история с ключом по
chat_id, ограничение контекста последними 15-20 репликами перед каждым вызовом LLM, очистка истёкших сессий после настраиваемого окна бездействия. Пропустите любую из них — и будете отлаживать ошибки переполнения контекста или устаревшего состояния в продакшене.
Инфраструктура Whapi.Cloud автоматически обрабатывает обновления протокола WhatsApp — ваша интеграция не ломается, когда WhatsApp выпускает новую версию клиента. Руководство по безопасной отправке сообщений охватывает поведение, которое действительно вызывает санкции WhatsApp.
Что говорят команды, создающие на Whapi.Cloud
«Whapi.Cloud стал ключевой частью нашей коммуникации с клиентами. Мы автоматизировали обновления продуктов, уведомления о заказах и сообщения поддержки без необходимости в шаблонах или одобрениях Meta.»
— Oscar T., CTO
«Мы подключили WhatsApp к нашим рабочим процессам с помощью n8n всего за несколько минут. Никакого кода, никаких сложностей — всё заработало с первой попытки.»
— Martin P., Разработчик
«Всё просто, интуитивно понятно и легко в навигации. Документация ясная, и вся необходимая информация прямо на экране.»
— Roberto K., Веб-разработчик
Разработчики пишут бизнес-логику; Whapi.Cloud управляет доставкой в WhatsApp. Именно это разделение делает архитектуру масштабируемой — ваш код маршрутизации работает одинаково на VPS за $5 или в контейнеризированном кластере, потому что сложность протокола остаётся на стороне шлюза. Сопоставьте каждое бизнес-событие с реакцией в WhatsApp: это и есть вся архитектура.
