How to use the WhatsApp Cloud Channel Setup agent skill

What an agent skill is and what this one does

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent reads and follows when a matching request comes in. This skill is for developers running a self-hosted NanoClaw instance who want a WhatsApp bot on the official Meta API.

Once applied, the agent copies a channel adapter file (whatsapp-cloud.ts) and its registration test into src/channels/, adds one import line to src/channels/index.ts, installs the pinned package @chat-adapter/whatsapp@4.41.1, and runs the build and test commands. It then asks you to paste four Meta credentials and saves them to a .env file.

• Copies the adapter into src/channels/
• Adds a self-registration import to the channel barrel
• Installs @chat-adapter/whatsapp at an exact pinned version
• Runs pnpm run build and a registration test
• Writes WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID, WHATSAPP_APP_SECRET and WHATSAPP_VERIFY_TOKEN to .env

Install the skill (ZIP download or Claude app upload)

Download the ZIP for this skill from this page. For a personal setup, unzip it into ~/.claude/skills/. To scope it to one project, unzip it into that project's .claude/skills/ folder.

If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the ZIP there.

• Personal: ~/.claude/skills/
• Per project: .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills, then upload

Prerequisites you need before starting

The skill assumes a working NanoClaw installation that uses pnpm and builds successfully. You also need a Meta for Developers account with a WhatsApp Business app, and a publicly reachable HTTPS URL for the webhook. The skill does not create any of these for you.

• NanoClaw installed with pnpm and a working build
• A Meta for Developers account with a WhatsApp Business app
• Phone Number ID, permanent System User access token, App Secret and a Verify Token
• A public HTTPS URL, for example via ngrok, Cloudflare Tunnel or a reverse proxy

Trigger the skill with a natural request

Once the skill is installed, ask your agent in plain language to add WhatsApp Cloud support to your NanoClaw project. The agent reads the skill, follows its Apply steps, and pauses to ask for credentials. The skill's own name, add-whatsapp-cloud, is a useful phrase to include if your agent matches skills by name.

• "Add the WhatsApp Cloud API channel to this NanoClaw project."
• "Use the add-whatsapp-cloud skill to connect WhatsApp to NanoClaw."
• "Set up the WhatsApp Business Cloud API channel and walk me through the Meta credentials."

Set up the Meta side and the webhook

Some steps happen in the Meta dashboard and cannot be automated. In the Meta app, add the WhatsApp product, note the Phone Number ID under WhatsApp > API Setup, and generate a permanent System User token with the whatsapp_business_messaging permission. Under WhatsApp > Configuration, set the webhook URL to your public domain followed by /webhook/whatsapp-cloud, choose a Verify Token, and subscribe to the messages field. Copy the App Secret from Settings > Basic.

Start the service before you click verify in Meta, because Meta sends a challenge as soon as you do. Expose port 3000 publicly using ngrok (ngrok http 3000), a Cloudflare Tunnel or a reverse proxy. If the proxy runs on another machine or in Docker on Linux, set WEBHOOK_HOST=0.0.0.0 in .env and restart.

• Phone Number ID: WhatsApp > API Setup (not the phone number itself)
• Webhook URL: https://your-domain/webhook/whatsapp-cloud
• Subscribe to the messages webhook field
• Restart the service so changes take effect

Remove the channel later

The REMOVE.md file in the skill describes how to undo the setup. It deletes the import line from src/channels/index.ts, removes the copied adapter and its test, deletes the four WHATSAPP_ variables from .env, uninstalls the package, then rebuilds and restarts the service. Every step is safe to re-run.