Data endpoint

Serve dynamic data to WhatsApp Flows

Dynamic WhatsApp Flows call your data endpoint to fetch screen content at runtime.

How it works

1. User opens the flow in WhatsApp
2. Meta sends an encrypted request to Kapso
3. Kapso decrypts and forwards to your function
4. Your function returns screen data
5. Kapso encrypts and returns to Meta
6. User sees the dynamic content

Setup requirements

Before using data endpoints:

1. WhatsApp phone number - Set in the Info tab
2. Flows encryption - One-time setup per phone number (Kapso handles the key exchange)
3. Function - Your code that returns screen data

Share a function across flows

Attach an existing deployed function using the Platform API:

curl -X PATCH "https://api.kapso.ai/platform/v1/whatsapp/flows/$FLOW_ID/data_endpoint" \
  -H "X-API-Key: $KAPSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"function_id": "YOUR_FUNCTION_UUID"}'

Use the Kapso Flow UUID, not the Meta Flow ID. Repeat the request for each flow that should use the function. The function and all flows must belong to the same project, and each flow needs a phone number with flows encryption configured.

This registers each flow’s endpoint with Meta without creating or deploying another function. Each flow keeps its own endpoint URL and secret. Use flow.id or flow.meta_flow_id in the request payload to distinguish flows.

Changing or deploying the shared function affects all flows attached to it, including changes made through a flow’s data endpoint code API. Attaching a new function replaces the association without deleting the old function. A missing, null, or empty function_id is rejected; this endpoint does not detach functions.

The flow’s function_logs and function_invocations endpoints return activity for the entire attached function, including calls from other flows sharing it. They do not filter activity to the requested flow.

For published flows, Kapso attempts to republish automatically. If republishing fails, the request still returns HTTP 200 with data.warning: the association was saved, but you need to republish the flow manually.

Request format

Kapso sends this payload to your function:

{
  "source": "whatsapp_flow",
  "flow": {
    "id": "kapso_flow_id",
    "meta_flow_id": "meta_flow_id"
  },
  "data_exchange": {
    "version": "3.0",
    "action": "data_exchange",
    "screen": "CURRENT_SCREEN",
    "data": {},
    "flow_token": "unique_session_token"
  },
  "signature_valid": true,
  "received_at": "2024-01-15T10:30:00Z"
}

The data_exchange object contains Meta’s original payload with the current screen and any user-submitted data.

Response format

Your function must return:

{
  "version": "3.0",
  "screen": "NEXT_SCREEN_ID",
  "data": {
    "field_name": "value"
  }
}

Field	Description
version	Always "3.0"
screen	Screen ID to display next
data	Key-value pairs matching screen’s data schema

Completing the flow

To end the flow and close it:

{
  "version": "3.0",
  "screen": "SUCCESS",
  "data": {
    "extension_message_response": {
      "params": {
        "flow_token": "from_request"
      }
    }
  }
}

Limits

Limit	Value
Response timeout	15 seconds
Rate limit	100 requests/minute per flow

Error handling

If your function fails or times out, Kapso returns an error screen to the user. Check the Invocations in your function dashboard for debugging.