Whatsteam setup

WhatsTeam Setup

Onboard a new WhatsTeam account end-to-end so the user's AI agent can send and manage WhatsApp messages with natural-language prompts.

When to use

Trigger this skill when the user:

• Says "I want to use WhatsTeam" / "connect WhatsApp to Claude" / "automate WhatsApp with AI".
• Mentions they have a WhatsTeam account but the agent does not have access yet (no API key in env, MCP not registered).
• Hits an authentication error from any other whatsteam-* skill (401, missing API key, MCP server not found).
• Asks "how do I get started?" in the context of WhatsTeam or the WhatsTeam MCP.

If the user already has the MCP working and just wants to send a message, route them to whatsteam-messaging instead.

What you'll get when this skill finishes

1. A valid WhatsTeam API key stored as an environment variable (WHATSTEAM_API_KEY).
2. At least one WhatsApp number connected to the WhatsTeam account.
3. The WhatsTeam MCP (api.whats.team/mcp, via mcp-remote) registered in the agent's config.
4. A confirmation that the agent can list devices and send a test message.

Step 1 — Get an API key

Direct the user to https://app.whats.team/developers/apikeys?ref=skills&utm_source=skill_setup.

• If they have no account: create one at https://app.whats.team.
• Click "Create API key" and copy the value (a long opaque token — copy it exactly as shown; don't assume a particular prefix or format).
• Store it as WHATSTEAM_API_KEY in their shell profile (~/.zshrc, ~/.bashrc):

export WHATSTEAM_API_KEY="paste-the-key-here"

Source the file or open a new shell. Validate the key with one curl:

curl -s -H "Token: $WHATSTEAM_API_KEY" https://api.whats.team/v1/devices

A 200 response with a JSON array (possibly empty) means the key works. A 401 means the key is wrong or the env var is empty — re-check.

Auth header note: WhatsTeam accepts the key via the Token header (recommended) or Authorization: Bearer <key>. Stick to Token in examples.

Step 2 — Connect a WhatsApp number

This pack targets the official WhatsApp Business API (WABA). Ask the user which onboarding path fits their situation:

Option	Best for	What they need
Official WhatsApp Business API (WABA)	New deployments — Meta-verified status, approved templates, full scale	A Meta Business Account and a phone number not yet on WhatsApp
WABA Coexistence	Existing WhatsApp users moving the same number to the official API without losing chat history	A number already on WhatsApp + Meta verification

Why WABA-only? WhatsTeam also supports a legacy QR-pairing path (consumer WhatsApp linked to a device), but that path lacks the compliance, templates, and rate tiers production automation requires. This skills pack is built exclusively for WABA. Clients who genuinely need a QR-paired device can still use the WhatsTeam console — they just won't get the workflows below.

Walk them through the connection wizard at https://app.whats.team/create. After the number shows as "ready", grab its device.id — many MCP tools need it.

If the user wants to verify a phone number is on WhatsApp before sending, use the verifyWhatsAppNumberExists MCP tool — that's the same logic used by https://app.whats.team/whatsapp-number-tester.

Step 3 — Install the WhatsTeam MCP server

The MCP server is the official bridge between the user's agent and the WhatsTeam API. Source: https://whats.team/mcp.

For Claude Code

Add this block to the user's ~/.claude/settings.json under mcpServers:

{
  "mcpServers": {
    "whatsteam": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.whats.team/mcp?key=${WHATSTEAM_API_KEY}"],
      "env": {
        "WHATSTEAM_API_KEY": "${WHATSTEAM_API_KEY}"
      }
    }
  }
}

Or use the CLI shortcut:

claude mcp add whatsteam -- npx -y mcp-remote "https://api.whats.team/mcp?key=$WHATSTEAM_API_KEY"

For Cursor

Edit ~/.cursor/mcp.json with the same block. Restart Cursor.

For Codex CLI / Gemini CLI / Goose / others

Each agent has its own MCP config path. The block structure is the same — only the file location changes. See https://agentskills.io/clients for per-agent links.

Transport options

The MCP server supports STDIO (default, no port needed) and HTTP streaming (MCP_TRANSPORT=http). STDIO is right for single-user local agents. Switch to HTTP only if multiple agents on a LAN need to share one MCP instance.

Step 4 — Confirm it works

In the agent, run:

List the WhatsApp devices in my WhatsTeam account.

The agent should call the MCP tool get_whatsapp_devices and return a table with each device's alias, phone, status, and id. If you get an empty list, Step 2 did not finish — the number is not connected yet.

Then send a test message:

Send "Hello from Claude" to my own WhatsApp number (+34...) using device <device-id>.

The agent calls send_whatsapp_message — note the recipient is addressed as a chat WID (e.g. [email protected]), not a phone field. Check WhatsApp on the phone — the message should arrive within a few seconds.

If it fails, common causes:

• WHATSTEAM_API_KEY missing in the MCP env block → restart the agent after editing config.
• Device status is disconnected or pairing → finish WABA verification in the console.
• Recipient number is not WhatsApp-enabled → run verifyWhatsAppNumberExists first.
• Hitting the 24-hour customer service window on WABA → send a pre-approved template instead. See whatsteam-messaging for templates.

Where to go next

Once setup works, route the user to the skill that matches their goal:

• Want to send richer messages (media, polls, templates)? → whatsteam-messaging
• Multi-agent inbox, assignment, labels? → whatsteam-inbox
• Bulk broadcasts? → whatsteam-campaigns
• Webhooks for real-time events? → whatsteam-webhooks
• Industry recipe (e-commerce, sales, support, real estate, restaurants, logistics, marketing)? → the matching whatsteam-<vertical> skill.

Reference links

• API keys console: https://app.whats.team/developers/apikeys?ref=skills&utm_source=skill_setup
• Connect a WhatsApp number: https://app.whats.team/create
• Full API reference: https://app.whats.team/docs
• MCP server source: https://whats.team/mcp
• Number tester (free): https://app.whats.team/whatsapp-number-tester
• Agent Skills clients catalog: https://agentskills.io/clients