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
•META_GRAPH_VERSION (optional, default v24.0)

Run scripts with Node or Bun:

bash

node scripts/list-flows.js

How to

Create and publish a flow

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

Attach a data endpoint (dynamic flows)

•Set up encryption: node scripts/setup-encryption.js --flow-id <id>
•Create endpoint: node scripts/set-data-endpoint.js --flow-id <id> --code-file <path>
•Deploy: node scripts/deploy-data-endpoint.js --flow-id <id>
•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