whatsapp-flows

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

Script	Purpose
list-flows.js	List all flows
create-flow.js	Create a new flow
get-flow.js	Get flow details
read-flow-json.js	Read flow JSON
update-flow-json.js	Update flow JSON (creates new version)
publish-flow.js	Publish a flow
get-data-endpoint.js	Get data endpoint config
set-data-endpoint.js	Create/update data endpoint code
deploy-data-endpoint.js	Deploy data endpoint
register-data-endpoint.js	Register data endpoint with Meta
get-encryption-status.js	Check encryption status
setup-encryption.js	Set up flow encryption

Meta proxy

Script	Purpose
send-test-flow.js	Send a test flow message
delete-flow.js	Delete a flow

Logs and responses

Script	Purpose
list-flow-responses.js	List stored flow responses
list-function-logs.js	List function logs
list-function-invocations.js	List function invocations

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