AI Generation
Describe the form you need in plain language, and SendSeven's AI builder writes a complete, valid builder doc for you: screens, components, field mappings and texts in your language. You can then refine single screens or components with an instruction.
AI generation needs the Professional plan or higher, and AI features must be turned on for the workspace. On plans with dynamic flows (Scale and higher), the AI may build dynamic flows; on other plans it builds static flows only.
| Method | Endpoint | Purpose |
|---|---|---|
POST | /whatsapp-flows/ai/estimate | How many AI credits a generation costs. |
POST | /whatsapp-flows/ai/generate | Start a generation job. |
POST | /whatsapp-flows/ai/refine | Start a job that rewrites one screen or component. |
GET | /whatsapp-flows/ai/jobs/{job_id} | Poll a job. |
All four need the scope whatsapp_flows:write.
The AI endpoints do not save anything. They return a builder doc; you save it with the normal create or versions endpoints.
Cost: AI credits
WhatsApp Flows is in beta. During the beta, completed flows are free. 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.
When billable is true, generations and refinements are billed in AI credits. A run is charged by the AI work it needs, so there is no fixed price per run: the estimate tells you what a generation typically uses. Failed or cancelled AI runs are not charged. The charge appears under AI usage in Settings > Usage. Check the estimate before you start:
curl -X POST https://api.sendseven.com/api/v1/whatsapp-flows/ai/estimate \
-H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
-H "Content-Type: application/json" \
-d '{}'
{
"dynamic_allowed": true,
"usage_billed": true,
"charged_on": "usage",
"credits": 24,
"credits_p50": 23.6,
"credits_p90": 31.4,
"price_euros": null,
"billable": true,
"refine_credits": null,
"max_repair_rounds": 3
}
| Field | Meaning |
|---|---|
usage_billed | true: runs are charged by the AI work they need, and credits is an estimate, not a fixed price. |
credits | Typical AI credits of one generation (credits_p50, rounded). null when no estimate is available. |
credits_p50 / credits_p90 | Typical credits of a generation / what a large generation may reach. |
price_euros | null (no fixed price per run). |
refine_credits | null (a refinement is charged by usage like a generation). |
billable | Whether generations are charged at all. |
charged_on | usage: charged by the AI work of the run. |
dynamic_allowed | Whether the AI may build dynamic flows on your plan. |
max_repair_rounds | How often the AI may fix its own validation errors within one job. |
Always use the estimate: the numbers depend on the AI level your workspace uses for the WhatsApp Flows builder.
Generate
Generations take about one to three minutes, so they run as jobs. Start one:
curl -X POST https://api.sendseven.com/api/v1/whatsapp-flows/ai/generate \
-H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
-H "Content-Type: application/json" \
-d '{
"description": "Rückrufformular für ein Autohaus: Name, Telefon-Zeitfenster (vormittags/nachmittags/abends), Anliegen (Kauf, Werkstatt, Leasing) und eine Newsletter-Einwilligung.",
"language": "de",
"flow_name": "Rückruf Autohaus",
"request_id": "crm-req-20261003-0042"
}'
| Field | Notes |
|---|---|
description | Required, 5–4000 characters. What the form should do. |
language | BCP-47 code of the texts. Defaults to the workspace language. |
flow_name | Optional name, up to 200 characters. |
channel_id | Optional WhatsApp channel the flow is for. |
request_id | Optional idempotency key (8–64 characters: letters, digits, _ . : -). A retry with the same key returns the same job, never a second run or charge. |
Response 202:
{
"job_id": "job_6f1e…",
"kind": "generate",
"status": "queued",
"stage": null,
"repair_round": 0,
"result": null,
"error": null,
"request_id": "crm-req-20261003-0042",
"created_at": "2026-10-03T09:00:00Z",
"updated_at": "2026-10-03T09:00:00Z"
}
Poll the job
curl https://api.sendseven.com/api/v1/whatsapp-flows/ai/jobs/job_6f1e… \
-H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00"
Poll every few seconds. status goes queued → running → succeeded or failed. While running, stage is generating, repairing or validating. Jobs are kept for 24 hours.
{
"job_id": "job_6f1e…",
"kind": "generate",
"status": "succeeded",
"repair_round": 1,
"result": {
"builder_doc": { "schema_version": 1, "meta": { "name": "Rückruf Autohaus", "kind": "static", "language": "de" }, "screens": [ … ] },
"issues": [],
"valid": true,
"compiled_preview": { "version": "7.3", "screens": [ … ] },
"credits_used": 0,
"model_used": "…",
"repair_rounds": 1,
"generation_id": "gen_2b7c…",
"language": "de",
"fallback_used": false
},
"error": null,
"usage_billed": true,
"credits_charged": 21.734
}
valid: falsemeans the doc still has errors (listed inissues). Fix it yourself or refine it.error.codeon a failed job is one ofai_unavailable,ai_error,invalid_request,interrupted,cancelled,not_found.usage_billedandcredits_chargedtell you what the job charged. Whenusage_billedistrue,credits_chargedholds the AI credits of a completed job (0for a free trial run). Failed or cancelled AI runs are not charged, so a failed or cancelled job reports0. It isnullwhile the job runs or when the charge is not known yet; poll again. Readcredits_charged, notresult.credits_used, for the amount.
Save the result
Create a flow from the result and pass the generation id, so the version is marked as AI-generated:
curl -X POST https://api.sendseven.com/api/v1/whatsapp-flows \
-H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
-H "Content-Type: application/json" \
-d '{
"name": "Rückruf Autohaus",
"origin": "ai",
"ai_generation_id": "gen_2b7c…",
"builder_doc": { … }
}'
origin: "ai" requires a builder_doc (422 invalid_origin). From here on, the flow is a normal flow: review it, then publish it.
Refine
Rewrite one screen, or one component of a screen, while the rest of the doc stays unchanged:
curl -X POST https://api.sendseven.com/api/v1/whatsapp-flows/ai/refine \
-H "Authorization: Bearer s7_api_a1b2c3d4e5f6789012345678abcdef00" \
-H "Content-Type: application/json" \
-d '{
"builder_doc": { … },
"instruction": "Frage zusätzlich nach dem Fahrzeugmodell als Dropdown.",
"target": { "screen_id": "ANLIEGEN" },
"language": "de"
}'
| Field | Notes |
|---|---|
builder_doc | The current doc. |
instruction | 3–2000 characters. |
target.screen_id | The screen to rewrite. |
target.component_index | Optional (0–200). Rewrites only this component. Omit it to rewrite the whole screen. |
language, channel_id, request_id | As for generate. |
A target that does not exist is rejected at once with 422. Otherwise the response is a job (202); poll it like a generation.
Errors
AI errors use the same {code, message} shape as the rest of the WhatsApp Flows API. For older clients, error repeats code:
{ "detail": { "code": "ai_disabled", "error": "ai_disabled", "message": "AI features are turned off for this workspace." } }
| Status | code | Cause |
|---|---|---|
403 | ai_disabled | AI features are turned off in the workspace settings. |
403 | feature_disabled | The plan does not include AI features (Professional and higher) or WhatsApp Flows. feature names the missing feature. This error has no error or message key. |
402 | trial_ai_generation_limit_reached | Free trial only: the 20 free AI builds are used up and the remaining trial AI credits don't cover another build. Returned by generate and refine before the job starts, with kind: "whatsapp_flow", limit, used, credits_required, credits_remaining and upgrade_url. A failed or cancelled build costs nothing. See Free trial limits. |
422 | invalid_request | For example an unknown refine target. |
429 | rate_limit_exceeded | Too many generate/refine calls; the default limit is 60 per hour per workspace. See Retry-After and retry_after. |
502 | ai_error | The AI builder could not create a flow. Try again. |
503 | ai_unavailable | The AI builder is busy. Retry after the Retry-After seconds. |
404 | job_not_found | Unknown job, or a job of another workspace. |