name: whatsapp-flows
description: Manage WhatsApp Flows via Kapso Platform API. List, create, update, publish flows, manage versions, attach data endpoints, and check encryption. Use when working with WhatsApp Flows, flow JSON, or data endpoints.

WhatsApp Flow Management

When to use

Use this skill to manage WhatsApp Flows end-to-end: discover flows, edit flow JSON via versions, publish/test, attach data endpoints, and inspect responses/logs.

Setup

Env vars:
- KAPSO_API_BASE_URL (host only, no /platform/v1)
- KAPSO_API_KEY
- PROJECT_ID
- META_GRAPH_VERSION (optional, default v24.0)

Run scripts with Node or Bun:

node scripts/list-flows.js

How to

Create and publish a flow

1. Create flow: node scripts/create-flow.js --phone-number-id <id> --name <name>
2. Read references/whatsapp-flows-spec.md for Flow JSON rules
3. Update JSON: node scripts/update-flow-json.js --flow-id <id> --json-file <path>
4. Publish: node scripts/publish-flow.js --flow-id <id>
5. Test: node scripts/send-test-flow.js --phone-number-id <id> --flow-id <id> --to <phone>

Attach a data endpoint (dynamic flows)

1. Set up encryption: node scripts/setup-encryption.js --flow-id <id>
2. Create endpoint: node scripts/set-data-endpoint.js --flow-id <id> --code-file <path>
3. Deploy: node scripts/deploy-data-endpoint.js --flow-id <id>
4. Register: node scripts/register-data-endpoint.js --flow-id <id>

Debug flows

• List responses: node scripts/list-flow-responses.js --flow-id <id>
• Function logs: node scripts/list-function-logs.js --flow-id <id>
• Function invocations: node scripts/list-function-invocations.js --flow-id <id>

Flow JSON rules

Static flows (no data endpoint):
- Use version: "7.3"
- routing_model and data_api_version are optional
- See assets/sample-flow.json

Dynamic flows (with data endpoint):
- Use version: "7.3" with data_api_version: "3.0"
- routing_model is required - defines valid screen transitions
- See assets/dynamic-flow.json

Read the full spec in references/whatsapp-flows-spec.md before editing.

Data endpoint rules

Handler signature:

async function handler(request, env) {
  const body = await request.json();
  // body.data_exchange.action: INIT | data_exchange | BACK
  // body.data_exchange.screen: current screen id
  // body.data_exchange.data: user inputs
  return Response.json({
    version: "3.0",
    screen: "NEXT_SCREEN_ID",
    data: { ... }
  });
}

• Do not use export or module.exports
• Completion uses screen: "SUCCESS" with extension_message_response.params
• Do not include endpoint_uri or data_channel_uri (Kapso injects these)

Scripts

Platform API

Meta proxy

Logs and responses

Troubleshooting

• Preview shows "flow_token is missing": Flow is dynamic without a data endpoint. Attach one and refresh.
• Encryption setup errors: Enable encryption in Settings for the phone number/WABA.
• OAuthException 139000 (Integrity): WABA must be verified in Meta security center.

References

• references/whatsapp-flows-spec.md - Flow JSON spec (read before editing)
• assets/sample-flow.json - Static flow example (no endpoint)
• assets/dynamic-flow.json - Dynamic flow example (with endpoint)

Related skills

• whatsapp-messaging - WhatsApp messaging and templates
• kapso-automation - Workflow automation
• kapso-api - Platform API and customers