# Agent Skills

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:

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

To target a specific agent:

```bash
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.

{% tabs %}
{% tab title="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.
{% endtab %}

{% tab title="Claude Code" %}
Include the navigation guide at the start of a session:

```
/file .agents/skills/whapi/AGENTS.md
```

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.
{% endtab %}

{% tab title="GitHub Copilot" %}
Reference the file in the chat using `#`:

```
#.agents/skills/whapi/AGENTS.md
```

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

{% tab title="ChatGPT / Claude.ai / Gemini (browser)" %}
These tools have no file system access, so there is no automatic activation. Use the ready-made prompts from the [AI Prompts](https://support.whapi.cloud/help-desk/ai-tools/ai-prompts) article — each prompt is self-contained and can be pasted directly into the chat.
{% endtab %}
{% endtabs %}

***

### 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`

```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](https://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](https://support.whapi.cloud/help-desk/getting-started/getting-started#pair-your-number).

***

### 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.

***