{"slug":"add-whatsapp-cloud","title":"add-whatsapp-cloud","summary":"Add WhatsApp Business Cloud API channel via Chat SDK. Official Meta API.","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-08-24T05:37:19.593933Z","repo":{"url":"https://github.com/nanocoai/nanoclaw","stars":30841,"forks":12823,"license":"MIT","updatedAt":"2026-09-23T17:25:39Z"},"bodyHtml":"
\n

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

\n

Add WhatsApp Cloud API Channel

\n

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

\n

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

\n

Apply

\n

1. Copy the adapter

\n

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

\n
src/channels/whatsapp-cloud.ts\nsrc/channels/whatsapp-cloud-registration.test.ts\n
\n

2. Register the adapter

\n

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

\n
import './whatsapp-cloud.js';\n
\n

3. Install the adapter package

\n

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

\n
@chat-adapter/whatsapp@4.29.0\n
\n

4. Build and validate

\n

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

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

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

\n

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

\n

Upgrading an existing install

\n

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

\n\n

Fresh installs need none of this.

\n

Credentials

\n

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

\n
    \n
  1. Go to Meta for Developers and create an app (type: Business).
    2. \n
  2. Add the WhatsApp product.
    3. \n
  3. Go to WhatsApp > API Setup:\n\n
    4. \n
  4. Go to WhatsApp > Configuration:\n\n
    5. \n
  5. Copy the App Secret from Settings > Basic.
    6. \n
\n

Store the credentials

\n

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

\n
Paste the System User access token — WhatsApp > API Setup, with `whatsapp_business_messaging` permission.\n
\n
Paste the Phone Number ID — WhatsApp > API Setup (not the phone number itself).\n
\n
Paste the App Secret — Settings > Basic.\n
\n
Paste the Verify Token — the random string you set under WhatsApp > Configuration.\n
\n
WHATSAPP_ACCESS_TOKEN={{access_token}}\nWHATSAPP_PHONE_NUMBER_ID={{phone_number_id}}\nWHATSAPP_APP_SECRET={{app_secret}}\nWHATSAPP_VERIFY_TOKEN={{verify_token}}\n
\n

Webhook server

\n

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

\n

Next Steps

\n

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

\n

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

\n

Channel Info

\n\n

Troubleshooting

\n

Meta's \"Verify and save\" fails on the webhook. Meta hits your URL with a challenge the moment you click, so the endpoint must already be publicly reachable at /webhook/whatsapp-cloud (shared webhook server, port 3000) and the service must be running with WHATSAPP_VERIFY_TOKEN set to exactly the string you typed under WhatsApp > Configuration. Start or restart the service first, then click verify.

\n

Everything works for a day, then all calls 401. You stored the temporary token from WhatsApp > API Setup, which expires in ~24 hours. Create a System User under Business Settings → Users, grant it the app with whatsapp_business_messaging, generate a permanent token, and replace WHATSAPP_ACCESS_TOKEN.

\n

Outbound messages are accepted but never delivered. Two Meta-side gates: while the app is in development mode you can only message numbers added to the recipient allowlist in API Setup; and free-form replies are only allowed within 24 hours of the user's last inbound message — outside that window you need an approved template. Also confirm WHATSAPP_PHONE_NUMBER_ID is the Phone Number ID, not the phone number itself.

\n

Adapter installed but nothing flows. Run pnpm exec vitest run src/channels/whatsapp-cloud-registration.test.ts — red means the barrel import or the @chat-adapter/whatsapp install drifted, so re-run the Apply steps. If green, restart the service (see Next Steps) so the adapter and .env values are live.

\n","files":[{"path":"apply-fixtures.json","sizeBytes":395,"isText":true},{"path":"REMOVE.md","sizeBytes":833,"isText":true},{"path":"SKILL.md","sizeBytes":7644,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"human-reviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"human-reviewed","screen":{"ran":true,"outcome":"flagged-cleared-by-moderator","suspicious":2,"notes":1,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-08-24T05:39:18.385534Z","sha256":"F3F4E15F34BA270F61627FC874AD5993124C0EC30C05518EEC0A7D6CF2066FE2","sizeBytes":4265},"review":null,"source":{"repositoryUrl":"https://github.com/nanocoai/nanoclaw","path":".claude/skills/add-whatsapp-cloud","license":"MIT","commit":"143db6c907c652773a536c7c9e96269fdad0a4a4","subtreeSha":"98B865B01B498B09865F29FA727F20E731A7D7B56300D9A32400CCF263B5DB61","lastSyncedAt":"2026-09-24T06:48:46.168681Z"},"reviewedAt":"2026-08-24T17:49:14.937758Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/nanocoai/nanoclaw/tree/main/.claude/skills/add-whatsapp-cloud"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install nanocoai-nanoclaw@llmmart"},{"target":"git","command":"git clone https://github.com/nanocoai/nanoclaw.git"}]}