API Reference v1.0

Send Flow

Send a published WhatsApp Flow to any phone number. The contact is created automatically if it does not already exist, and the recipient gets an interactive message with a button that opens your multi-screen form inside WhatsApp.

POST https://whatsbizapi.com/api/wpbox/sendflow

Sends the flow identified by flow_id to phone. The flow must belong to the account that owns the API token, and it must be published — a draft is rejected before anything reaches Meta.

⚠

Publish before you send: Meta accepts a draft flow at the API and then fails on the handset, so this endpoint refuses it instead. Publish the flow from /whatsapp-flows first.

Body Parameters

Parameter	Type	Description
token required	string	Your API authentication token. Found in your dashboard under Settings → API.
phone required	string	Recipient phone number in E.164 digits without a leading `+` — for example `919876543210`. If a contact with this number already exists on your account it is reused; otherwise a new contact is created.
flow_id required	integer \| string	The flow to send. Use the numeric id shown by the cURL button on the `/whatsapp-flows` list. Meta's own flow id (the long number printed under the flow name) is accepted too.
body optional	string	Message text shown above the button, max 1024 characters. Defaults to `Tap the button to start.`
cta optional	string	Button label, max 20 characters. Defaults to `Open`.
data optional	object	Values passed into the flow's first screen. Only useful when that screen declares matching `data` properties in its Flow JSON.

Example Request

cURL

curl -X POST https://whatsbizapi.com/api/wpbox/sendflow \
  -H "Content-Type: application/json" \
  -d '{
    "token": "YOUR_API_TOKEN",
    "phone": "919876543210",
    "flow_id": 12,
    "body": "Tap the button to book your slot.",
    "cta": "Book now"
  }'

Example Response

Response 200

{
  "status": "success",
  "flow_id": 12,
  "message_wamid": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgS...",
  "flow_token": "api-0-4471-Xa1b2c3d4e5f"
}

Response Fields

Field	Type	Description
`status`	string	`success` when WhatsApp accepted the message.
`flow_id`	integer	The id of the flow that was sent.
`message_wamid`	string	WhatsApp's message id for the send.
`flow_token`	string	Minted per recipient and echoed back in the `nfm_reply` webhook — it is what links a submission to this exact send. Store it if you need to match responses yourself.

Error Responses

Error Response 401

{
  "status": "error",
  "message": "Invalid token"
}

Error Response 400

{
  "status": "error",
  "message": "Invalid flow"
}

Error Response 400

{
  "status": "error",
  "message": "Flow 'Lead capture' is not published, so it cannot be sent. Publish it first."
}

Validation Error 400

{
  "status": "error",
  "errors": {
    "flow_id": ["The flow id field is required."]
  }
}

Notes

ℹ

Copy the command instead of typing it: the cURL button in the Actions column of /whatsapp-flows copies a ready-to-run version of the request above, with your token and the right flow_id already filled in. Replace TARGET_NUMBER with the recipient.

ℹ

Responses arrive by webhook: when the recipient submits the form, WhatsApp posts an nfm_reply to your webhook carrying the flow_token from this response. See Webhooks.

⚠

Session window applies: a flow goes out as a session message, so the recipient must have messaged you within the last 24 hours. Outside that window, open the conversation with an approved template first — see Send Template.