Skip to main content
WhatsApp

Flows

Build native in-chat forms: create a Flow from its screen JSON, preview, publish, deprecate and send it.

Overview

A Flow is a multi-screen form WhatsApp renders inside the conversation — no browser, no link-out. Customers pick dates, confirm an address or answer a survey without leaving the chat, and the submission comes back to you as structured JSON.

Typical uses: cash-on-delivery confirmation, address capture, lead qualification, appointment booking, and post-conversation surveys.

Two APIs for the same Flows

Flows live on your WhatsApp Business Account (WABA). CallMissed gives you two ways to manage them. Both act on the same WABA, and a Flow made with either one is sent the same way.

WhatsApp Flow APIFlow records API
Base path/api/v1/whatsapp/flows/api/v1/commerce/flows
Scopeswhatsapp:read / whatsapp:writewa_flows:read / wa_flows:write
Ids in pathsWhatsApp's Flow idCallMissed's record id (UUID)
What a list returnsEvery Flow on the WABA, read live from WhatsApp, including ones made in WhatsApp ManagerOnly the Flows created through this API, from CallMissed's stored copy
OperationsCreate, list, get, preview, update metadata, replace the Flow JSON, publish, deprecate, deleteCreate, list, get, publish, delete, read submissions
Choosing the WABAaccount_id or waba_id on every callYour workspace's first connected number

Use the WhatsApp Flow API to build and iterate on a Flow: it is the only one that can replace the Flow JSON of a draft, give you a preview link, or deprecate a published Flow. Use the Flow records API when you want CallMissed to keep the Flow JSON alongside a record id, and to read submissions.

Lifecycle

create (DRAFT) ──▶ publish (PUBLISHED) ──▶ send ──▶ read responses
                                       └──▶ deprecate (DEPRECATED)
  1. Create with a Flow JSON screen document and one or more categories. It starts as DRAFT.
  2. Iterate while it is a draft: replace the Flow JSON and open the preview link (WhatsApp Flow API).
  3. Publish it. One way, and after publishing the screen document is frozen. A change means a new Flow.
  4. Send it with POST /api/v1/whatsapp/messages/interactive using interactive_type: "flow" and WhatsApp's Flow id. That is the billed, window-aware send path for every interactive message.
  5. Read the submissions with the Flow records API.
  6. Deprecate a published Flow you no longer want sent. A published Flow cannot be deleted.

Authentication

Authorization: Bearer cm_your_api_key
OperationScope
WhatsApp Flow API: list, get, previewwhatsapp:read
WhatsApp Flow API: create, update, replace JSON, publish, deprecate, deletewhatsapp:write
Flow records API: list, get, read responseswa_flows:read
Flow records API: create, publish, deletewa_flows:write

Your workspace also needs a connected WhatsApp number and Business Account. Without one, the Flow records API returns 409 No connected WhatsApp number for tenant and the WhatsApp Flow API returns 404 WhatsApp account not found.

Statuses

DRAFT, PUBLISHED, DEPRECATED, BLOCKED, THROTTLED. Only the first two are ever set from this API; the rest can appear when WhatsApp changes a Flow's state on its side.

Categories

Every Flow declares 1–8 categories: SIGN_UP, SIGN_IN, APPOINTMENT_BOOKING, LEAD_GENERATION, CONTACT_US, CUSTOMER_SUPPORT, SURVEY, OTHER.

WhatsApp Flow API

Every call reads or writes the Flow at WhatsApp directly. Nothing is cached, so a status WhatsApp changed on its side (BLOCKED, THROTTLED) shows up on the next read.

Choosing the WABA

Every route takes the WABA as a selector: account_id (CallMissed's UUID from List accounts) or waba_id (Meta's id, at most 64 characters). On POST /flows it goes in the body; on every other route it is a query parameter. One of the two is required, otherwise 400 Either account_id (UUID) or waba_id (Meta) is required.

Before acting on a Flow id, CallMissed checks that the Flow is on that WABA. A Flow id that is not returns the same 404 Flow not found as one that does not exist.

The Flow object

{
  "id": "1122334455667788",
  "name": "Appointment booking",
  "status": "DRAFT",
  "categories": ["APPOINTMENT_BOOKING"],
  "validation_errors": [],
  "json_version": "7.0",
  "data_api_version": null,
  "endpoint_uri": null
}
FieldTypeNotes
idstringWhatsApp's Flow id. Use it in paths here and as flow_id when sending
namestring, nullable
statusstring, nullableOne of the five statuses
categoriesstring[]
validation_errorsobject[]Problems WhatsApp found in your Flow JSON, as WhatsApp reports them (message, line and column spans). A Flow cannot be published while this is non-empty
json_versionstring, nullableThe Flow JSON version
data_api_versionstring, nullableSet on endpoint-backed Flows
endpoint_uristring, nullableSet on endpoint-backed Flows

Create a Flow

POST /api/v1/whatsapp/flows · scope whatsapp:write

FieldTypeRequiredNotes
account_id / waba_idUUID / stringOne of the twoThe WABA to create the Flow on
namestring, 1 to 512 charsYes
categoriesstring[]YesAt least one, from the category list
flow_jsonobject or stringNoThe screen document, as an object or an already-encoded JSON string. Can be added later with Replace the Flow JSON
clone_flow_idstring, max 64NoStart from a copy of an existing Flow on the same WABA
endpoint_uristring, max 2048NoYour data-exchange endpoint. Omit for a static Flow
publishbooleanNoPublish on creation. Irreversible. Default off
curl -X POST https://api.callmissed.com/api/v1/whatsapp/flows \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "waba_id": "102290129340398",
    "name": "Appointment booking",
    "categories": ["APPOINTMENT_BOOKING"],
    "flow_json": { "version": "7.0", "screens": [] }
  }'

Response (200 OK)

{
  "id": "1122334455667788",
  "success": true,
  "validation_errors": []
}

A 200 with entries in validation_errors means the Flow was created and its JSON needs fixing before it can be published. The response carries the id either way.

List Flows

GET /api/v1/whatsapp/flows · scope whatsapp:read

ParamTypeDefaultNotes
account_id / waba_idUUID / stringOne of the two is required
limitinteger, 1 to 10050Page size
afterstring, max 512next_cursor from the previous page
curl "https://api.callmissed.com/api/v1/whatsapp/flows?waba_id=102290129340398&limit=50" \
  -H "Authorization: Bearer cm_your_api_key"
{
  "flows": [
    {
      "id": "1122334455667788",
      "name": "Appointment booking",
      "status": "PUBLISHED",
      "categories": ["APPOINTMENT_BOOKING"],
      "validation_errors": [],
      "json_version": null,
      "data_api_version": null,
      "endpoint_uri": null
    }
  ],
  "next_cursor": null
}

next_cursor is null on the last page.

Get a Flow

GET /api/v1/whatsapp/flows/{flow_id}?waba_id=... · scope whatsapp:read

Returns one Flow object, including json_version, data_api_version, endpoint_uri and validation_errors.

Preview a Flow

GET /api/v1/whatsapp/flows/{flow_id}/preview?waba_id=... · scope whatsapp:read

ParamTypeDefaultNotes
invalidatebooleanfalsetrue issues a new link and stops the previous one working
{
  "preview_url": "<the preview link WhatsApp returns>",
  "expires_at": "2026-08-24T09:00:00+0000"
}

Open preview_url in a browser to click through the Flow as a customer would. Leave invalidate off unless a link has been shared too widely.

Update Flow metadata

PATCH /api/v1/whatsapp/flows/{flow_id}?waba_id=... · scope whatsapp:write

FieldTypeNotes
namestring, 1 to 512 chars
categoriesstring[]
endpoint_uristring, max 2048

Send at least one field, otherwise 400. Only the fields you send change. Returns { "success": true }. A published Flow cannot be modified, and WhatsApp's refusal comes back as 422.

Replace the Flow JSON

POST /api/v1/whatsapp/flows/{flow_id}/assets?waba_id=... · scope whatsapp:write

FieldTypeRequiredNotes
flow_jsonobject or stringYesThe full screen document. WhatsApp limits it to 10 MB
curl -X POST "https://api.callmissed.com/api/v1/whatsapp/flows/1122334455667788/assets?waba_id=102290129340398" \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "flow_json": { "version": "7.0", "screens": [] } }'
{ "success": true, "validation_errors": [] }

As with create, a 200 with validation_errors means the upload landed and the document has problems to fix before you can publish.

Publish a Flow

POST /api/v1/whatsapp/flows/{flow_id}/publish?waba_id=... · scope whatsapp:write

No body. Returns { "success": true }. Irreversible: a published Flow cannot be updated or deleted, only deprecated. WhatsApp refuses to publish while validation errors are outstanding.

Deprecate a Flow

POST /api/v1/whatsapp/flows/{flow_id}/deprecate?waba_id=... · scope whatsapp:write

No body. Returns { "success": true }. A deprecated Flow can no longer be sent or opened. It does not undo publishing.

Delete a Flow

DELETE /api/v1/whatsapp/flows/{flow_id}?waba_id=... · scope whatsapp:write

Returns 204. Only a DRAFT Flow can be deleted. WhatsApp's refusal for any other status comes back as 422; deprecate a published Flow instead.

Errors

StatusWhen
400No account_id or waba_id, an empty PATCH body, or WhatsApp rejected the name, categories or JSON
401The WABA's access token is no longer valid. Reconnect the number
403Key is missing whatsapp:read / whatsapp:write, or the WABA has not granted the permission this needs
404WhatsApp account not found, or Flow not found on that WABA
409The WABA is disconnected, or has no usable token. Reconnect it
422WhatsApp refused the request for the Flow's current status (for example, editing or deleting a published Flow)
503WhatsApp did not respond correctly. Retry

Managing Flows does not consume credits.

Flow records API

CallMissed keeps a copy of each Flow created here, with the Flow JSON you sent and its own record id. The WABA is your workspace's first connected number's account.

The flow record

{
  "id": "f1a2…",
  "tenant_id": "a0b1…",
  "flow_id": "1122334455667788",
  "name": "Appointment booking",
  "categories": ["APPOINTMENT_BOOKING"],
  "status": "PUBLISHED",
  "flow_json": { "version": "7.0", "screens": [] },
  "endpoint_uri": null,
  "created_at": "2026-08-09T09:00:00Z",
  "updated_at": "2026-08-09T09:30:00Z"
}

There are two ids. id is the CallMissed record and is what every path parameter in the Flow records API takes. flow_id is WhatsApp's id — that is the one you pass to the send endpoint.

endpoint_uri decides the Flow's kind:

endpoint_uriKindBehaviour
nullStaticEvery screen is defined up front in flow_json
SetEndpoint-backedScreens are served from your endpoint at runtime via data_exchange

Start static. It needs no server, no encryption key and no runtime availability on your side.

GET/api/v1/commerce/flows

Newest first.

ParameterTypeConstraints
statusstringOne of the five statuses
limitinteger1 <= limit <= 200, default 50
offsetinteger0 <= offset <= 100000, default 0

POST/api/v1/commerce/flows

FieldTypeRequiredConstraints
namestringYes1–255 characters, not blank
categoriesstring[]Yes1–8 entries from the category list
flow_jsonobjectYesThe screen document. At most 10 MB serialised
endpoint_uristringNoAt most 512 characters. Omit for a static Flow
curl -X POST https://api.callmissed.com/api/v1/commerce/flows \
  -H "Authorization: Bearer cm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment booking",
    "categories": ["APPOINTMENT_BOOKING"],
    "flow_json": { "version": "7.0", "screens": [] }
  }'

Returns 201 with status: "DRAFT".

The Flow is created at WhatsApp first, then mirrored locally — so a rejected screen document never leaves a phantom record behind. WhatsApp's validation message is passed through verbatim, which is what you want when a screen definition is malformed.

GET/api/v1/commerce/flows/{flow_uuid}

One Flow by its CallMissed id. 404 Flow not found.

POST/api/v1/commerce/flows/{flow_uuid}/publish

No body. Moves DRAFT to PUBLISHED.

curl -X POST https://api.callmissed.com/api/v1/commerce/flows/f1a2…/publish \
  -H "Authorization: Bearer cm_your_api_key"

One way, and irreversible. Publishing freezes the screen document — iterate while the Flow is still a draft. WhatsApp validates the whole document at this point, so this is where a structural mistake surfaces.

DELETE/api/v1/commerce/flows/{flow_uuid}

Returns 204.

WhatsApp refuses to delete a PUBLISHED Flow and its refusal is passed through. If the Flow is already gone upstream, the local record is still cleared, so a stale mirror can always be tidied.

Responses

When a customer completes a Flow, the submission is stored here: one record per WhatsApp message id (a redelivered message is not stored twice), correlated by the flow_token you set when sending.

WhatsApp's completion message does not carry the Flow id, so flow_id is null on captured submissions and filtering by flow_id does not match them. Filter by flow_token or contact_id instead. The message.received webhook event for a submission has type: "interactive" and a message_id equal to the record's wa_message_id, but not the screen data: read that here.

GET/api/v1/commerce/flows/responses

Newest first.

ParameterTypeConstraints
flow_idstringWhatsApp's flow id, at most 64 characters
flow_tokenstringAt most 128 characters — the identifier you sent
contact_idUUID
limitinteger1 <= limit <= 200, default 50
offsetinteger0 <= offset <= 100000, default 0
[
  {
    "id": "r9c8…",
    "tenant_id": "a0b1…",
    "flow_id": null,
    "flow_token": "booking-4471",
    "wa_message_id": "wamid.HBg…",
    "contact_id": "4411…",
    "conversation_id": "c0ff…",
    "response": { "flow_token": "booking-4471", "date": "2026-08-22", "slot": "10:30", "branch": "Kothrud" },
    "created_at": "2026-08-17T07:41:00Z"
  }
]

response is the screen data the customer submitted, exactly as your flow_json defined the field names, plus the flow_token.

Filtering by your own flow_token is the reliable way to tie a submission back to the order, booking or ticket you sent it for — set it to something meaningful when you send.

GET/api/v1/commerce/flows/responses/{response_id}

One submission by its CallMissed id. 404 Flow response not found.

Flow records errors

StatusWhen
403Key is missing wa_flows:read / wa_flows:write
404Flow or response not in your tenant
409No connected WhatsApp number or Business Account for your tenant
422Blank name, no categories, an unknown category, or a flow_json over 10 MB
503WhatsApp accepted the call but returned no flow id

Errors originating at WhatsApp keep their status code and message, so a validation failure reads the same as it would against the Cloud API directly.

Creating, publishing, deleting and reading Flows do not consume credits. Sending a Flow message is billed on the interactive message endpoint.

On this page