> For the complete documentation index, see [llms.txt](https://support.whapi.cloud/help-desk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.whapi.cloud/help-desk/ai-tools/agent-skills.md).

# Agent Skills

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

If you build your WhatsApp integration by prompting an AI agent — Cursor, Claude Code, GitHub Copilot, Codex — the agent will happily write code that looks right and doesn't work. It invents parameters that don't exist, formats Chat IDs wrong, polls for messages instead of using webhooks, and calls tools by names it made up.

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:

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

***

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

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

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

{% hint style="info" %}
`API_TOKEN` takes your **channel token**, not a Partner Token — copy it from the channel page at [panel.whapi.cloud](https://panel.whapi.cloud/dashboard). It only appears after a WhatsApp number is paired with the channel; if you haven't paired one yet, see the [pairing guide](https://support.whapi.cloud/help-desk/getting-started/getting-started#pair-your-number).
{% endhint %}

***

#### 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](/help-desk/ai-tools/ai-prompts.md) instead.

**Is it free?** Yes. The skill is an open repository — [Whapi-Cloud/whapi-whatsapp-api-skill](https://github.com/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:

```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](/help-desk/ai-tools/ai-prompts.md) 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.

***