{"id":"add-whatsapp-cloud","name":"add-whatsapp-cloud","summary":"WhatsApp Business Cloud APIチャネルはChat SDK経由で追加できます。","body":"# Add WhatsApp Cloud API Channel\n\nConnect 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\nThe 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\n## Apply\n\n### 1. Copy the adapter\n\nFetch the `channels` branch and copy the WhatsApp Cloud adapter into\n`src/channels/` (overwrite — the branch is canonical):\n\n```nc:copy from-branch:channels\nsrc/channels/whatsapp-cloud.ts\nsrc/channels/whatsapp-cloud-registration.test.ts\n```\n\n### 2. Register the adapter\n\nAppend 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\n```nc:append to:src/channels/index.ts\nimport './whatsapp-cloud.js';\n```\n\n### 3. Install the adapter package\n\nPinned to an exact version — the supply-chain policy rejects ranges and `latest`:\n\n```nc:dep\n@chat-adapter/whatsapp@4.29.0\n```\n\n### 4. Build and validate\n\nBuild 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\n```nc:run effect:build\npnpm run build\n```\n```nc:run effect:test\npnpm exec vitest run src/channels/whatsapp-cloud-registration.test.ts\n```\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\nEnd-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\n## Upgrading an existing install\n\nOlder 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\n`whatsapp-cloud` instance (channelType stays `whatsapp`). Two consequences for an\ninstall that ran the previous version:\n\n- **Webhook route moves** from `/webhook/whatsapp` to `/webhook/whatsapp-cloud`.\n  Update the callback URL in your Meta App dashboard (WhatsApp > Configuration)\n  accordingly.\n- **Chat SDK state namespace moves.** Subscriptions in the `chat_sdk_*` tables\n  re-key under the new instance, so previously-subscribed threads may need to\n  re-engage the bot.\n\nFresh installs need none of this.\n\n## Credentials\n\nMeta 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\n1. Go to [Meta for Developers](https://developers.facebook.com/apps/) and create an app (type: Business).\n2. Add the **WhatsApp** product.\n3. Go to **WhatsApp** > **API Setup**:\n   - Note the **Phone Number ID** (not the phone number itself).\n   - Generate a **permanent System User access token** with `whatsapp_business_messaging` permission.\n4. Go to **WhatsApp** > **Configuration**:\n   - Set webhook URL: `https://your-domain/webhook/whatsapp-cloud`.\n   - Set a **Verify Token** (any random string you choose).\n   - Subscribe to webhook fields: `messages`.\n5. Copy the **App Secret** from **Settings** > **Basic**.\n\n### Store the credentials\n\nCapture 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\n```nc:prompt access_token secret\nPaste the System User access token — WhatsApp > API Setup, with `whatsapp_business_messaging` permission.\n```\n```nc:prompt phone_number_id\nPaste the Phone Number ID — WhatsApp > API Setup (not the phone number itself).\n```\n```nc:prompt app_secret secret\nPaste the App Secret — Settings > Basic.\n```\n```nc:prompt verify_token secret\nPaste the Verify Token — the random string you set under WhatsApp > Configuration.\n```\n```nc:env-set\nWHATSAPP_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\nThe 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\n## Next Steps\n\nIf you're in the middle of `/setup`, return to the setup flow now.\n\nOtherwise, run `/manage-channels` to wire this channel to an agent group.\n\n## Channel Info\n\n- **type**: `whatsapp-cloud`\n- **terminology**: WhatsApp Cloud API supports 1:1 conversations only (no group chats). Each conversation is with a phone number.\n- **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.\n- **supports-threads**: no\n- **typical-use**: Interactive 1:1 chat -- direct messages only\n- **default-isolation**: Same agent group if you're the only person messaging the bot. Each additional person who messages gets their own conversation automatically, but they share the agent's workspace and memory -- use a separate agent group if you need information isolation between different contacts.\n\n## Troubleshooting\n\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\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\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\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.","author":"@nanocoai","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/nanocoai/nanoclaw/tree/main/.claude/skills/add-whatsapp-cloud","license":"MIT","category":"writing","lang":"en","tokens":1754,"stars":0,"calls30d":1,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"apply-fixtures.json","size":395,"sha256":"ea49e60ddc10837d535d7ce6b48e16c85797a818b5f9f1b0daad4d300ca55dc7"},{"path":"REMOVE.md","size":833,"sha256":"deebc3311c059fc2c22d79d568f979923b48123c8b7f2b7f1e6e19639d3fd422"}],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":["developers.facebook.com"]}}