Коротко: Установка Whapi Agent Skill одной командой предотвращает три самые частые ошибки, которые AI-агенты допускают при работе с WhatsApp API: неверные Chat ID, неправильные заголовки авторизации и polling вместо webhooks. Skill кодифицирует 7 категорий референсов и работает с Cursor, Claude Code, Codex, GitHub Copilot и более чем 40 другими агентами.
Установка: npx skills add Whapi-Cloud/whapi-whatsapp-api-skill · Требуется Node.js 18+ · GitHub · Документация
Что такое Agent Skill?
Когда вы просите Cursor или Claude Code собрать бот для WhatsApp, агент обращается к обучающим данным, охватывающим тысячи API — и ни один из них не является специфически авторитетным для Whapi.Cloud в её нынешнем виде. Результат — код, выглядящий правдоподобно, но молча ломающийся в продакшене.
Agent Skill — это исправление. Это структурированный файл знаний (SKILL.md), который лежит в вашем проекте и автоматически загружается в контекст агента, когда тот распознаёт релевантную задачу. Воспринимайте его как постоянные инструкции: «При разработке с WhatsApp API от Whapi.Cloud используй именно эти имена полей, паттерны авторизации и архитектурные правила».
Стандарт был представлен в конце 2025 года через vercel-labs/skills и сегодня поддерживается более чем 40 AI-агентами. Skill устанавливается одной командой npx skills add. Без конфигурационных файлов, без boilerplate — агент подхватывает её автоматически.
MCP — это кладовая, а Agent Skill — рецепт. MCP-сервер Whapi даёт вашему агенту 165 инструментов для вызова WhatsApp API. Agent Skill учит его, какой инструмент вызывать в какой ситуации, с какими параметрами и каких паттернов избегать. Вместе они закрывают самые распространённые режимы сбоя в WhatsApp-коде, сгенерированном AI.
Проблема: что AI-агенты делают не так с WhatsApp
AI-агенты для кодинга — общего назначения. Без конкретного grounding'а они генерируют код, который выглядит корректно, но падает в runtime. Ни одна из этих ошибок не всплывает на этапе компиляции — они проявляются только тогда, когда API возвращает 400 или 401.
Вот десять самых частых ошибок и то, как Whapi Agent Skill их исправляет:
| Что пишет AI (неправильно) | Что требует Whapi.Cloud (правильно) | Последствия |
|---|---|---|
[email protected] |
[email protected] |
Устаревший формат — каждая отправка возвращает 400 |
{"message": "hello"} |
{"body": "hello"} |
Неправильное имя поля — сообщение молча отбрасывается |
{"chat_id": "..."} |
{"to": "..."} |
Инструменты отправки используют to, а не chat_id |
X-API-Key: your_token |
Authorization: Bearer your_token |
Неверный заголовок авторизации — 401 на каждый запрос |
API_KEY=your_token |
API_TOKEN=your_token |
Неверное имя переменной окружения — MCP-сервер её не подхватывает |
Общий sendMessage() |
sendMessageText, sendMessageImage и т. д. |
Универсального инструмента не существует — ошибка 400 |
Polling getMessages в цикле |
Webhook через updateChannelSettings |
Задержка 5+ секунд, сжигает rate limit, теряет события |
| Отвечать на все входящие сообщения | Фильтровать from_me: true перед ответом |
Без этого фильтра бот отвечает сам себе в бесконечном цикле |
sendBulkMessages(recipients: [...]) |
sendMessageText по одному получателю, с задержками |
Такого инструмента не существует — галлюцинированный endpoint |
{"webhookUrl": "https://..."} |
{"webhooks": [{"url": "...", "mode": "body", ...}]} |
Конфигурация webhook должна использовать вложенный массив webhooks[] |
Agent Skill vs. MCP: два слоя, один стек
Если вы уже используете MCP-сервер Whapi, Agent Skill добавляет слой знаний, которого сам по себе MCP не даёт. Whapi.Cloud — единственный провайдер WhatsApp API, поставляющий оба компонента.
| Agent Skill | MCP-сервер (whapi-mcp) | |
|---|---|---|
| Что даёт | Знания: как правильно использовать API | Возможности: 165 инструментов для вызова API |
| Способ установки | npx skills add ... |
Добавить запись в mcp.json |
| Нужен аккаунт Whapi? | Нет — грузится как контекст | Да — нужен валидный API_TOKEN |
| Делает вызовы к API? | Нет — только справочный файл | Да — выполняет реальные вызовы API |
| Предотвращает галлюцинации? | Да — это его главная задача | Частично — схемы инструментов помогают, паттерны — нет |
Что содержит Whapi Agent Skill
Whapi Agent Skill кодифицирует 7 категорий референсов, чтобы ваш AI-агент пришёл к API уже зная правила. Каждый файл референса включает правильные и неправильные примеры, антигаллюцинационные чек-листы и заметки, специфичные для Whapi.
1. Основные концепты (КРИТИЧНО)
Ошибки в формате Chat ID — самая частая одиночная причина ошибок 400 в WhatsApp-коде, сгенерированном AI. Skill кодифицирует три формата:
- Личный чат:
{phone}@s.whatsapp.net— например,[email protected] - Группа:
{id}@g.us— получайте черезgetGroups; никогда не конструируйте ID вручную - Канал / Newsletter:
{id}@newsletter— получайте черезgetNewsletters
Также покрывает настройку MCP и авторизацию Authorization: Bearer {token} с корректным именем переменной окружения API_TOKEN.
2. Отправка сообщений (КРИТИЧНО)
Полное дерево решений, чтобы агент выбирал правильный инструмент для каждого типа контента:
- Текст →
sendMessageText(поле:body) - Изображение JPG/PNG/WebP →
sendMessageImage(поле:media) - Видео MP4 →
sendMessageVideo - GIF (MP4-файл) →
sendMessageGif - Кругляшок-видео →
sendMessageShort - Аудиофайл MP3/WAV →
sendMessageAudio - Голосовое сообщение OGG Opus →
sendMessageVoice - Документ/PDF →
sendMessageDocument - Стикер WebP →
sendMessageSticker - Опрос →
sendMessagePoll - Интерактивные кнопки/список →
sendMessageInteractive - Геолокация →
sendMessageLocation
3. Получение сообщений (КРИТИЧНО)
Polling getMessages в цикле — это антипаттерн; получение сообщений WhatsApp требует исключительно webhooks. Skill обучает корректной вложенной структуре конфигурации webhook и объясняет, почему polling не работает в масштабе: задержка 5+ секунд, постоянное потребление rate limit, пропущенные события между интервалами опроса.
4. Группы (ВЫСОКИЙ)
Создание групп, управление участниками, генерация инвайт-ссылок, назначение ролей администратора. Skill покрывает полный жизненный цикл через createGroup, getGroups и инструменты управления участниками. ID групп используют формат @g.us и должны быть получены через API.
5. Каналы / Newsletters (ВЫСОКИЙ)
Создание Каналов WhatsApp, публикация сообщений через Chat ID @newsletter, управление подписчиками и администраторами. Для больших WhatsApp-аудиторий Канал безопаснее, чем цикл рассылки: нет риска бана, нет обязательных задержек между сообщениями.
6. Сообщества (СРЕДНИЙ)
Создание сообществ, привязка групп, отправка объявлений через выделенную группу «Анонсы». Объявления должны отправляться именно через группу «Анонсы», а не напрямую в подгруппы.
7. Паттерны интеграции (ВЫСОКИЙ)
Два production-ready рецепта:
- Паттерн бота: Настройка webhook → получение сообщения → фильтр
from_me: true→ ответ. Подходит для echo-ботов, ответчиков по ключевым словам и AI-ассистентов. - Паттерн рассылки: Цикл по получателям с обязательными задержками, требованием прогретого номера, правилами персонализации и проверкой квоты через
getLimits.
Сценарии использования: где skill помогает уже сегодня
Вот пять конкретных рабочих процессов, где Whapi Agent Skill выдаёт корректный код с первого раза.
1. Бот клиентской поддержки в WhatsApp
Вы просите Cursor построить бот поддержки. Без skill Cursor пишет polling-цикл и использует Chat ID формата @c.us. Со skill он генерирует обработчик webhook, фильтрует from_me и автоматически использует @s.whatsapp.net. Фильтруйте from_me: true в каждом обработчике ответа бота, иначе ваш WhatsApp-бот зациклится, отправляя сообщения сам себе.
@app.route("/webhook", methods=["POST"])
def webhook():
data = request.json
if "messages" not in data:
return {"status": "ok"}
for message in data["messages"]:
if message.get("from_me"):
continue # prevent infinite loop
if message.get("type") != "text":
continue
chat_id = message["chat_id"] # e.g., "[email protected]"
text = message["text"]["body"] # correct field name: body
reply(chat_id, f"Got it: {text}")2. Уведомление о лиде с веб-формы
Новый лид отправляет форму. Ваш агент шлёт сообщение в WhatsApp команде продаж. Skill гарантирует, что агент использует sendMessageText с полем body и корректным Chat ID @s.whatsapp.net, а не галлюцинированный универсальный endpoint отправки.
3. Система уведомлений в группу
Вы хотите публиковать апдейты в WhatsApp-группе. Skill обучает агента, что ID групп используют формат @g.us, что нужно вызвать getGroups, чтобы получить ID (никогда не конструируйте вручную), и что параметр to принимает полную строку Chat ID.
4. Рассылка через Канал WhatsApp
Вам нужно достучаться до сотен подписчиков. Skill подсвечивает подход через Канал до того, как агент предложит цикл рассылки: нет риска бана, нет обязательных задержек между сообщениями, подписчики подписываются сами. Для больших аудиторий это правильный выбор по умолчанию.
5. Контролируемая массовая рассылка
Когда требуется прямая рассылка по списку: максимум 10 сообщений за 15 минут, минимум 60–90 секунд между отправками, обязательно прогретый номер, персонализированный контент для каждого получателя. Отправка WhatsApp-сообщений без 60-секундных задержек и без персонализации запускает антиспам-детекцию и блокировку аккаунта. Сначала вызовите getLimits, чтобы проверить остаток квоты.
Установка: одна команда, все агенты
Установите Whapi WhatsApp Agent Skill одной командой:
npx skills add Whapi-Cloud/whapi-whatsapp-api-skillТребование: Node.js 18 или новее.
Чтобы нацелиться на конкретного агента или установить глобально:
# Install for Cursor only
npx skills add Whapi-Cloud/whapi-whatsapp-api-skill --agent cursor
# Install for Claude Code only
npx skills add Whapi-Cloud/whapi-whatsapp-api-skill --agent claude-code
# Install globally (available in all projects)
npx skills add Whapi-Cloud/whapi-whatsapp-api-skill --globalПосле установки skill автоматически загружается, когда ваш агент распознаёт задачу, связанную с WhatsApp. Если она не активируется сама:
- Cursor: Сошлитесь на
@.agents/skills/whapi/AGENTS.mdв чате или выполните/whapi - Claude Code: Выполните
/file .agents/skills/whapi/AGENTS.mdв начале сессии или выполните/whapi - GitHub Copilot: Сошлитесь на
#.agents/skills/whapi/AGENTS.mdв чате
Настройка MCP-сервера (Cursor)
Чтобы агент мог выполнять реальные вызовы WhatsApp API, добавьте MCP-сервер Whapi в %USERPROFILE%\.cursor\mcp.json:
{
"mcpServers": {
"whapi-mcp": {
"command": "npx",
"args": ["-y", "whapi-mcp@latest"],
"env": { "API_TOKEN": "YOUR_TOKEN" }
}
}
}Возьмите токен на panel.whapi.cloud/dashboard. После сохранения конфига перезапустите Cursor и вызовите checkHealth (без аргументов) — подключённый канал возвращает "status.text": "AUTH".
Полная инструкция по установке: support.whapi.cloud/help-desk/ai-tools/agent-skills
Что пока не покрыто — и что на подходе
Текущая версия сосредоточена на самых частых сценариях. Некоторые области пока не представлены в референс-файлах skill:
- Интерактивные сообщения (
sendMessageInteractive): Задокументированы, но помечены как нестабильные — доставка варьируется между версиями WhatsApp. Активно отслеживаются. - Статусы / Stories WhatsApp: Доступны в MCP (165 инструментов), но пока не задокументированы в категориях референсов skill.
- Commerce / Заказы / Товары: Каталог и флоу заказов WhatsApp доступны в API, но пока не в библиотеке паттернов skill.
- Продвинутая работа с медиа: Краевые случаи кодирования файлов, ограничений размера и стриминга аудио пока не покрыты.
- WhatsApp-звонки: Детекция входящих звонков через webhooks перечислена; паттерны управления звонками в планах.
Agent Skills кодифицируют годы проб и ошибок с API в один файл, чтобы AI-агенты сразу переходили к корректной реализации. Whapi Agent Skill — живой документ, который растёт с каждым задокументированным сценарием разработки. Контрибьюции приветствуются.
Как начать работу с Whapi.Cloud
Whapi Agent Skill бесплатна и с открытым исходным кодом. Чтобы использовать её с реальным WhatsApp API, нужен аккаунт Whapi.Cloud — доступен бесплатный sandbox без истечения срока, покрывающий 5 активных диалогов и 150 сообщений в сутки. Без одобрения Meta, без ограничений по шаблонам.
- Создайте бесплатный аккаунт на whapi.cloud
- Привяжите ваш номер WhatsApp через QR-код
- Скопируйте токен канала из дашборда
- Выполните:
npx skills add Whapi-Cloud/whapi-whatsapp-api-skill - Добавьте запись MCP-сервера в конфиг вашего агента
- Попросите агента: «Отправь сообщение в WhatsApp через WHAPI»
Агент загрузит skill, проверит подключение через checkHealth и проведёт вас через первую отправку с корректными именами полей, форматом Chat ID и заголовком авторизации. Ваша первая рабочая отправка в WhatsApp — от установки skill до подтверждения доставки — занимает меньше десяти минут.
GitHub: github.com/Whapi-Cloud/whapi-whatsapp-api-skill
Документация: support.whapi.cloud/help-desk/ai-tools/agent-skills
MCP-интеграция: whapi.cloud/mcp-whatsapp-api
