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 when building WhatsApp integrations with Whapi.Cloud — wrong Chat ID format, hallucinated parameters, polling instead of webhooks, and incorrect tool names. It works with Cursor, Claude Code, Codex, GitHub Copilot, and 40+ other agents.

---

Installation

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.

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.

Cursor

Reference the skill file directly in the chat:

@.agents/skills/whapi/AGENTS.md

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

Or activate the skill using the /whapi command.

Claude Code

GitHub Copilot

ChatGPT / Claude.ai / Gemini (browser)

---

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

{
  "mcpServers": {
    "whapi-mcp": {
      "command": "npx",
      "args": ["-y", "whapi-mcp@latest"],
      "env": { "API_TOKEN": "YOUR_TOKEN" }
    }
  }
}

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.

---