TL;DR: Забудьте об устаревших PHP SDK и нестабильных библиотеках эмуляции браузера. Используйте чистый PHP-скрипт на базе встроенного cURL для быстрого развертывания на обычном хостинге или масштабируйте решение с помощью Guzzle-клиента с автозагрузкой PSR-4 через Composer. Подключите любой номер по QR-коду за 2 минуты, обязательно настройте защиту от бесконечных циклов автоответов и автоматизируйте группы WhatsApp до 1024 участников по фиксированной подписке Whapi.Cloud.
Это пошаговое руководство от Whapi.Cloud, провайдера шлюза WhatsApp API, объясняет, как создать стабильный WhatsApp-бот на PHP 8.x с использованием как встроенного cURL, так и структурированного ООП-подхода. Подключение номера WhatsApp через веб-сокеты сессий позволяет обойти бизнес-верификацию Meta, настроить интеграцию через вебхуки и отправлять неограниченное количество сообщений по фиксированной ежемесячной подписке.
Статья ориентирована на PHP-разработчиков, которым необходимо автоматизировать группы и каналы WhatsApp без использования тяжеловесных фреймворков. Мы разберем как готовый к копированию скрипт для виртуального хостинга, так и современную, поддерживаемую структуру классов для PHP 8.2–8.4. Мы не будем касаться создания очередей в базе данных или асинхронных брокеров сообщений, сосредоточившись на базовой механике интеграции и защите от бесконечных циклов.
Почему разработчики отказываются от официального WhatsApp Cloud API от Meta
Поклиентская тарификация диалогов и жесткая переклассификация категорий со стороны Meta делают расходы на исходящие уведомления непредсказуемыми. Стартапы сталкиваются с внезапным десятикратным ростом затрат и необходимостью согласовывать каждый шаблон сообщения перед отправкой.
При официальной модели тарификации Meta любое доставленное уведомление может повлечь за собой непредвиденные расходы в случае изменения категории диалога. Если автоматические алгоритмы Meta переведут стандартное обновление заказа из категории «сервисных» (utility) в «маркетинговые» (marketing), стоимость доставки сообщения может вырасти в десять раз. Кроме того, официальное подключение требует верификации в Facebook Business Manager, соблюдения строгих правил сбора согласий и использования предварительно одобренных HSM-шаблонов, что исключает возможность живого, неформального общения с пользователями.
Whapi.Cloud решает эти бюрократические проблемы, подключаясь к WhatsApp через сокеты веб-сессий — точно так же, как это делает WhatsApp Web. Это позволяет запускать бота по фиксированной ежемесячной подписке с безлимитными сообщениями, без согласования шаблонов и с полным доступом к нативным функциям WhatsApp, включая группы и каналы. Ниже приведено прямое сравнение двух подходов.
| Операционный показатель | Официальный Meta Cloud API | Шлюз Whapi.Cloud API |
|---|---|---|
| Время настройки и запуска | От нескольких дней до недель (требуется Facebook Business Manager) | Менее 2 минут (сканирование QR-кода) |
| Верификация бизнеса | Обязательна перед запуском коммерческих объемов | Не требуется (подходит любой активный номер телефона) |
| Модель тарификации | Поклиентская оплата за диалоги + наценки провайдеров (BSP) | Фиксированная ежемесячная подписка (безлимитные сообщения) |
| Лимит участников в группах | Строго ограничен (максимум 8 участников, жесткие лимиты) | До 1024 участников в группе (нативное ограничение WhatsApp) |
| Поддержка каналов и статусов | Отсутствует | Полный доступ через API для создания и публикации обновлений |
| Согласование шаблонов | Обязательно для всех исходящих сообщений от бизнеса | Без ограничений (отправка любого текста или медиафайлов) |
Мы сталкивались со случаями, когда бюджеты проектов вырастали в десять раз за одну ночь из-за того, что обычное сервисное уведомление клиента классифицировалось алгоритмом Meta как маркетинговое. Использование API-шлюза позволяет независимым разработчикам и стартапам полностью контролировать экономику рассылок, гарантируя предсказуемые ежемесячные расходы независимо от объема общения.
Шаг 1: Подключите номер WhatsApp по QR-коду за 2 минуты
Для обхода бизнес-верификации Meta понадобятся только стандартный аккаунт WhatsApp и сканирование QR-кода. Это установит стабильное сокет-соединение веб-сессии, открывая мгновенный доступ к API для отправки сообщений и управления группами.
Сканирование QR-кода создает устойчивое сокет-соединение веб-сессии, благодаря чему ваш PHP-скрипт полностью обходит необходимость регистрации бизнеса. Вы можете мгновенно привязать любой активный номер WhatsApp — как личный, так и бизнес-аккаунт. Это позволяет разрабатывать и тестировать бота на собственном устройстве перед его переносом на выделенный рабочий номер. Для начала выберите один из тарифов с фиксированной оплатой Whapi.Cloud, соответствующий вашим объемам отправки.
Чтобы подключить номер, выполните следующие действия:
-
Создайте аккаунт: Зарегистрируйтесь на портале регистрации Whapi.Cloud. Это бесплатно и займет менее 30 секунд.
-
Сгенерируйте QR-код: Перейдите в настройки вашего канала, чтобы увидеть уникальный QR-код для подключения. Панель управления формирует его динамически на основе запущенного инстанса веб-сессии.
-
Привяжите устройство: Откройте WhatsApp на телефоне, перейдите в «Настройки» > «Связанные устройства», нажмите «Привязка устройства» и отсканируйте QR-код.
-
Скопируйте токен: Скопируйте ваш уникальный API-токен из панели управления. Храните его в безопасности, так как он предоставляет полный программный доступ к вашему аккаунту WhatsApp.
Шаг 2: Как вывести локальный сервер в интернет с помощью Ngrok
Вебхукам WhatsApp требуется безопасный публичный HTTPS-адрес для доставки входящих сообщений в режиме реального времени. Ngrok создает защищенный туннель к вашему локальному PHP-серверу, позволяя мгновенно тестировать интеграцию без развертывания на внешнем VPS.
Вебхуки не смогут связаться с вашим локальным сервером, если он находится за NAT или брандмауэром, без использования защищенного туннеля. Ngrok на этапе разработки избавляет от необходимости загружать код на сервер или настраивать DNS домена при каждом изменении строки кода. Все входящие запросы перенаправляются напрямую на ваш локальный Apache или встроенный PHP-сервер разработки.
Чтобы подготовить локальное окружение к приему вебхуков, выполните следующие шаги:
-
Запустите локальный сервер: Запустите встроенный веб-сервер PHP в корневой директории вашего проекта командой
php -S localhost:80. -
Запустите Ngrok: Выполните команду
ngrok http 80в терминале. Ngrok сгенерирует безопасный HTTPS-адрес перенаправления (например,https://abc-123.ngrok-free.app), связывающий внешнюю сеть с вашим компьютером. -
Укажите адрес вебхука: Включите вебхуки в панели управления Whapi.Cloud и вставьте ваш HTTPS-адрес от Ngrok с указанием пути к скрипту (например,
https://abc-123.ngrok-free.app/index.php).
Шаг 3: Пишем WhatsApp-бот в один файл без внешних зависимостей
Простой PHP-скрипт в один файл, использующий встроенные функции декодирования JSON и cURL-запросы, полностью совместим с любым недорогим виртуальным хостингом. Такое легковесное решение отлично подходит для создания простых автоответов.
Всегда фильтруйте входящие вебхуки: защита от бесконечного цикла — это критически важный барьер, не позволяющий боту отвечать на собственные сообщения. Когда бот отправляет сообщение, WhatsApp высылает исходящее уведомление обратно на ваш скрипт. Если обработчик воспримет это событие как новое входящее сообщение и попытается ответить, возникнет бесконечный цикл. Это израсходует весь лимит сообщений за считанные минуты и может привести к блокировке номера. Мы называем этот механизм защитой от бесконечных циклов (self-loop guard). Полный список полей вебхука доступен в документации для разработчиков.
Создайте файл index.php в корневой директории вашего сервера и добавьте следующий готовый код без внешних зависимостей:
<?php
// Set your Whapi.Cloud API token and base URL
$apiToken = 'YOUR_API_TOKEN_HERE';
$baseUrl = 'https://gate.whapi.cloud';
// Capture the raw HTTP POST request sent by Whapi's webhook system
$inputJson = file_get_contents('php://input');
$data = json_decode($inputJson, true);
// If the payload is empty or doesn't contain messages, silent exit
if (!$data || !isset($data['messages'])) {
exit;
}
// Iterate through the array of incoming messages
foreach ($data['messages'] as $message) {
// ENFORCE SELF-LOOP GUARD: Skip messages sent by the bot's own connected number
if (isset($message['from_me']) && $message['from_me'] === true) {
continue;
}
$chatId = $message['chat_id'];
$text = isset($message['text']['body']) ? trim($message['text']['body']) : '';
// Simple keyword processing
if (strtolower($text) === 'ping') {
$replyPayload = [
'to' => $chatId,
'body' => 'pong'
];
// Send native cURL POST request to Whapi's sendMessageText endpoint
$ch = curl_init("{$baseUrl}/messages/text");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($replyPayload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer {$apiToken}",
"Content-Type: application/json"
]);
$response = curl_exec($ch);
curl_close($ch);
}
}
Важно: Опасность бесконечного цикла автоответов
Отсутствие проверки флага from_me — самая частая ошибка при разработке WhatsApp-ботов. Поскольку уведомления WhatsApp содержат как входящие сообщения, так и ваши собственные ответы, бот без этой проверки начнет бесконечно отвечать самому себе. Это быстро исчерпает лимит сообщений и приведет к немедленной блокировке номера.
Приведенный код использует стандартную библиотеку cURL, что делает его совместимым с любым хостинг-провайдером — даже с недорогими тарифами cPanel со строгими настройками безопасности. Скрипт валидирует входящие пакеты, извлекает текстовые строки и отправляет чистый POST-запрос к эндпоинту /messages/text.
Шаг 4: Переходим на ООП: бот с использованием Composer и Guzzle
Масштабирование PHP-бота требует структурированной архитектуры классов с автозагрузкой по стандарту PSR-4. Использование HTTP-клиента Guzzle предотвращает блокировку пула воркеров PHP-FPM медленными сетевыми запросами, обеспечивая стабильность при высокой нагрузке.
Использование HTTP-клиента Guzzle позволяет безопасно обрабатывать сетевые ошибки и таймауты соединений, защищая пул PHP-FPM от зависаний. В высоконагруженных приложениях синхронные cURL-скрипты блокируют поток выполнения на время ожидания ответа, что быстро истощает ресурсы сервера. ООП-обертка корректно обрабатывает сбои HTTP-запросов, логируя ошибки без остановки слушателя вебхуков.
В этой статье мы не рассматриваем создание очередей в базе данных или асинхронных брокеров сообщений — для небольших проектов вполне достаточно синхронного выполнения. Когда объем превысит 10 000 сообщений в день, имеет смысл перейти на очереди Laravel или Symfony Messenger. Для начала создайте файл composer.json, чтобы настроить автозагрузку и определить зависимости:
{
"name": "whapi/whatsapp-php-bot",
"description": "Professional OOP WhatsApp Bot using PSR-4, Guzzle, and PHP 8.x",
"type": "project",
"require": {
"php": ">=8.1",
"guzzlehttp/guzzle": "^7.8"
},
"autoload": {
"psr-4": {
"App\\": "src/"
}
}
}
Выполните команду composer install в директории проекта, чтобы загрузить Guzzle и сгенерировать файлы автозагрузки. Затем создайте папку src/ и разместите основную логику бота в файле src/WhatsAppBot.php:
<?php
namespace App;
use GuzzleHttp\Client;
use GuzzleHttp\Exception\GuzzleException;
class WhatsAppBot
{
private Client $client;
private string $apiToken;
public function __construct(string $apiToken)
{
$this->apiToken = $apiToken;
$this->client = new Client([
'base_uri' => 'https://gate.whapi.cloud/',
'timeout' => 5.0,
'headers' => [
'Authorization' => "Bearer {$this->apiToken}",
'Content-Type' => 'application/json',
'Accept' => 'application/json'
]
]);
}
/**
* Sends a text message to a specific WhatsApp contact or Chat ID.
*/
public function sendTextMessage(string $to, string $body): bool
{
try {
$response = $this->client->post('messages/text', [
'json' => [
'to' => $to,
'body' => $body
]
]);
return $response->getStatusCode() === 200;
} catch (GuzzleException $e) {
error_log("WhatsApp API delivery failure: " . $e->getMessage());
return false;
}
}
/**
* Programmatically creates a WhatsApp Group and adds participants.
*/
public function createGroup(string $subject, array $participants): ?string
{
try {
$response = $this->client->post('groups', [
'json' => [
'subject' => $subject,
'participants' => $participants
]
]);
$body = json_decode($response->getBody()->getContents(), true);
return $body['group_id'] ?? null;
} catch (GuzzleException $e) {
error_log("WhatsApp API group creation failure: " . $e->getMessage());
return null;
}
}
}
Теперь создадим публичный шлюз для приема вебхуков. Создайте папку public/ и напишите входной скрипт в файле public/webhook.php:
<?php
// Подключаем автозагрузчик PSR-4
require_once __DIR__ . '/../vendor/autoload.php';
use App\WhatsAppBot;
$apiToken = 'YOUR_API_TOKEN_HERE';
$bot = new WhatsAppBot($apiToken);
// Обрабатываем входящий поток JSON-событий
$inputJson = file_get_contents('php://input');
$data = json_decode($inputJson, true);
if (!$data || !isset($data['messages'])) {
exit;
}
foreach ($data['messages'] as $message) {
// ВАЖНО: Исключаем обработку собственных исходящих сообщений для защиты от циклов
if (isset($message['from_me']) && $message['from_me'] === true) {
continue;
}
$chatId = $message['chat_id'];
$text = isset($message['text']['body']) ? trim($message['text']['body']) : '';
if (strtolower($text) === 'ping') {
$bot->sendTextMessage($chatId, 'pong');
}
}
Организация кода по стандартам автозагрузки PSR-4 позволяет легко интегрировать эту структуру классов в современные PHP-фреймворки, такие как Laravel или Symfony. При этом обработчик вебхуков остается чистым, а ресурсоемкие сетевые операции и логирование ошибок делегируются изолированному Guzzle-клиенту.
Шаг 5: Автоматизация групп и каналов в WhatsApp
Whapi.Cloud открывает полный программный контроль над группами WhatsApp (до 1024 участников) и публичными каналами вещания. В отличие от официального API от Meta, вы можете управлять сообществами и делать массовые рассылки без платы за каждый начатый диалог.
Программное создание групп и автоматическая публикация в каналах позволяют обойти ограничения на личные сообщения (1:1), действующие для обычных чатов. В официальном WhatsApp Business API отправка рассылок требует согласования шаблонов, влечет за собой расходы на каждое сообщение и ограничивает размер групп всего 8 участниками. С Whapi.Cloud вы получаете полный контроль: создавайте группы до 1024 человек и публикуйте посты в каналы без предварительного одобрения шаблонов и дополнительных комиссий за трафик — все это доступно в рамках фиксированной ежемесячной подписки. Эти возможности поддерживаются нашими специализированными решениями WhatsApp Groups API и WhatsApp Channels API.
Вот пример того, как использовать разработанный ООП-класс для программного создания группы с двумя участниками и отправки в нее приветственного сообщения:
<?php
require_once __DIR__ . '/../vendor/autoload.php';
use App\WhatsAppBot;
$apiToken = 'YOUR_API_TOKEN_HERE';
$bot = new WhatsAppBot($apiToken);
// Указываем участников, используя их WhatsApp Chat ID (номер телефона с суффиксом @s.whatsapp.net)
$participants = [
'[email protected]',
'[email protected]'
];
// Программно создаем группу через эндпоинт createGroup
$groupId = $bot->createGroup('PHP Dev Automation', $participants);
if ($groupId) {
// Отправляем сообщение напрямую в созданную группу по её Chat ID
$bot->sendTextMessage($groupId, 'Welcome to the PHP Dev Automation group! This message was sent programmatically.');
echo "Group successfully created! ID: " . $groupId;
} else {
echo "Group creation failed. Check error logs for details.";
}
Вы можете использовать ту же функцию sendTextMessage для публикации обновлений в вашем WhatsApp-канале. Достаточно заменить параметр $to на Chat ID канала (в формате [email protected] or с соответствующим суффиксом канала). Сокет-шлюз обрабатывает все типы получателей одинаково, отправляя JSON-данные напрямую через установленное сокет-соединение.
Бесплатная разработка: как использовать постоянную песочницу Whapi.Cloud
Постоянная песочница Whapi.Cloud предоставляет разработчикам пять бесплатных активных чатов для тестирования. Вы можете полностью спроектировать логику, отладить вебхуки и протестировать защиту от циклов перед переходом на коммерческий тариф.
Бесплатный тариф Sandbox не ограничен по времени и позволяет вести до 5 активных диалогов для тестирования. Это дает возможность настроить интеграцию на PHP, зарегистрировать вебхуки, проверить защиту от петель автоответов и протестировать отправку медиафайлов без привязки банковской карты. Когда бот будет полностью готов, для переноса в продакшен достаточно просто заменить API-токен в коде.
Песочница разработчика включает постоянный лимит в 150 сообщений в день и 1000 запросов к API в месяц, чего более чем достаточно для отладки, тестирования и создания прототипа.
Как защитить номер WhatsApp от блокировок в продакшене
Алгоритмы защиты от спама в WhatsApp работают на стороне сервера, отслеживая резкие всплески отправки одинаковых сообщений «холодным» контактам. Чтобы обезопасить номер, требуются постепенный прогрев, случайные задержки имитации ввода текста и поддержание двустороннего диалога.
Обнаружение спама полностью автоматизировано и происходит на стороне сервера: резкий рост объема одинаковых исходящих сообщений — самый быстрый способ получить бан. Поскольку Whapi.Cloud работает через веб-сокеты сессий, WhatsApp оценивает вашу активность точно так же, как если бы вы использовали обычный браузер. Если с нового номера за час уходит 5000 одинаковых рекламных сообщений без единого входящего ответа, фильтры безопасности мгновенно заблокируют аккаунт.
Для защиты ваших номеров соблюдайте четыре правила в продакшене:
-
Прогревайте новые номера: Постепенно увеличивайте объем отправки в течение 7–10 дней. Начните с 50 сообщений в первый день и повышайте лимиты только после обмена сообщениями с доверенными контактами.
-
Добавляйте случайные задержки ввода: Используйте параметр Whapi
typing_time, чтобы сделать паузу в 2–5 секунд перед отправкой ответа. Это имитирует реальный набор текста человеком. -
Используйте каналы для массовых рассылок: Если нужно отправить уведомление тысячам пользователей, отдавайте предпочтение каналам WhatsApp. Этот формат требует от пользователей осознанного вступления, что исключает жалобы на спам.
-
Следите за показателем готовности номера: Проверяйте встроенный индекс готовности номера (Readiness Score) в панели управления перед запуском массовых рассылок.
По нашему опыту, номера, прошедшие 7–10 дней предварительного прогрева (двустороннего общения с реальными контактами), сохраняют высокий уровень доверия системы и практически не подвержены автоматическим блокировкам. Перед запуском автоматизации убедитесь, что вы уделили время прогреву. Подробные рекомендации можно найти в руководстве Whapi.Cloud по предотвращению блокировок.
Решение частых проблем при настройке и запуске бота
Большинство сбоев при развертывании бота связаны с истечением срока действия туннеля Ngrok, отсутствием защиты от бесконечных циклов или ограничениями портов на виртуальном хостинге. Систематическая проверка этих трех моментов решает практически все типичные проблемы.
Если бот перестал отвечать, не спешите переписывать код — сначала проверьте три ключевые точки интеграции. При отсутствии реакции сервера на входящие события убедитесь в следующем:
-
Истек срок действия туннеля Ngrok: Бесплатные туннели Ngrok меняют адрес при каждом перезапуске. Если бот перестал получать вебхуки, проверьте, совпадает ли текущий адрес Ngrok с URL-адресом вебхука в личном кабинете Whapi.Cloud.
-
Отсутствует защита от бесконечного цикла (Self-Loop Guard): Если бот дублирует ответы или зацикливается, убедитесь, что проверка флага
from_meактивна. Это должно быть самым первым действием внутри цикла обработки сообщений. -
Блокировка портов на хостинге: Некоторые провайдеры виртуального хостинга cPanel блокируют исходящие соединения на нестандартные порты. Убедитесь, что брандмауэр вашего сервера разрешает исходящие SSL-соединения Guzzle к
gate.whapi.cloudпо порту 443.
При возникновении любых вопросов вы можете обратиться в службу поддержки Whapi.Cloud через чат-виджет на сайте whapi.cloud. Наша команда оперативно помогает разработчикам решать технические проблемы, избавляя от долгих ожиданий ответов на тикеты, характерных для крупных корпоративных платформ.
