Flow

Sends a WhatsApp Flow message to a recipient. Flows are interactive forms inside WhatsApp (multi-step UI) that let users submit structured information without leaving the chat.

Once the user completes the Flow, the form outcome is sent to a URL you configure (your Flow completion endpoint). This makes Flows perfect for Make / n8n / Zapier automations where you want structured inputs instead of free-text.

Common use cases:

Collecting appointment details (date, time, location)
Return / refund forms (order number, reason, photos)
Lead intake (name, email, interest)
Onboarding questionnaires (preferences, profile info)
Support triage (category, urgency, attachments)

Webhook / callback note: when the user submits the Flow, WhatsApp sends the form result to the completion URL configured for your Flow (your backend / Make / n8n webhook).

URL


https://api.messagesmart.nl/api/v1/whatsapp/messages/flow

Headers

See Authentication.

Request body

Field	Type	Required	Notes
whatsAppBusinessId	string	Yes	Can be collected from the dashboard or provided via webhook
whatsAppBusinessPhoneNumberId	string	Yes	Can be collected from the dashboard or provided via webhook
to	string	Yes	Recipient phone number in E.164 format
flowId	string	Yes	Meta Flow ID
body	string	No	Optional text shown above the Flow button
flowCta	string	No	Optional override for the Flow button label
flowAction	string	No	Defaults to `navigate`
flowMessageVersion	string	No	Defaults to `3`
flowActionPayload	object	Yes	Dynamic payload passed into the Flow (e.g. screen + data)

flowActionPayload (dynamic)

flowActionPayload is sent to WhatsApp as the Flow parameters payload. Use it to define the starting screen and pass any contextual data your Flow needs.

Example shape:


{
  "screen": "INTRO",
  "data": {
    "customerId": "cus_123",
    "ticketId": "tkt_456"
  }
}

Examples

JSON


{
  "whatsAppBusinessId": "123456789012345",
  "whatsAppBusinessPhoneNumberId": "399750423212934",
  "to": "+31612345678",
  "flowId": "987654321098765",
  "body": "Please fill in the form so we can help you faster.",
  "flowCta": "Open form",
  "flowAction": "navigate",
  "flowMessageVersion": "3",
  "flowActionPayload": {
    "screen": "INTRO",
    "data": {
      "requestType": "appointment",
      "customerRef": "CUST-10024"
    }
  }
}

cURL


curl -X POST "https://api.messagesmart.nl/api/v1/whatsapp/messages/flow" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsAppBusinessId": "123456789012345",
    "whatsAppBusinessPhoneNumberId": "399750423212934",
    "to": "+31612345678",
    "flowId": "987654321098765",
    "body": "Please fill in the form so we can help you faster.",
    "flowCta": "Open form",
    "flowAction": "navigate",
    "flowMessageVersion": "3",
    "flowActionPayload": {
      "screen": "INTRO",
      "data": {
        "requestType": "appointment",
        "customerRef": "CUST-10024"
      }
    }
  }'

Node.js


const response = await fetch(
  "https://api.messagesmart.nl/api/v1/whatsapp/messages/flow",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.MESSAGESMART_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      whatsAppBusinessId: "123456789012345",
      whatsAppBusinessPhoneNumberId: "399750423212934",
      to: "+31612345678",
      flowId: "987654321098765",
      body: "Please fill in the form so we can help you faster.",
      flowCta: "Open form",
      flowAction: "navigate",
      flowMessageVersion: "3",
      flowActionPayload: {
        screen: "INTRO",
        data: {
          requestType: "appointment",
          customerRef: "CUST-10024",
        },
      },
    }),
  }
);
 
const json = await response.json();
console.log(json);
 
if (!json.success) {
  throw new Error(`${json.error.code}: ${json.error.message}`);
}

Response

Success (200 OK)


{
  "success": true,
  "data": {
    "messaging_product": "whatsapp",
    "contacts": [
      {
        "input": "+31612345678",
        "wa_id": "31612345678"
      }
    ],
    "messages": [
      {
        "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI1RjQyNUE3NEYxMzAzMzQ5MkEA"
      }
    ]
  }
}

Notes

The returned data.messages[0].id is the WhatsApp message ID.
The Flow result is not returned by this endpoint. It is delivered to the Flow completion URL you configured.

Validation error (400 Bad Request)


{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "FlowId is required",
    "httpStatus": 400,
    "details": null
  }
}

Common causes:

Missing flowId
Missing flowActionPayload
Missing WhatsApp business identifiers

Provider error (502 Bad Gateway)


{
  "success": false,
  "error": {
    "code": "WHATSAPP_SEND_FAILED",
    "message": "Failed to send WhatsApp flow message.",
    "httpStatus": 502,
    "details": {
      "provider": "meta",
      "raw": {}
    }
  }
}