/add-whatsapp-cloud

name: add-whatsapp-cloud
description: Add WhatsApp Business Cloud API channel via Chat SDK. Official Meta API.

Add WhatsApp Cloud API Channel

Connect NanoClaw to WhatsApp via the official Meta WhatsApp Business Cloud API. NanoClaw doesn't ship channels in trunk — this skill copies the WhatsApp Cloud adapter in from the `channels` branch.

The mechanical steps under **Apply** carry `nc:` directive fences: an agent reads the prose and applies them, and a parser can apply them deterministically from the same document. Every directive is idempotent, so the whole skill is safe to re-run; anything a parser can't apply falls back to the prose beside it.

Apply

1. Copy the adapter

Fetch the `channels` branch and copy the WhatsApp Cloud adapter into `src/channels/` (overwrite — the branch is canonical):

src/channels/whatsapp-cloud.ts
src/channels/whatsapp-cloud-registration.test.ts

2. Register the adapter

Append the self-registration import to the channel barrel (skipped if the line is already present). This one line is the skill's only reach-in into core:

import './whatsapp-cloud.js';

3. Install the adapter package

Pinned to an exact version — the supply-chain policy rejects ranges and `latest`:

@chat-adapter/whatsapp@4.41.1

4. Build and validate

Build guards the typed `createChatSdkBridge(...)` core call and proves the dependency is installed — the import throws at evaluation if `@chat-adapter/whatsapp` is missing or the barrel drifts:

pnpm run build

pnpm exec vitest run src/channels/whatsapp-cloud-registration.test.ts

`whatsapp-cloud-registration.test.ts` imports the real channel barrel and asserts the registry contains `whatsapp-cloud` — it goes red if the import line is deleted or drifts, if the barrel fails to evaluate, or if `@chat-adapter/whatsapp` isn't installed (the import throws), so it also covers the dependency from step 3.

End-to-end message delivery against a real WhatsApp Business number is verified manually once the service is running — see Next Steps and the webhook setup below.

Upgrading an existing install

Older copies of the adapter registered this bridge under the bare `whatsapp` key, which collided with the native Baileys adapter. It now registers under a distinct `whatsapp-cloud` instance (channelType stays `whatsapp`). Two consequences for an install that ran the previous version:

• **Webhook route moves** from `/webhook/whatsapp` to `/webhook/whatsapp-cloud`.

Update the callback URL in your Meta App dashboard (WhatsApp > Configuration) accordingly.

• **Chat SDK state namespace moves.** Subscriptions in the `chat_sdk_*` tables

re-key under the new instance, so previously-subscribed threads may need to re-engage the bot.

Fresh installs need none of this.

Credentials

Meta app setup is human and interactive — these steps are prose, not directives (no parser can click through the Meta dashboard). A recipe rebuild produces a compiling, registered adapter that cannot receive a message until they're done.

1. Go to [Meta for Developers](https://developers.facebook.com/apps/) and create an app (type: Business). 2. Add the **WhatsApp** product. 3. Go to **WhatsApp** > **API Setup**:

• Note the **Phone Number ID** (not the phone number itself).
• Generate a **permanent System User access token** with `whatsapp_business_messaging` permission.

4. Go to **WhatsApp** > **Configuration**:

• Set webhook URL: `https://your-domain/webhook/whatsapp-cloud`.
• Set a **Verify Token** (any random string you choose).
• Subscribe to webhook fields: `messages`.

5. Copy the **App Secret** from **Settings** > **Basic**.

Store the credentials

Capture the four values, then write them. `prompt` only *asks* and binds the answer to a name; a separate directive consumes it — so the same prompts could feed `ncl` or the OneCLI vault instead of `.env` by swapping only the consumer. Here they go to `.env` (set-if-absent — a value you've already filled in is never overwritten):

Paste the System User access token — WhatsApp > API Setup, with `whatsapp_business_messaging` permission.

Paste the Phone Number ID — WhatsApp > API Setup (not the phone number itself).

Paste the App Secret — Settings > Basic.

Paste the Verify Token — the random string you set under WhatsApp > Configuration.

WHATSAPP_ACCESS_TOKEN={{access_token}}
WHATSAPP_PHONE_NUMBER_ID={{phone_number_id}}
WHATSAPP_APP_SECRET={{app_secret}}
WHATSAPP_VERIFY_TOKEN={{verify_token}}

Webhook server

The Chat SDK bridge automatically starts a shared webhook server on port 3000 (`WEBHOOK_PORT` to change it), handling `/webhook/whatsapp-cloud`. This port must be publicly reachable for Meta to deliver events. Running locally, expose it with ngrok (`ngrok http 3000`), a Cloudflare Tunnel, or a reverse proxy on a VPS — the resulting public URL is the base for the webhook URL set under WhatsApp > Configuration above. Tell the user:

NanoClaw's webhook server listens on 127.0.0.1 only, so a tunnel or proxy on this machine works as is. If yours runs on another machine or in Docker on Linux, add `WEBHOOK_HOST=0.0.0.0` to `.env`; it takes effect at the next restart.

Next Steps

If you're in the middle of `/setup`, return to the setup flow now.

Otherwise, run `/manage-channels` to wire this channel to an agent group.

Channel Info

• **type**: `whatsapp-cloud`
• **terminology**: WhatsApp Cloud API supports 1:1 conversations only (no group chats). Each conversation is with a phone number.
• **how-to-find-id**: The platform ID is the Phone Number ID from the Meta Business dashboard (not the phone number itself). Find it under WhatsApp > API Setup.
• **sup