Это пошаговое руководство от Whapi.Cloud — провайдера API-шлюза для WhatsApp — охватывает создание готового к продакшену чат-бота для WhatsApp с GPT-4o и Node.js. WhatsApp не имеет нативной интеграции с ChatGPT: нет никакого переключателя, официального плагина или прямого endpoint'а OpenAI, который можно указать для телефонного номера. Подключение GPT-4o к WhatsApp требует трёх компонентов: API-шлюза, который принимает сообщения WhatsApp и доставляет их на ваш сервер, webhook-сервера, который обрабатывает эти сообщения, и сессионного слоя, который сохраняет историю переписки между запросами. Весь этот стек можно собрать, протестировать и развернуть менее чем за два часа.
Руководство написано для разработчиков и технических основателей, создающих AI-ассистентов для WhatsApp. Это не пятиминутный демо-туториал — это ориентированное на продакшен руководство, охватывающее весь pipeline обработки сообщений: настройку webhook'ов, управление состоянием сессии, восстановление после ошибок, оценку стоимости и HTTPS-деплой на реальном сервере. Каждый раздел разбирает режим отказа, который более простые руководства пропускают. Здесь не рассматриваются WhatsApp Flows, VoIP и официальный онбординг Meta BSP — это отдельные темы.
Что Большинство Туториалов Упускает в Чат-ботах WhatsApp с ИИ
Работающее демо — не продакшен-бот. Большинство статей о «создании бота WhatsApp с ChatGPT» останавливаются на концепции webhook'а: показывают, как получить сообщение, вызвать API OpenAI и отправить ответ. Это работает один раз, изолированно, с единственным тестовым сообщением. При появлении реальных пользователей всё ломается.
Ограничения частоты запросов, управление сессиями и HTTPS обязательны с первого дня. Вот что обычно ломается:
-
Вызовы GPT-4o без состояния: Без управления сессией каждое сообщение — это новый разговор. У бота нет памяти о том, кто пользователь и что было сказано десять секунд назад. Он не может поддерживать контекст и выстраивать диалоговый поток, делающий AI-ассистента полезным.
-
Отсутствие обработки ошибок: Если вызов OpenAI завершается сбоем или по таймауту, бот ничего не отправляет. Пользователь видит тишину и считает бота сломанным — потому что с его точки зрения так и есть. Скрытые сбои неотличимы от офлайн-ботов.
-
ngrok в продакшене: ngrok — инструмент разработки. Туннели рвутся без предупреждения, URL'ы меняются при перезапуске, управления процессами нет. Когда туннель падает, бот уходит в офлайн — молча, без уведомлений.
-
Захардкоженные API-ключи: Учётные данные в исходном коде рано или поздно попадают в историю git или логи сервера. Это провал безопасности, а не «исправлю потом».
Полный Pipeline Сообщений: WhatsApp → Whapi.Cloud → GPT-4o → WhatsApp
Разберитесь в pipeline'е, прежде чем писать первую строку кода — он определяет вашу архитектуру. Каждое сообщение пользователя проходит четыре этапа:
- WhatsApp → Whapi.Cloud: Пользователь отправляет сообщение в WhatsApp. Whapi.Cloud получает его через socket-соединение веб-сессии — тот же механизм, который использует WhatsApp Web — и доставляет на ваш сервер как HTTP POST-запрос.
- Whapi.Cloud → Ваш webhook-сервер: Ваш сервер Node.js/Express получает payload webhook'а. Извлекает ID отправителя и текст сообщения, затем передаёт запрос в ваш AI-обработчик.
- Ваш сервер → OpenAI GPT-4o: Ваш сервер вызывает API Chat Completions OpenAI с сообщением пользователя плюс полной историей переписки. GPT-4o возвращает ответ.
- Ваш сервер → Whapi.Cloud → WhatsApp: Ваш сервер отправляет ответ на endpoint отправки сообщений Whapi.Cloud. Whapi.Cloud доставляет его в WhatsApp пользователя.
Каждый этап добавляет задержку. Сам GPT-4o при стандартной нагрузке отвечает за 1–3 секунды. Доставка через WhatsApp практически мгновенная. Общее время отклика, воспринимаемое пользователем, обычно составляет 2–5 секунд — закладывайте это ожидание в дизайн продукта, а не объясняйтесь после запуска. Полный формат входящего payload'а см. в справочнике формата входящих webhook'ов.
Предварительные Требования: Что Нужно Перед Написанием Кода
Перед началом нужно настроить четыре вещи:
-
Аккаунт Whapi.Cloud: Зарегистрируйтесь на panel.whapi.cloud/register. Бесплатного плана достаточно для разработки и тестирования.
-
API-ключ OpenAI: Создайте его на platform.openai.com. Доступ к GPT-4o доступен на стандартном уровне API с тарификацией по использованию.
-
Node.js v18+: Подойдёт любой современный LTS-релиз. Понадобится установить четыре пакета:
express,openai,axiosиdotenv. -
ngrok (только для разработки): Открывает локальный сервер в интернет, чтобы Whapi.Cloud могла доставлять webhook'и во время разработки. Перед продакшеном замените на реальный HTTPS-URL.
Шаг 1 — Получите Доступ к API WhatsApp через Whapi.Cloud (Без Meta BSP)
Whapi.Cloud предоставляет доступ к webhook'ам WhatsApp без регистрации в Meta BSP. Вы подключаете номер WhatsApp, сканируя QR-код в панели управления — тот же механизм, что и в WhatsApp Web — и уже через минуту готовы отправлять и получать сообщения. Официальный путь через Meta требует регистрации BSP, предварительного согласования шаблонов и многоэтапного онбординга — процесс, занимающий дни и недели. Whapi.Cloud убирает всё это: пользователь пишет вашему боту, бот отвечает.
Чтобы подключить номер WhatsApp и зарегистрировать webhook:
- Войдите в свою панель управления Whapi.Cloud.
- Создайте новый канал. Дайте ему название (например, «AI Support Bot»).
- Отсканируйте QR-код WhatsApp-аккаунтом, который хотите использовать как номер бота. Соединение устанавливается немедленно.
- Скопируйте API-токен канала — он понадобится в файле
.env. - Перейдите в раздел Webhooks в настройках канала. Вставьте публичный HTTPS-URL вашего сервера (или URL ngrok во время разработки), например:
https://yourdomain.com/webhook. Сохраните.
После сохранения URL webhook'а Whapi.Cloud будет пересылать все входящие сообщения WhatsApp на ваш сервер как HTTP POST-запросы. Подробности настройки см. в руководстве по началу работы с Whapi.Cloud.
Шаг 2 — Создайте Express Webhook-Сервер
Начните с переменных окружения. Никогда не хардкодьте API-ключи. Используйте файл .env и загружайте его через dotenv — это держит учётные данные вне исходного кода и вне системы контроля версий:
# .env
OPENAI_API_KEY=sk-your-openai-key-here
WHAPI_TOKEN=your-whapi-cloud-token-here
WHAPI_API_URL=https://gate.whapi.cloud
PORT=3000
Установите необходимые пакеты:
npm init -y
npm install express openai axios dotenv
Теперь создайте server.js — точку входа, запускающую Express и определяющую endpoint webhook'а:
// server.js -- Entry point: starts Express and defines the webhook endpoint
require('dotenv').config();
const express = require('express');
const { handleIncomingMessage } = require('./bot');
const app = express();
app.use(express.json());
// Whapi.Cloud delivers all incoming WhatsApp messages to this endpoint as HTTP POST
app.post('/webhook', async (req, res) => {
// Respond immediately -- Whapi.Cloud expects a fast 200 before processing
res.sendStatus(200);
const messages = req.body.messages;
if (!messages || messages.length === 0) return;
for (const message of messages) {
// Skip outbound messages echoed back by Whapi.Cloud -- prevents infinite reply loops
if (message.from_me) continue;
// This guide covers text messages only; other types (image, audio) require separate handling
if (message.type !== 'text') continue;
const senderId = message.from; // WhatsApp Chat ID of the sender
const userText = message.text.body; // The user's message text
await handleIncomingMessage(senderId, userText);
}
});
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => console.log(`Webhook server running on port ${PORT}`));
Здесь важны два архитектурных решения. Первое: отвечайте 200 OK немедленно, до обработки сообщения. Если обрабатывать синхронно сначала, медленные ответы GPT-4o могут вызвать повторную доставку от Whapi.Cloud — и вы обработаете одно сообщение дважды. Второе: фильтр from_me не опционален. Whapi.Cloud зеркалирует исходящие сообщения обратно на webhook. Без этой проверки бот отвечает на собственные сообщения в бесконечном цикле. Это руководство обрабатывает текстовые сообщения; Whapi.Cloud также поддерживает типы изображений, аудио, документов и реакций — каждый доставляется на тот же endpoint webhook'а с другим полем type. Более широкую справку по реализации на Node.js см. в руководстве Whapi.Cloud по боту WhatsApp на Node.js.
Шаг 3 — Подключите GPT-4o к Обработчику Webhook'а
Модуль бота решает три задачи: загружает историю переписки пользователя, вызывает GPT-4o с этой историей и отправляет ответ обратно через API Whapi.Cloud. Операция sendMessageText требует двух параметров: to (ID чата WhatsApp получателя) и body (текст сообщения) — оба проверены по схеме API Whapi.Cloud.
// bot.js -- GPT-4o integration and Whapi.Cloud message send-back
const OpenAI = require('openai');
const axios = require('axios');
const { getHistory, saveHistory } = require('./session');
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
// System prompt defines the bot's persona, scope, and response style
// This is the most important configuration decision -- write it for your specific use case
const SYSTEM_PROMPT = {
role: 'system',
content: `You are a helpful AI assistant.
Keep replies concise -- WhatsApp users prefer short, clear messages.
If you cannot answer something, say so directly.`
};
// Calls GPT-4o with the full conversation history; returns the model's reply text
async function askGPT(history) {
const response = await openai.chat.completions.create({
model: 'gpt-4o',
messages: [SYSTEM_PROMPT, ...history],
max_tokens: 500,
temperature: 0.7
});
return response.choices[0].message.content.trim();
}
// Sends a text reply to the user via Whapi.Cloud REST API
// Required params (verified via MCP): to (string), body (string)
async function sendWhatsAppMessage(to, body) {
await axios.post(
`${process.env.WHAPI_API_URL}/messages/text`,
{ to, body },
{ headers: { Authorization: `Bearer ${process.env.WHAPI_TOKEN}` } }
);
}
// Main handler: load history → call GPT-4o → save updated history → send reply
async function handleIncomingMessage(senderId, userText) {
try {
const history = await getHistory(senderId);
// Append the new user message to history
history.push({ role: 'user', content: userText });
// Truncate to last 20 messages -- controls token cost regardless of conversation length
const truncatedHistory = history.slice(-20);
// Call GPT-4o with the full conversation context
const reply = await askGPT(truncatedHistory);
// Append the assistant reply and persist the updated history
truncatedHistory.push({ role: 'assistant', content: reply });
await saveHistory(senderId, truncatedHistory);
// Deliver the reply to the user's WhatsApp
await sendWhatsAppMessage(senderId, reply);
} catch (error) {
console.error(`[${new Date().toISOString()}] Error for ${senderId}:`, error.message);
// Always send a fallback -- never leave the user with silence
await sendWhatsAppMessage(
senderId,
'I encountered an issue processing your request. Please try again in a moment.'
).catch(e => console.error('Failed to send fallback message:', e.message));
}
}
module.exports = { handleIncomingMessage };
System prompt — это важнейшая настройка вашего чат-бота. Размытый prompt порождает офтопные или чрезмерно длинные ответы — особенно критично в WhatsApp, где пользователи ожидают коротких ответов. Пишите его под конкретный сценарий использования: определите область ответственности ассистента, стиль коммуникации и что он должен говорить, когда не может ответить. Не воспринимайте его как заглушку.
Без Состояния Сессии GPT-4o Обрабатывает Каждое Сообщение WhatsApp как Новый Разговор
GPT-4o не имеет состояния. Каждый вызов API независим — у модели нет памяти предыдущих вызовов, если вы явно не включаете предыдущие сообщения в массив messages. Без сессионного слоя каждое сообщение WhatsApp от пользователя воспринимается как начало нового разговора. Бот не может поддерживать контекст и создаёт откровенно дезориентирующий опыт для пользователей, ожидающих непрерывности.
Уровень 1 — Map в памяти (только для разработки)
Для локальной разработки и быстрого тестирования JavaScript Map с ключом по ID отправителя работает без какой-либо настройки:
// session-memory.js -- In-memory session store
// Inputs: senderId (string). Returns: history array (messages[]).
// WARNING: data is lost on every server restart. Use only in development.
const sessions = new Map();
function getHistory(senderId) {
if (!sessions.has(senderId)) {
sessions.set(senderId, []);
}
return Promise.resolve(sessions.get(senderId));
}
function saveHistory(senderId, history) {
sessions.set(senderId, history);
return Promise.resolve();
}
module.exports = { getHistory, saveHistory };
Критическое ограничение: данные живут в памяти процесса. Перезапуск сервера стирает все переписки. При наличии конкурентных пользователей также возникает риск неограниченного роста памяти без политики вытеснения. Это приемлемо для тестирования, но неприемлемо для продакшена.
Уровень 2 — Redis с TTL (продакшен)
Redis с TTL — правильное хранилище сессий для продакшен-ботов WhatsApp с конкурентными пользователями. Оно переживает перезапуски сервера, обрабатывает несколько экземпляров приложения без конфликтов и автоматически удаляет устаревшие сессии — в соответствии с 24-часовым окном переписки самого WhatsApp:
// session-redis.js -- Redis-backed session store for production
// Inputs: senderId (string), history array. Outputs: history array.
// TTL of 24 hours mirrors the WhatsApp session window -- sessions expire together.
const redis = require('redis');
const client = redis.createClient({ url: process.env.REDIS_URL || 'redis://localhost:6379' });
client.connect().catch(console.error);
const SESSION_TTL_SECONDS = 86400; // 24 hours
async function getHistory(senderId) {
const data = await client.get(`session:${senderId}`);
return data ? JSON.parse(data) : [];
}
async function saveHistory(senderId, history) {
await client.setEx(
`session:${senderId}`,
SESSION_TTL_SECONDS,
JSON.stringify(history)
);
}
module.exports = { getHistory, saveHistory };
Добавьте пакет redis (v4+) в зависимости и установите переменную окружения REDIS_URL. Чтобы переключиться с хранилища в памяти на Redis, измените одну строку в bot.js: require('./session-memory') становится require('./session-redis'). Интерфейс идентичен — оба модуля экспортируют getHistory и saveHistory с одинаковой сигнатурой.
| Подход | Персистентность | Конкурентные пользователи | Усилия по настройке | Рекомендуется для |
|---|---|---|---|---|
| Map в памяти | Теряется при перезапуске | Только один экземпляр | Нет | Локальная разработка |
| Redis с TTL | Переживает перезапуски | Безопасен для нескольких экземпляров | Умеренные | Продакшен |
Обработка Ошибок: Каждый Скрытый Сбой GPT-4o Оставляет Пользователя без Ответа
Каждый продакшен-бот WhatsApp нуждается в обработке ошибок. Это не опция и не «улучшение для v2». Если вызов GPT-4o завершается сбоем — из-за таймаута OpenAI, достижения лимита частоты запросов или сетевой ошибки — и у вас нет обработчика ошибок, пользователь ничего не получит. Он решит, что бот сломан. В большинстве случаев будет прав.
Пример bot.js выше включает базовый try/catch с fallback-сообщением. Расширьте его классификацией ошибок, чтобы логи были actionable:
// Extended error classification inside handleIncomingMessage's catch block
} catch (error) {
const timestamp = new Date().toISOString();
if (error.status === 429) {
// OpenAI rate limit -- you have exceeded tokens-per-minute for this API key
// Consider queuing requests or implementing exponential backoff
console.warn(`[${timestamp}] OpenAI rate limit hit for ${senderId}. Status: 429`);
} else if (error.code === 'ECONNABORTED' || error.code === 'ETIMEDOUT') {
// OpenAI request took too long -- network issue or model overload
console.warn(`[${timestamp}] OpenAI request timed out for ${senderId}`);
} else {
// Unknown error -- log fully for investigation
console.error(`[${timestamp}] Unhandled error for ${senderId}:`, error.message);
}
// Send user-visible fallback regardless of error type
try {
await sendWhatsAppMessage(
senderId,
'I am having trouble right now. Please try again in a moment.'
);
} catch (sendError) {
// If even the fallback fails, the Whapi.Cloud connection itself is likely broken
console.error(`[${timestamp}] Fallback send failed for ${senderId}:`, sendError.message);
}
}
Всегда логируйте ошибки с временными метками и ID отправителей. Записи без меток времени практически бесполезны в продакшене — вы не сможете сопоставить их с жалобами пользователей, инцидентами статуса OpenAI или логами доставки Whapi.Cloud. Если отправка fallback-сообщения тоже не удалась — это отдельный сигнал: соединение с Whapi.Cloud разорвано, а не только вызов OpenAI. Воспринимайте эти два типа сбоев как разные алерты.
О лимитах частоты запросов OpenAI: HTTP 429 означает превышение лимита токенов в минуту. Немедленное решение — повторная попытка с экспоненциальной задержкой. Структурное решение — при повторении проблемы — поставить входящие сообщения в очередь и обрабатывать их с ограничением параллелизма, вместо запуска вызова GPT-4o на каждый webhook одновременно.
Сколько Стоит AI-Бот WhatsApp? Стоимость GPT-4o за Сообщение
GPT-4o стоит примерно $0,002–$0,005 за среднестатистический обмен сообщениями в WhatsApp при стандартном использовании токенов. Оценка предполагает типичное сообщение пользователя в 20–50 токенов и ответ модели в 100–200 токенов, с историей переписки из 10–15 предыдущих ходов в каждом вызове API. По этим расценкам 10 000 обменов сообщениями обходятся примерно в $20–$50 в месяц в виде оплаты API OpenAI.
Стоимость токенов прямо пропорциональна длине истории. Ограничение до 20 сообщений — как в коде выше — делает затраты на каждый вызов предсказуемыми вне зависимости от общей длины переписки. Вы платите за 20 ходов контекста за вызов, сколько бы длинным ни был разговор.
GPT-4o стоит дороже за токен, чем GPT-3.5-turbo, но разница в качестве существенна для открытых диалоговых задач. Для структурированных ответов шаблонного типа, где достаточно GPT-3.5-turbo, замена модели — это однострочное изменение: замените 'gpt-4o' на 'gpt-3.5-turbo' в функции askGPT. Анализируйте реальное использование и удовлетворённость пользователей перед понижением — преждевременная оптимизация здесь обычно выражается в регрессиях качества в тикетах поддержки, а не в числах бенчмарков.
Whapi.Cloud использует подписочную модель ценообразования без собственных поминутных или посообщенческих сборов. Актуальные цены на тарифы см. на странице тарифных планов Whapi.Cloud для расчёта полной стоимости стека при вашем объёме сообщений.
От ngrok к Продакшену: Деплой AI-Бота WhatsApp на Реальный Сервер
Запускать ngrok в продакшене — не стратегия деплоя: переходите на реальный сервер до того, как поделитесь ботом с реальными пользователями. Любой Linux-VPS с 1 ГБ ОЗУ справится с одноканальным ботом при умеренном объёме сообщений. Вам нужен Node.js, работающий Redis и доменное имя с действующим HTTPS-сертификатом. WhatsApp блокирует доставку webhook'ов на URL без HTTPS. Обходного пути нет.
Управление Процессами с PM2
PM2 — стандартный менеджер процессов для Node.js в продакшене. Он автоматически перезапускает сервер при аварии и при перезагрузке системы:
# Install PM2 globally
npm install -g pm2
# Start the bot server under PM2 supervision
pm2 start server.js --name "whatsapp-ai-bot"
# Persist the PM2 process list across server reboots
pm2 save
# Generate and configure the system startup script
pm2 startup
После запуска pm2 startup скопируйте и выполните команду, которую он выводит — это регистрирует PM2 в системе инициализации, чтобы бот автоматически перезапускался после перезагрузки сервера.
HTTPS с Nginx и Let's Encrypt
Используйте Nginx как обратный прокси перед сервером Node.js. Приложение Express работает на http://localhost:3000 внутри. Nginx завершает SSL и проксирует запросы. Получите сертификат от Let's Encrypt через Certbot:
# Install Nginx and Certbot (Ubuntu/Debian)
sudo apt update && sudo apt install nginx certbot python3-certbot-nginx -y
# Obtain and auto-configure an SSL certificate for your domain
sudo certbot --nginx -d yourdomain.com
# Certbot configures Nginx automatically and sets up certificate renewal
# Your webhook endpoint will be available at: https://yourdomain.com/webhook
После запуска Certbot обновите URL webhook'а в панели управления Whapi.Cloud до https://yourdomain.com/webhook. Используйте функцию тестирования webhook'а в панели для проверки доставки. Если логи сервера показывают получение тестового payload'а, продакшен-настройка работает.
Чеклист Готовности к Продакшену
-
HTTPS включён с действующим сертификатом (Let's Encrypt через Certbot)
-
PM2 работает с настроенной персистентностью запуска
-
Redis работает с парольной аутентификацией, не открыт публично
-
Все секреты в переменных окружения
.env— не в исходном коде и не в истории git -
Обработка ошибок с видимыми пользователю fallback-сообщениями и серверным логированием с временными метками
-
Ограничение истории сообщений для контроля затрат на токены в длинных переписках
-
Фильтр
from_meактивен — предотвращает ответы бота на собственные исходящие сообщения -
URL webhook'а обновлён до продакшен-HTTPS-домена в панели управления Whapi.Cloud
-
Тест webhook'а подтверждён — тестовый payload получен и зафиксирован сервером
Более 3000 команд ежедневно используют Whapi.Cloud в продакшене. Инфраструктурные защиты, включая уникальные прокси и региональных провайдеров, обеспечивают слой подключения. Ваша ответственность — прикладной слой: состояние сессии, обработка ошибок и system prompt, определяющий, что ваш бот реально делает. Сделайте это правильно — и у вас будет бот, достойный запуска. Руководство по безопасной работе вашего номера WhatsApp в масштабе см. в гайде Whapi.Cloud по предотвращению блокировок аккаунта.
Whapi.Cloud подключает ваш номер WhatsApp к серверу менее чем за минуту — без регистрации Meta BSP, без процесса согласования шаблонов, без периода ожидания. Отсканируйте QR-код, вставьте URL webhook'а и начните получать сообщения. Всё, что вам нужно для реализации, уже есть в этом руководстве.
