Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Agent Skills

Agent Skills to help developers using AI agents with Whapi.Cloud API

The Whapi Agent Skill is a structured set of instructions for AI agents that prevents the most common mistakes whenAgent Skills

The Whapi Agent Skill fixes that. It's a structured instruction set that your agent loads automatically when it detects a WhatsApp task, giving it the real API rules instead of its own recollection. It works with Cursor, Claude Code, Codex, GitHub Copilot, and 40+ other agents.

You don't need to be a developer to use it — that's largely the point. If you're vibe coding your way to a WhatsApp integration, the skill is what keeps the result working rather than merely plausible.

The Whapi Agent Skill fixes that. It's a structured instruction set that your agent loads automatically when it detects a WhatsApp task, giving it the real API rules instead of its own recollection. It works with Cursor, Claude Code, Codex, GitHub Copilot, and 40+ other agents.

You don't need to be a developer to use it — that's largely the point. If you're vibe coding your way to a WhatsApp integration, the skill is what keeps the result working rather than merely plausible.

Installation

Requirements: Node.js 18+

Install for all detected agents at once:

npx skills add Whapi-Cloud/whapi-whatsapp-api-skill

To target a specific agent:

npx skills add Whapi-Cloud/whapi-whatsapp-api-skill --agent cursor
npx skills add Whapi-Cloud/whapi-whatsapp-api-skill --agent claude-code

Add --global to make the skill available across all projects.

Getting Started

Once installed, the skill is available to your AI agent automatically. No configuration needed — the agent loads it when you start working on a WhatsApp integration.

Start a conversation like this:

  • "Help me send a WhatsApp message using Whapi"

  • "I want to build a WhatsApp bot with Whapi, where do I start?"

  • "Set up Whapi MCP in Cursor for me"

The agent will load the skill, check prerequisites (MCP connection, token), and guide you step by step.

Manual Skill Activation

After installation, AI agents load the Whapi skill automatically when they detect a WhatsApp-related task. If the skill does not activate on its own, use the commands below to load it manually.

Reference the skill file directly in the chat:

Or attach it via the @Files picker and select AGENTS.md from the skill folder.

Or activate the skill using the /whapi command.

Include the navigation guide at the start of a session:

Claude Code also reads CLAUDE.md from the project root automatically on startup — if the skill is installed in the project, this file is already there and points to the guide.

Or activate the skill using the /whapi command.

Reference the file in the chat using #:

If the skill was installed globally, it may also be available in .github/copilot-instructions.md depending on how npx skills add configured it.

These tools have no file system access, so there is no automatic activation. Use the ready-made prompts from the AI Prompts article — each prompt is self-contained and can be pasted directly into the chat.

What the Skill Covers

The skill is organized into 7 reference categories, loaded by the agent on demand:

  • Core concepts — Chat ID formats (@s.whatsapp.net, @g.us, @newsletter), MCP setup, Bearer token authentication

  • Sending messages — Decision tree for choosing the right tool per content type (text, image, video, voice, audio, document, poll, interactive, reaction)

  • Receiving messages — Webhook setup with correct nested structure, incoming payload format, why polling is an anti-pattern

  • Groups — Create, manage participants, invite links, admin roles

  • Channels (Newsletters) — Create, post via @newsletter ID, manage subscribers and admins

  • Communities — Create, link groups, send announcements via the dedicated Announcements group (not to sub-groups directly)

  • Integration patterns — Full bot recipe (webhook → filter from_me → reply) and safe broadcast loop with rate limits

Each reference file includes correct and incorrect examples, and an explicit anti-hallucination checklist of parameters and tools that do not exist.

MCP Setup

The skill and the MCP server complement each other: whapi-mcp gives your agent access to the API, the skill tells it how to use that access correctly. Install both.

Config file locations, the whapi-mcp-optimal slim build, connection verification with checkHealth, and the channel status table are all covered in MCP (Model Context Protocol).

API_TOKEN takes your channel token, not a Partner Token — copy it from the channel page at panel.whapi.cloud. It only appears after a WhatsApp number is paired with the channel; if you haven't paired one yet, see the pairing guide.

Frequently asked

Do I need to know how to code? No. The skill exists precisely for vibe coding — you describe the goal in plain language, the agent writes the integration, and the skill keeps it from inventing parameters and endpoints along the way.

Do I need the MCP server too? They solve different problems. The skill alone already stops the agent from writing wrong code. Add the MCP server if you want the agent to actually call the API and see real responses. Most people install both.

Does it work with ChatGPT or Claude in the browser? Not automatically — those have no file system access. Use the ready-made prompts from AI Prompts instead.

Is it free? Yes. The skill is an open repository — Whapi-Cloud/whapi-whatsapp-api-skill.

How do I update it? Re-run npx skills add Whapi-Cloud/whapi-whatsapp-api-skill — it pulls the current version.

Installation

Install for all detected agents at once:

To target a specific agent:

Add --global to make the skill available across all projects.

Requirements: Node.js 18+

Getting Started

Once installed, the skill is available to your AI agent automatically. No configuration needed — the agent loads it when you start working on a WhatsApp integration.

Start a conversation like this:

  • "Help me send a WhatsApp message using WHAPI"

  • "I want to build a WhatsApp bot with WHAPI, where do I start?"

  • "Set up WHAPI MCP in Cursor for me"

The agent will load the skill, check prerequisites (MCP connection, token), and guide you step by step.

Manual Skill Activation

After installation, AI agents load the WHAPI skill automatically when they detect a WhatsApp-related task. If the skill does not activate on its own, use the commands below to load it manually.

Reference the skill file directly in the chat:

Or attach it via the @Files picker and select AGENTS.md from the skill folder.

Or activate the skill using the /whapi command.

Include the navigation guide at the start of a session:

Claude Code also reads CLAUDE.md from the project root automatically on startup — if the skill is installed in the project, this file is already there and points to the guide.

Or activate the skill using the /whapi command.

Reference the file in the chat using #:

If the skill was installed globally, it may also be available in .github/copilot-instructions.md depending on how npx skills add configured it.

These tools have no file system access, so there is no automatic activation. Use the ready-made prompts from the AI Prompts article — each prompt is self-contained and can be pasted directly into the chat.

What the Skill Covers

The skill is organized into 7 reference categories, loaded by the agent on demand:

  • Core concepts — Chat ID formats (@s.whatsapp.net, @g.us, @newsletter), MCP setup, Bearer token authentication

  • Sending messages — Decision tree for choosing the right tool per content type (text, image, video, voice, audio, document, poll, interactive, reaction)

  • Receiving messages — Webhook setup with correct nested structure, incoming payload format, why polling is an anti-pattern

  • Groups — Create, manage participants, invite links, admin roles

  • Channels (Newsletters) — Create, post via @newsletter ID, manage subscribers and admins

  • Communities — Create, link groups, send announcements via the dedicated Announcements group (not to sub-groups directly)

  • Integration patterns — Full bot recipe (webhook → filter from_me → reply) and safe broadcast loop with rate limits

Each reference file includes correct and incorrect examples, and an explicit anti-hallucination checklist of parameters and tools that do not exist.

MCP Setup

The skill works alongside whapi-mcp — the official WHAPI MCP server with 165 tools covering messaging, groups, channels, communities, and more.

Add the following to your agent's MCP config file:

  • Cursor: %USERPROFILE%\.cursor\mcp.json

  • Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json

Getting your token: Go to panel.whapi.cloud/dashboard, open your channel, and copy the token from the settings page.

The token only works after a WhatsApp number is paired with the channel. If you haven't done this yet, follow the pairing guide.

Verifying the Connection

After saving the config, restart your agent and call checkHealth (no arguments). A working channel returns "status.text": "AUTH".

status.text
Meaning
Action

AUTH

Connected and operational

Ready to use

QR

Waiting for QR scan

Open the channel dashboard and scan

INIT

Server initializing

Wait 40–50 s; contact support if it persists

LAUNCH

Connecting to WhatsApp

Wait a few seconds

STOP

Channel deactivated

Check subscription at the dashboard

SYNC_ERROR

Sync failure

Log out the channel and reconnect

If checkHealth returns 404 ("Channel not found"), the token is invalid or the channel doesn't exist — double-check the token and that a number is paired.

PreviousMCP (Model Context Protocol)
NextAI Prompts

Last updated