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:

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