Integrate Whatsapp

1---
2name: integrate-whatsapp
3description: "Connect WhatsApp to your product with Kapso: onboard customers with setup links, detect connections, receive events via webhooks, and send messages/templates/media. Also manage WhatsApp Flows (create/update/publish, data endpoints, encryption). Use when integrating WhatsApp end-to-end."
4---
5 
6# Integrate WhatsApp
7 
8## Setup
9 
10Env vars:
11- `KAPSO_API_BASE_URL` (host only, no `/platform/v1`)
12- `KAPSO_API_KEY`
13- `META_GRAPH_VERSION` (optional, default `v24.0`)
14 
15Auth header (direct API calls):
16```
17X-API-Key: <api_key>
18```
19 
20Install deps (once):
21```bash
22npm i
23```
24 
25## Connect WhatsApp (setup links)
26 
27Typical onboarding flow:
28 
291. Create customer: `POST /platform/v1/customers`
302. Generate setup link: `POST /platform/v1/customers/:id/setup_links`
313. Customer completes embedded signup
324. Use `phone_number_id` to send messages and configure webhooks
33 
34Detect connection:
35- Project webhook `whatsapp.phone_number.created` (recommended)
36- Success redirect URL query params (use for frontend UX)
37 
38Provision phone numbers (setup link config):
39```json
40{
41  "setup_link": {
42    "provision_phone_number": true,
43    "phone_number_country_isos": ["US"]
44  }
45}
46```
47 
48Notes:
49- Platform API base: `/platform/v1`
50- Meta proxy base: `/meta/whatsapp/v24.0` (messaging, templates, media)
51- Use `phone_number_id` as the primary WhatsApp identifier
52 
53## Receive events (webhooks)
54 
55Use webhooks to receive:
56- Project events (connection lifecycle, workflow events)
57- Phone-number events (messages, conversations, delivery status)
58 
59Scope rules:
60- **Project webhooks**: only project-level events (connection lifecycle, workflow events)
61- **Phone-number webhooks**: only WhatsApp message + conversation events for that `phone_number_id`
62- WhatsApp message/conversation events (`whatsapp.message.*`, `whatsapp.conversation.*`) are **phone-number only**
63 
64Create a webhook:
65- Project-level: `node scripts/create.js --scope project --url <https://...> --events <csv>`
66- Phone-number: `node scripts/create.js --phone-number-id <id> --url <https://...> --events <csv>`
67 
68Common flags for create/update:
69- `--url <https://...>` - webhook destination
70- `--events <csv|json-array>` - event types (Kapso webhooks)
71- `--kind <kapso|meta>` - Kapso (event-based) vs raw Meta forwarding
72- `--payload-version <v1|v2>` - payload format (`v2` recommended)
73- `--buffer-enabled <true|false>` - enable buffering for `whatsapp.message.received`
74- `--buffer-window-seconds <n>` - 1-60 seconds
75- `--max-buffer-size <n>` - 1-100
76- `--active <true|false>` - enable/disable
77 
78Test delivery:
79```bash
80node scripts/test.js --webhook-id <id>
81```
82 
83Always verify signatures. See:
84- `references/webhooks-overview.md`
85- `references/webhooks-reference.md`
86 
87## Send and read messages
88 
89### Discover IDs first
90 
91Two Meta IDs are needed for different operations:
92 
93| ID | Used for | How to discover |
94|----|----------|-----------------|
95| `business_account_id` (WABA) | Template CRUD | `node scripts/list-platform-phone-numbers.mjs` |
96| `phone_number_id` | Sending messages, media upload | `node scripts/list-platform-phone-numbers.mjs` |
97 
98### SDK setup
99 
100Install:
101```bash
102npm install @kapso/whatsapp-cloud-api
103```
104 
105Create client:
106```ts
107import { WhatsAppClient } from "@kapso/whatsapp-cloud-api";
108 
109const client = new WhatsAppClient({
110  baseUrl: "https://api.kapso.ai/meta/whatsapp",
111  kapsoApiKey: process.env.KAPSO_API_KEY!
112});
113```
114 
115### Send a text message
116 
117Via SDK:
118```ts
119await client.messages.sendText({
120  phoneNumberId: "<PHONE_NUMBER_ID>",
121  to: "+15551234567",
122  body: "Hello from Kapso"
123});
124```
125 
126### Send a template message
127 
1281. Discover IDs: `node scripts/list-platform-phone-numbers.mjs`
1292. Draft template payload from `assets/template-utility-order-status-update.json`
1303. Create: `node scripts/create-template.mjs --business-account-id <WABA_ID> --file <payload.json>`
1314. Check status: `node scripts/template-status.mjs --business-account-id <WABA_ID> --name <name>`
1325. Send: `node scripts/send-template.mjs --phone-number-id <ID> --file <send-payload.json>`
133 
134### Send an interactive message
135 
136Interactive messages require an active 24-hour session window. For outbound notifications outside the window, use templates.
137 
1381. Discover `phone_number_id`
1392. Pick payload from `assets/send-interactive-*.json`
1403. Send: `node scripts/send-interactive.mjs --phone-number-id <ID> --file <payload.json>`
141 
142### Read inbox data
143 
144Use Meta proxy or SDK:
145- Proxy: `GET /{phone_number_id}/messages`, `GET /{phone_number_id}/conversations`
146- SDK: `client.messages.query()`, `client.conversations.list()`
147 
148### Template rules
149 
150Creation:
151- Use `parameter_format: "NAMED"` with `{{param_name}}` (preferred over positional)
152- Include examples when using variables in HEADER/BODY
153- Use `language` (not `language_code`)
154- Don't interleave QUICK_REPLY with URL/PHONE_NUMBER buttons
155- URL button variables must be at the end of the URL and use positional `{{1}}`
156 
157Send-time:
158- For NAMED templates, include `parameter_name` in header/body params
159- URL buttons need a `button` component with `sub_type: "url"` and `index`
160- Media headers use either `id` or `link` (never both)
161 
162## WhatsApp Flows
163 
164Use Flows to build native WhatsApp forms. Read `references/whatsapp-flows-spec.md` before editing Flow JSON.
165 
166### Create and publish a flow
167 
1681. Create flow: `node scripts/create-flow.js --phone-number-id <id> --name <name>`
1692. Update JSON: `node scripts/update-flow-json.js --flow-id <id> --json-file <path>`
1703. Publish: `node scripts/publish-flow.js --flow-id <id>`
1714. Test: `node scripts/send-test-flow.js --phone-number-id <id> --flow-id <id> --to <phone>`
172 
173### Attach a data endpoint (dynamic flows)
174 
1751. Set up encryption: `node scripts/setup-encryption.js --flow-id <id>`
1762. Create endpoint: `node scripts/set-data-endpoint.js --flow-id <id> --code-file <path>`
1773. Deploy: `node scripts/deploy-data-endpoint.js --flow-id <id>`
1784. Register: `node scripts/register-data-endpoint.js --flow-id <id>`
179 
180### Flow JSON rules
181 
182Static flows (no data endpoint):
183- Use `version: "7.3"`
184- `routing_model` and `data_api_version` are optional
185- See `assets/sample-flow.json`
186 
187Dynamic flows (with data endpoint):
188- Use `version: "7.3"` with `data_api_version: "3.0"`
189- `routing_model` is required (defines valid screen transitions)
190- See `assets/dynamic-flow.json`
191 
192### Data endpoint rules
193 
194Handler signature:
195```js
196async function handler(request, env) {
197  const body = await request.json();
198  // body.data_exchange.action: INIT | data_exchange | BACK
199  // body.data_exchange.screen: current screen id
200  // body.data_exchange.data: user inputs
201  return Response.json({
202    version: "3.0",
203    screen: "NEXT_SCREEN_ID",
204    data: { }
205  });
206}
207```
208 
209- Do not use `export` or `module.exports`
210- Completion uses `screen: "SUCCESS"` with `extension_message_response.params`
211- Do not include `endpoint_uri` or `data_channel_uri` (Kapso injects these)
212 
213### Troubleshooting
214 
215- Preview shows `"flow_token is missing"`: flow is dynamic without a data endpoint. Attach one and refresh.
216- Encryption setup errors: enable encryption in Settings for the phone number/WABA.
217- OAuthException 139000 (Integrity): WABA must be verified in Meta security center.
218 
219## Scripts
220 
221### Webhooks
222 
223| Script | Purpose |
224|--------|---------|
225| `list.js` | List webhooks |
226| `get.js` | Get webhook details |
227| `create.js` | Create a webhook |
228| `update.js` | Update a webhook |
229| `delete.js` | Delete a webhook |
230| `test.js` | Send a test event |
231 
232### Messaging and templates
233 
234| Script | Purpose | Required ID |
235|--------|---------|-------------|
236| `list-platform-phone-numbers.mjs` | Discover business_account_id + phone_number_id | — |
237| `list-connected-numbers.mjs` | List WABA phone numbers | business_account_id |
238| `list-templates.mjs` | List templates (with filters) | business_account_id |
239| `template-status.mjs` | Check single template status | business_account_id |
240| `create-template.mjs` | Create a template | business_account_id |
241| `update-template.mjs` | Update existing template | business_account_id |
242| `send-template.mjs` | Send template message | phone_number_id |
243| `send-interactive.mjs` | Send interactive message | phone_number_id |
244| `upload-media.mjs` | Upload media for send-time headers | phone_number_id |
245 
246### Flows
247 
248| Script | Purpose |
249|--------|---------|
250| `list-flows.js` | List all flows |
251| `create-flow.js` | Create a new flow |
252| `get-flow.js` | Get flow details |
253| `read-flow-json.js` | Read flow JSON |
254| `update-flow-json.js` | Update flow JSON (creates new version) |
255| `publish-flow.js` | Publish a flow |
256| `get-data-endpoint.js` | Get data endpoint config |
257| `set-data-endpoint.js` | Create/update data endpoint code |
258| `deploy-data-endpoint.js` | Deploy data endpoint |
259| `register-data-endpoint.js` | Register data endpoint with Meta |
260| `get-encryption-status.js` | Check encryption status |
261| `setup-encryption.js` | Set up flow encryption |
262| `send-test-flow.js` | Send a test flow message |
263| `delete-flow.js` | Delete a flow |
264| `list-flow-responses.js` | List stored flow responses |
265| `list-function-logs.js` | List function logs |
266| `list-function-invocations.js` | List function invocations |
267 
268### OpenAPI
269 
270| Script | Purpose |
271|--------|---------|
272| `openapi-explore.mjs` | Explore OpenAPI (search/op/schema/where) |
273 
274Examples:
275```bash
276node scripts/openapi-explore.mjs --spec whatsapp search "template"
277node scripts/openapi-explore.mjs --spec whatsapp op sendMessage
278node scripts/openapi-explore.mjs --spec whatsapp schema TemplateMessage
279node scripts/openapi-explore.mjs --spec platform ops --tag "WhatsApp Flows"
280node scripts/openapi-explore.mjs --spec platform op setupWhatsappFlowEncryption
281node scripts/openapi-explore.mjs --spec platform search "setup link"
282```
283 
284## Assets
285 
286| File | Description |
287|------|-------------|
288| `template-utility-order-status-update.json` | UTILITY template with named params + URL button |
289| `send-template-order-status-update.json` | Send-time payload for order_status_update |
290| `template-utility-named.json` | UTILITY template showing button ordering rules |
291| `template-marketing-media-header.json` | MARKETING template with IMAGE header |
292| `template-authentication-otp.json` | AUTHENTICATION OTP template (COPY_CODE) |
293| `send-interactive-buttons.json` | Interactive button message |
294| `send-interactive-list.json` | Interactive list message |
295| `send-interactive-cta-url.json` | Interactive CTA URL message |
296| `send-interactive-location-request.json` | Location request message |
297| `send-interactive-catalog-message.json` | Catalog message |
298| `sample-flow.json` | Static flow example (no endpoint) |
299| `dynamic-flow.json` | Dynamic flow example (with endpoint) |
300| `webhooks-example.json` | Webhook create/update payload example |
301 
302## References
303 
304- [references/getting-started.md](references/getting-started.md) - Platform onboarding
305- [references/platform-api-reference.md](references/platform-api-reference.md) - Full endpoint reference
306- [references/setup-links.md](references/setup-links.md) - Setup link configuration
307- [references/detecting-whatsapp-connection.md](references/detecting-whatsapp-connection.md) - Connection detection methods
308- [references/webhooks-overview.md](references/webhooks-overview.md) - Webhook types, signature verification, retries
309- [references/webhooks-event-types.md](references/webhooks-event-types.md) - Available events
310- [references/webhooks-reference.md](references/webhooks-reference.md) - Webhook API and payload notes
311- [references/templates-reference.md](references/templates-reference.md) - Template creation rules, components cheat sheet, send-time components
312- [references/whatsapp-api-reference.md](references/whatsapp-api-reference.md) - Meta proxy payloads for messages and conversations
313- [references/whatsapp-cloud-api-js.md](references/whatsapp-cloud-api-js.md) - SDK usage for sending and reading messages
314- [references/whatsapp-flows-spec.md](references/whatsapp-flows-spec.md) - Flow JSON spec
315 
316## Related skills
317 
318- `automate-whatsapp` - Workflows, agents, and automations
319- `observe-whatsapp` - Debugging, logs, health checks
320 
321<!-- FILEMAP:BEGIN -->
322```text
323[integrate-whatsapp file map]|root: .
324|.:{package.json,SKILL.md}
325|assets:{dynamic-flow.json,sample-flow.json,send-interactive-buttons.json,send-interactive-catalog-message.json,send-interactive-cta-url.json,send-interactive-list.json,send-interactive-location-request.json,send-template-order-status-update.json,template-authentication-otp.json,template-marketing-media-header.json,template-utility-named.json,template-utility-order-status-update.json,webhooks-example.json}
326|references:{detecting-whatsapp-connection.md,getting-started.md,platform-api-reference.md,setup-links.md,templates-reference.md,webhooks-event-types.md,webhooks-overview.md,webhooks-reference.md,whatsapp-api-reference.md,whatsapp-cloud-api-js.md,whatsapp-flows-spec.md}
327|scripts:{create-flow.js,create-function.js,create-template.mjs,create.js,delete-flow.js,delete.js,deploy-data-endpoint.js,deploy-function.js,get-data-endpoint.js,get-encryption-status.js,get-flow.js,get-function.js,get.js,list-connected-numbers.mjs,list-flow-responses.js,list-flows.js,list-function-invocations.js,list-function-logs.js,list-platform-phone-numbers.mjs,list-templates.mjs,list.js,openapi-explore.mjs,publish-flow.js,read-flow-json.js,register-data-endpoint.js,send-interactive.mjs,send-template.mjs,send-test-flow.js,set-data-endpoint.js,setup-encryption.js,submit-template.mjs,template-status.mjs,test.js,update-flow-json.js,update-function.js,update-template.mjs,update.js,upload-media.mjs,upload-template-header-handle.mjs}
328|scripts/lib:{args.mjs,cli.js,env.js,env.mjs,http.js,output.js,output.mjs,request.mjs,run.js,whatsapp-flow.js}
329|scripts/lib/webhooks:{args.js,kapso-api.js,webhook.js}
330```
331<!-- FILEMAP:END -->
332 
333