Sending
A flow can be sent once it is published on the WhatsApp Business Account of the sending number. There are three ways:
- API:
POST /whatsapp-flows/{id}/send - Inbox: agents pick a flow in a WhatsApp conversation.
- Automation: the Send WhatsApp Flow node sends it and waits for the answers.
Every send creates a session: a unique token that ties the contact's answers back to the flow, the version and the sender.
POST /whatsapp-flows/{id}/send(this page) sends a flow built in SendSeven, by its SendSeven id. It creates a session, supports template mode and only sends published flows.POST /whatsapp/flows/sendsends any flow on the WhatsApp Business Account, including flows built in WhatsApp Manager, by its WhatsApp flow id. It sends an interactive message inside the 24-hour window only and can send a flow in draft mode for testing. See Send a flow built in WhatsApp Manager.
Interactive or template
WhatsApp only allows free-form messages within 24 hours after the contact's last message. That decides the mode:
mode | When | What the contact gets |
|---|---|---|
interactive (default) | The 24-hour service window is open. | A flow message with your header, body, footer and button text. |
template | Any time, including outside the window. | An approved WhatsApp template with a Flow button that opens this flow. |
Every way of sending a flow (this API, POST /whatsapp/flows/send, the inbox and automations) checks the window the same way. Any message the contact sent to that WhatsApp number in the last 24 hours opens it, including a newsletter keyword such as START that did not open a conversation.
For template mode, create a WhatsApp template with a Flow button that points to this flow and get it approved first (see WhatsApp templates).
Send via API
Scopes: messages:create and whatsapp_flows:read.
curl -X POST https://api.sendseven.com/api/v1/whatsapp-flows/0f9e8d7c-…/send \
-H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
-H "Content-Type: application/json" \
-d '{
"conversation_id": "9a8b7c6d-…",
"header_text": "Rückruf vereinbaren",
"body_text": "Wann dürfen wir dich anrufen? Das Formular dauert keine Minute.",
"cta": "Formular öffnen"
}'
Response 200:
{
"session_id": "5b0e2c1a-…",
"message_id": "msg_7e6d…",
"conversation_id": "9a8b7c6d-…",
"status": "sent",
"error": null
}
Request fields
| Field | Notes |
|---|---|
contact_id / conversation_id | Exactly one. A conversation also supplies the contact and its reply channel. |
channel_id | The WhatsApp channel to send from. Optional when it comes from the conversation or the template. |
mode | interactive (default) or template. |
header_text | Interactive only. Up to 60 characters. |
body_text | Interactive only. Up to 1024 characters. Defaults to "Tap the button below to continue." in the contact's language (else the workspace default language, else English). |
footer_text | Interactive only. Up to 60 characters. |
cta | Interactive only. The button text, up to 30 characters, for example "Formular öffnen". Defaults to "Get started" in the contact's language (else the workspace default language, else English). |
template_id | Template mode: the approved template with a Flow button. |
template_variables | Template mode: values for the template placeholders, as an object ({"1": "Anna"} or named parameters) or a list (["Anna"] becomes {"1": "Anna"}). |
screen | Optional entry screen (navigate only). Defaults to the first screen. |
initial_data | Optional data for the entry screen. Replaces the data from send-time bindings. |
flow_action | navigate or data_exchange. Leave it empty to let SendSeven choose (see below). |
Entry screen data
For a static flow, SendSeven fills the entry screen's data when the message is sent: from your initial_data if you pass it, otherwise from the entry screen's bindings (for example the contact's name and e-mail), otherwise from the declared example values.
For a dynamic flow, SendSeven by default sends the flow with flow_action: "data_exchange". The entry screen is then loaded live from the managed endpoint when the contact opens the flow, so the data is fresh even days later. Passing screen or initial_data switches to navigate. data_exchange on a flow without an endpoint returns 409 flow_action_requires_endpoint.
Session lifetime
An API send is valid for 72 hours. After that, a dynamic flow can no longer load data, and WhatsApp shows the contact an error instead of the next screen. A static flow that the contact already filled in on the phone is still accepted when it arrives late.
Session status | Meaning |
|---|---|
created | Session created, message not yet accepted by WhatsApp. |
sent | WhatsApp accepted the message. |
in_progress | The contact opened the flow (dynamic flows). |
completed | The contact submitted the flow. |
expired | expires_at passed without a submission. SendSeven moves open sessions to expired within a few minutes of expires_at. A static flow that arrives late still moves the session to completed. |
cancelled | Reserved. Not used at the moment. |
failed | WhatsApp rejected the send. error contains the reason. |
A send that WhatsApp rejects does not return an HTTP error: the response has status: "failed" and an error. HTTP errors are only returned when the send cannot start.
Errors
Errors come as {"detail": {"code": "...", "message": "...", "details": {...}}}; details only when there is extra context. The exceptions are noted in the table. An archived flow can still be sent. Request bodies that don't match the schema return the usual validation error list.
| Status | Code | Cause |
|---|---|---|
400 | channel_not_whatsapp | The channel is not a WhatsApp channel. |
400 | no_whatsapp_recipient | The contact has no WhatsApp number. |
400 | conversation_contact_mismatch | The conversation belongs to another contact. |
403 | feature_disabled | WhatsApp Flows are not included in the plan (feature: "whatsapp_flows", no message). |
404 | flow_definition_not_found, channel_not_found, conversation_not_found, template_not_found | Unknown flow, channel, conversation or template. A conversation you can't open counts as unknown. |
409 | CHANNEL_DISCONNECTED / CHANNEL_UNAVAILABLE | The number is disconnected, or Meta blocks sending for the account. code and error carry the value. See Lost access or blocked. |
409 | CHANNEL_TEMPLATES_BLOCKED | mode: "template" only: Meta reports a payment issue on the account, so template sends are paused. The interactive mode inside the 24-hour window is not affected. See Meta payment issue. |
409 | CONTACT_BLOCKED | The contact is blocked. This one is in detail.error. |
403 | translation_not_available | translate: true, but translation is not on your plan or is switched off for the workspace. In detail.code. |
409 | conversation_owned_elsewhere | Only for members limited to certain inboxes: the contact is in an ongoing conversation a colleague handles that you can't open. In detail.error. |
409 | flow_not_published | The flow is not published on the channel's WhatsApp Business Account. |
409 | flow_action_requires_endpoint | data_exchange on a flow without a managed endpoint. |
409 | dynamic_not_supported_on_coexistence | A dynamic flow on a number that also uses the WhatsApp Business app (Coexistence). These numbers can only send static flows. |
422 | outside_service_window | Interactive send outside the 24-hour window. details.last_customer_message_at tells you when the contact last wrote. Use template mode. |
422 | template_required | mode: "template" without template_id. |
422 | template_has_no_flow_button | The template has no Flow button. |
422 | template_flow_mismatch | The template's Flow button opens a different flow. |
422 | channel_required | No channel given and none could be derived. |
422 | recipient_required | Neither or both of contact_id and conversation_id. |
422 | invalid_mode, invalid_flow_action | Unknown value. |
422 | draft_send_not_supported | This endpoint sends only published flows. Use the preview link to test a draft, or send the draft to your own phone with POST /whatsapp/flows/send and mode: "draft". |
503 | flow_token_not_configured | Sending flows is temporarily unavailable. Retry later. |
Template send example
curl -X POST https://api.sendseven.com/api/v1/whatsapp-flows/0f9e8d7c-…/send \
-H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
-H "Content-Type: application/json" \
-d '{
"contact_id": "c0ffee00-…",
"mode": "template",
"template_id": "tpl_41b2…",
"template_variables": ["Anna"]
}'
Send a flow built in WhatsApp Manager
POST /whatsapp/flows/send sends a flow by its WhatsApp flow id. Use it for flows you built in WhatsApp Manager (Meta's Flow Builder); it also works for flows built in SendSeven, by their published WhatsApp flow id. The answers arrive as an incoming message, and whatsapp_flow.completed fires as well (see Responses and Webhooks). For a flow built outside SendSeven, flow_definition_id is null and nothing is written to the contact, because such a flow has no field mapping.
Scope: messages:create. Listing flows and saving default data need channels:read and channels:update.
Find the flow and the data it needs
# All flows of the channel's WhatsApp Business Account
curl "https://api.sendseven.com/api/v1/whatsapp/channels/{channel_id}/flows" \
-H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00"
# Screens, entry screen, data each screen expects, saved defaults
curl "https://api.sendseven.com/api/v1/whatsapp/channels/{channel_id}/flows/{flow_id}" \
-H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00"
Each flow in the list has id (the WhatsApp flow id), name, status (DRAFT, PUBLISHED, ...) and, for flows built in SendSeven, definition_id. Flows of archived SendSeven flows are hidden unless you pass include_archived=true.
The details response has screens (each with its input fields and its data_schema), entry_screen, variables, is_static and defaults (saved default data per screen). is_static: true means the flow has no data endpoint, so any data its first screen shows must be sent with the message. The flow JSON is cached for a few minutes; pass refresh=true to read it again.
Send
curl -X POST https://api.sendseven.com/api/v1/whatsapp/flows/send \
-H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
-H "Content-Type: application/json" \
-d '{
"channel_id": "ch_wa_001",
"conversation_id": "9a8b7c6d-…",
"flow_id": "1234567890123456",
"flow_cta": "Choose newsletters",
"body": "Which newsletters would you like to receive?",
"data": { "first_name": "{{contact.first_name}}" }
}'
| Field | Notes |
|---|---|
channel_id | Required. The WhatsApp channel to send from. |
conversation_id / contact_id / recipient | One of them. conversation_id wins and must belong to channel_id (400 conversation_channel_mismatch otherwise). recipient is a phone number of a contact who already wrote to you. Contacts reached through a WhatsApp username (no phone number) work with conversation_id or contact_id. |
flow_id | Required. The WhatsApp flow id. |
flow_cta | Required. Button text, 1 to 30 characters. |
body | Message text. header and footer are optional. (body_text, header_text, footer_text are accepted too.) Without a body, a default text in the sender's language is sent, see Default text and translation. |
screen | The screen to open. Defaults to the screen with saved default data, otherwise the flow's entry screen. |
data | Data for that screen, as a JSON object. See below. |
mode | published (default) or draft. A draft flow is meant for testing on your own phone; send published flows to customers. |
flow_token | Optional tracking token. Generated when you leave it out. |
translate | Optional. true translates the button text, body, header and footer into the recipient's language before sending; false never translates. Leave it out and API tokens never translate (the behaviour is unchanged for existing integrations). See Default text and translation. |
target_language | Optional ISO 639-1 code (es, fr, ...) to translate into. Defaults to the recipient's language. |
Response 200: success, message_id, external_id (the WhatsApp message id), conversation_id, flow_token, screen, translation, and on failure error and error_code. A send that WhatsApp rejects returns 200 with success: false. translation is null unless the texts were translated; then it holds source_language, target_language and fallback_fields (the fields sent untranslated).
Default text and translation
Default body. When body is empty, SendSeven sends a default text in the sender's app language: the user's personal language, else the workspace default language, else English ("Tap the button below to continue."). Defaults exist in English, German, French, Spanish, Portuguese, Italian, Arabic and Polish; other languages get the English text. For an API token without a user, the workspace default language is used.
Translation needs a plan with translation (Professional and higher) and translation switched on for the workspace. With "translate": true:
- The recipient's language comes from the conversation (the language chosen in "Send in", else the language detected from the customer's messages, else the contact's language), or from the contact's language when you send by
contact_id. Passtarget_languageto choose it yourself. - The button text, body, header and footer are translated together. A field whose translation fails or is longer than WhatsApp allows (button 30, header and footer 60, body 1024 characters) is sent in its original wording and listed in
translation.fallback_fields. A failed translation never stops the send. - An empty body is sent as the default text in the recipient's language when one exists (no translation needed).
- When the texts already are in the target language, nothing is translated and
translationisnull. - Translations are billed like other message translations at your AI model level. A preview (below) followed by the send of the same texts within about 15 minutes is billed once.
When translate is left out, a user signed in to SendSeven gets the same result as their personal Auto-translate setting: the texts are translated only if the user turned Auto-translate on, set the languages they speak, and the recipient's language is known for certain and is not one of them. API tokens and OAuth apps are never translated unless they send "translate": true.
The stored message holds what was actually sent: text and meta.flow_cta, meta.header, meta.footer are the translated texts. A translated message also carries meta.translation with source_language, target_language, fallback_fields and original (the texts before translation: flow_cta, body_text, header_text, footer_text). When the body was translated, meta.translations.original and meta.translated_to are set as for other translated replies.
Languages for a send:
curl "https://api.sendseven.com/api/v1/whatsapp/flows/send/translation-context?conversation_id=9a8b7c6d-…" \
-H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00"
{
"available": true,
"sender_language": "de",
"recipient_language": "es",
"recipient_language_confident": true,
"needs_translation": true,
"auto_translate": false
}
Pass conversation_id or contact_id; without either, recipient_language is null. available is false when translation is not on your plan or switched off; then only sender_language is filled. needs_translation is true when the recipient's language is known and is not a language the sender reads. auto_translate is true when a send without translate would be translated (always false for API tokens). Reading the context never translates anything. Scope: messages:create.
Preview the translated texts (billed as a translation):
curl -X POST https://api.sendseven.com/api/v1/whatsapp/flows/send/translation-preview \
-H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
-H "Content-Type: application/json" \
-d '{
"conversation_id": "9a8b7c6d-…",
"flow_cta": "Termin wählen",
"body_text": "Wann passt es dir?"
}'
{
"source_language": "de",
"target_language": "es",
"flow_cta": "Elegir cita",
"body_text": "¿Cuándo te viene bien?",
"header_text": null,
"footer_text": null,
"fallback_fields": []
}
The body takes conversation_id or contact_id, flow_cta (required), body_text, header_text, footer_text and an optional target_language. The response shows the texts exactly as the send with "translate": true would send them, including the default body. Errors: 403 with code: "translation_not_available", 422 with code: "recipient_language_unknown" (no target language known: pass target_language), 429 with code: "rate_limited". Scope: messages:create.
Screen data and saved defaults
Some flows show data you supply, for example a list of newsletters with the ones the contact already has pre-ticked. The example values entered in WhatsApp Manager are only used for Meta's preview, so such a flow needs its data on every send. SendSeven fills the screen data key by key, in this order:
datafrom the request,- the saved default data for this flow and screen,
- for flows built in SendSeven, the flow's send-time bindings,
- the flow's example data.
String values in data and in saved defaults can use contact variables, rendered per recipient: {{contact.first_name}}, {{contact.last_name}}, {{contact.name}}, {{contact.email}}, {{contact.phone}}, {{contact.birthday}}, {{contact.language}} and {{contact.custom.<key>}}. Unknown or empty variables become an empty string. The flow must bind the value as a dynamic property (for example a TextBody whose text is exactly ${data.first_name}); ${data.x} inside literal text is shown as is.
Save default data once per flow screen, so every send without data uses it, including templates with a Flow button for this flow:
curl -X PUT "https://api.sendseven.com/api/v1/whatsapp/channels/{channel_id}/flows/{flow_id}/defaults" \
-H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
-H "Content-Type: application/json" \
-d '{ "screen": "NEWSLETTERS", "data": { "lists": [{ "id": "news", "title": "Weekly news" }] } }'
Defaults are stored per WhatsApp channel and flow. Send "data": null to remove the default for that screen. The data must be a JSON object of at most 16 KB, and a channel can hold defaults for up to 200 flows; otherwise the request returns 422 with code: "invalid_defaults". If you change the flow in WhatsApp Manager, check that the saved defaults still match the fields the screen expects.
Errors
| Status | Code | Cause |
|---|---|---|
400 | detail is a message string: the channel is not a WhatsApp channel, or none of conversation_id, contact_id and recipient was given. | |
400 | conversation_channel_mismatch | The conversation is not on channel_id. In detail.code. |
400 | no_whatsapp_recipient | The contact has no WhatsApp id or phone number. In detail.code. |
404 | detail is a message string: channel, conversation or contact not found. | |
409 | CHANNEL_DISCONNECTED / CHANNEL_UNAVAILABLE | The number is disconnected, or Meta blocks sending for the account. In detail.error. |
409 | CONTACT_BLOCKED | The contact or number is blocked. In detail.error. |
409 | conversation_owned_elsewhere | Only for members limited to certain inboxes: the contact is in an ongoing conversation a colleague handles that you can't open. In detail.error. |
422 | outside_service_window | The 24-hour window is closed, or the contact never wrote to this number. detail has last_customer_message_at and window_end_at (both null when there is no conversation on this number). In detail.code. Send an approved template with a Flow button instead. |
422 | recipient_language_unknown | translate: true, but the recipient's language is unknown. Pass target_language. In detail.code. |
422 | Validation error list, for example flow_cta longer than 30 characters. |
From the inbox
In a WhatsApp conversation, agents can pick any published flow and send it. Inside the 24-hour window it goes out as an interactive message; outside it, they choose a template with a Flow button. The answers appear in the conversation once the contact submits. The button text and body start in the agent's app language, and when the customer writes in another language the agent can translate the texts before sending (see Default text and translation). Inbox sends are recorded with sender_type: "inbox", API sends with sender_type: "api".
Dynamic flows cannot be sent from a number that also uses the WhatsApp Business app (Coexistence). The send is refused with dynamic_not_supported_on_coexistence. Static flows work on these numbers.
From an automation
The Send WhatsApp Flow node in Flows sends a WhatsApp Flow to the contact of the run, waits for the submission, and continues on a branch:
- completed: the answers are available as
{{vars.waflow.<output_key>.<field>}}. - timeout: the contact did not submit in time (default 24 hours, up to 72 hours).
- fallback: the flow could not be sent, for example outside the 24-hour window without a fallback template, or a dynamic flow on a WhatsApp Business app (Coexistence) number.
The node uses the same 24-hour window rule as the Send message step: any message the contact sent to that WhatsApp number in the last 24 hours opens it, including a newsletter keyword such as START that did not open a conversation. A flow started by a START opt-in can therefore send the WhatsApp Flow right away. Sending a flow from an automation does not open an inbox conversation for a pure newsletter sign-up.
See Send WhatsApp Flow node for the full configuration.
To react to submissions of flows sent anywhere (inbox, API, campaigns), use the whatsapp_flow.completed trigger.
Billing
WhatsApp Flows is in beta. During the beta, completed flows are free. AI-builder generations are billed in AI credits (see AI generation). Every flow you send counts as one message from your plan's message pool, like any other WhatsApp message. Additional charges per completed flow will apply once WhatsApp Flows becomes generally available; we will announce them in advance.
- Interactive flow message (inside the 24-hour window): one outbound WhatsApp message.
- Template with a Flow button (
mode: "template", or outside the window): one outbound template message. - Campaigns with a Flow-button template: one campaign message per recipient, from the same message pool.
- Send WhatsApp Flow node in an automation: one message, the same as an inbox or API send.
A flow counts once it is sent, delivered or read. Failed sends are not billed. The contact's submission arrives as an incoming message and is free. During the beta, the completion itself costs nothing.