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

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://support.whapi.cloud/help-desk/ai-tools/agent-skills.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.