WhatsApp: Flows through the API
List the published WhatsApp Flows of a number and send a Flow to the contact through the XBASE API, within the 24-hour window.
Updated on
A WhatsApp Flow is a form that opens inside WhatsApp, like a sign-up, a booking or a survey. Flows are created and published in WhatsApp API → Flows, and the contact's answers arrive in the conversation.
List the Flows
GET https://api.xbase.app/api/external/v1/whatsapp/flows?numberId=6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3bnumberId is required: Flows belong to the business's WhatsApp account at Meta, and each number sends the ones of its account.
curl "https://api.xbase.app/api/external/v1/whatsapp/flows?numberId=6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3b" \
-H "Authorization: Bearer $XBASE_API_KEY"Response 200:
[
{
"id": "1234567890123456",
"name": "Visit booking",
"status": "PUBLISHED",
"categories": ["APPOINTMENT_BOOKING"]
}
]| Field | Type | Description |
|---|---|---|
id | text | Flow id at Meta. Goes in flow.flowId when sending |
name | text | Flow name |
status | text | PUBLISHED, or THROTTLED (published, but Meta limited it to 10 sends per hour) |
categories | list of texts | Flow categories at Meta |
Only the Flows Meta delivers to a contact come back: drafts and deprecated Flows are left out.
Send a Flow
A Flow goes out through POST /whatsapp/messages with "type": "flow", within the 24-hour window:
curl -X POST https://api.xbase.app/api/external/v1/whatsapp/messages \
-H "Authorization: Bearer $XBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"numberId": "6d1f3c2a-4b5e-4f60-9a7b-8c9d0e1f2a3b",
"to": "15555550100",
"type": "flow",
"flow": {
"flowId": "1234567890123456",
"body": "Pick the best day for the visit.",
"cta": "Book"
}
}'| Field | Rule |
|---|---|
flow.flowId | Flow id, digits only (list the Flows) |
flow.body | Message text, up to 1,024 characters |
flow.cta | Text of the button that opens the Flow, up to 30 characters |
flow.header · flow.footer | Optional, up to 60 characters |
The response is the same as for messages. The Flow opens on the first screen. When the contact submits the form, the answers show up in the conversation and arrive as whatsapp.message.received in the workspace webhooks.
Errors
| Status | code | When |
|---|---|---|
| 400 | (no code) | Missing numberId, flowId with anything other than digits, or a Flow without screens |
| 404 | NUMBER_NOT_FOUND | The number does not exist in this workspace |
| 404 | FLOW_NOT_FOUND | The Flow does not belong to this number's WhatsApp account |
| 422 | NUMBER_DISCONNECTED | The number is disconnected |
| 422 | WINDOW_CLOSED | Outside the 24-hour window. Send a template |
| 422 | META_ERROR | Meta refused. details.metaCode has Meta's code |
See the full format in Errors.