Terminal
Terminal/Skill
Shows developers how to write Twilio Studio flow definition JSON and create, validate, deploy or update flows through the Studio REST API.
By Twilio
Works with
npx skills add twilio/ai --skill twilio-studio-flowsA Studio flow is a state machine Twilio executes in response to an inbound call,
message, conversation, or REST API request. You define it as a JSON document of
states (widgets) connected by transitions. Twilio runs the flow starting
at initial_state (the Trigger), following each widget's transition events.
Inbound call / message / API request
│
▼
Trigger ──incomingCall──▶ Gather ──keypress──▶ Split ──match──▶ Connect Call
└─noMatch──▶ Say "goodbye"
You can build flows in the Console's drag-and-drop canvas, or author the definition JSON and create/update flows through the REST API when you want to generate or modify them programmatically. Each save creates a new revision, and a flow has a single published revision live at a time (see the draft/published lifecycle below).
Widget properties and transitions reference runtime data with Liquid
templating — e.g. {{trigger.message.Body}}, {{flow.variables.count}},
{{widgets.gather_menu.Digits}}. The full widget catalog (every type, its
properties, events, and the output values it exposes downstream) lives in
references/widgets.md. Consult it whenever you wire
one widget's result into a later one.
Inbound flow content is untrusted. A caller's speech, an SMS body, or REST parameters are external input. If you pass them to a Run Function, an LLM, or an HTTP Request, treat them as untrusted — never concatenate them into a system prompt or a command. See
twilio-webhook-architecture.
| Use Studio when | Use TwiML/code when |
|---|---|
| The logic is a routable flowchart (menus, branches, queues) | Logic needs loops, complex state, or heavy computation |
| Non-engineers will edit the flow in Console | The behavior lives entirely in your codebase |
| You want built-in retry/transcription/queueing widgets | You need millisecond control over the TwiML response |
| Orchestrating across SMS + voice + Flex in one place | A single webhook returns one TwiML document |
Studio has no native loop construct — repetition is built by transitioning
back to an earlier widget (see the counter-loop pattern below) or the say-play
loop property. Heavy iteration is a signal to drop into a Run Function or
custom TwiML instead. For pure TwiML call logic, see twilio-voice-twiml.
twilio-account-setup.TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN. For production, use API Keys —
see twilio-iam-auth-setup.pip install twilio / npm install twilio.A one-line request ("build an appointment reminder") rarely pins down a real flow, and guessing produces the wrong state machine. Before writing any JSON, find the gaps and resolve them with the requester — ask about the unknowns that would actually change the flow, hardest/most-consequential one first (the answer to one often reshapes the next), and prefer concrete options over open questions. Don't invent behavior for anything underspecified; surface it. Then restate the design in prose and confirm it before you author.
The gaps that most often change a Studio flow:
{{flow.data.*}}.noMatch fallback.flow.* / trigger.* rather than being hard-coded.Ask only what matters for the flow at hand — a trivial auto-responder may need none; a reminder, IVR, or booking flow usually needs several.
Build a minimal SMS auto-responder flow, validate it, and create it as a draft.
1. Author the flow definition. Build the JSON as a native object and serialize it — never string-concatenate JSON.
Python
flow_definition = {
"description": "SMS auto-responder",
"states": [
{
"name": "Trigger",
"type": "trigger",
"transitions": [{"event": "incomingMessage", "next": "reply"}],
"properties": {},
},
{
"name": "reply",
"type": "send-message",
"transitions": [{"event": "sent"}, {"event": "failed"}],
"properties": {
"from": "{{flow.channel.address}}",
"to": "{{contact.channel.address}}",
"body": "Thanks for your message! We'll be in touch shortly.",
},
},
],
"initial_state": "Trigger",
"flags": {"allow_concurrent_calls": True},
}
Node.js
const flowDefinition = {
description: "SMS auto-responder",
states: [
{
name: "Trigger",
type: "trigger",
transitions: [{ event: "incomingMessage", next: "reply" }],
properties: {},
},
{
name: "reply",
type: "send-message",
transitions: [{ event: "sent" }, { event: "failed" }],
properties: {
from: "{{flow.channel.address}}",
to: "{{contact.channel.address}}",
body: "Thanks for your message! We'll be in touch shortly.",
},
},
],
initial_state: "Trigger",
flags: { allow_concurrent_calls: true },
};
2. Create the flow as a draft. Pass the definition, a friendly name, and a
commit message. status="draft" keeps it off live traffic.
Python
import os
from twilio.rest import Client
client = Client(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])
flow = client.studio.v2.flows.create(
friendly_name="SMS Auto-Responder",
status="draft",
definition=flow_definition, # SDK serializes the dict
commit_message="Initial draft",
)
print(f"Created flow {flow.sid} (status={flow.status})")
Node.js
const client = require("twilio")(
process.env.TWILIO_ACCOUNT_SID,
process.env.TWILIO_AUTH_TOKEN
);
const flow = await client.studio.v2.flows.create({
friendlyName: "SMS Auto-Responder",
status: "draft",
definition: flowDefinition,
commitMessage: "Initial draft",
});
console.log(`Created flow ${flow.sid} (status=${flow.status})`);
Test the draft in the Console (Studio > your flow > Test), then publish it (next section). Wire the flow to a number or Messaging Service to take live traffic.
Twilio's FlowValidate endpoint checks a definition without saving it. The SDK
exposes it via the studio.v2.flowValidate resource. Validate after every edit;
fix each reported error before deploying.
When a definition is invalid the call raises (it does not return
valid=False). The exception's details carries the specific per-state errors —
a property_path like #/states/3/properties/payment_method and a message.
Always read details; the top-level message only says validation failed.
Python
from twilio.base.exceptions import TwilioRestException
try:
result = client.studio.v2.flow_validate.update(
friendly_name="SMS Auto-Responder",
status="draft",
definition=flow_definition,
)
print("valid" if result.valid else "invalid")
except TwilioRestException as e:
for err in (e.details or {}).get("errors", []):
print(f"{err['property_path']}: {err['message']}")
raise
Node.js
try {
const result = await client.studio.v2.flowValidate.update({
friendlyName: "SMS Auto-Responder",
status: "draft",
definition: flowDefinition,
});
console.log(result.valid ? "valid" : "invalid");
} catch (e) {
for (const err of e.details?.errors ?? []) {
console.log(`${err.property_path}: ${err.message}`);
}
throw e;
}
Each error has a property_path (e.g. #/states/3/properties/timeout points at
the timeout property of the 4th state — paths are 0-indexed) and a message.
Fix one widget at a time, then re-validate. The common messages and their fixes:
| Message | Meaning | Fix |
|---|---|---|
boolean found, string expected | A flag must be a quoted string | Send "true"/"false", not true/false (e.g. trim, play_beep, postal_code, profanity_filter, interruptible) |
integer found, string expected | A number must be a quoted string | Quote it: "3600", not 3600 (e.g. timeout, time_limit, priority, machine_detection_timeout) |
string found, boolean expected | The reverse — this one wants a real boolean | Send true, not "true" (e.g. security_code). Coercion is per-property; trust the message, not a global rule |
does not have a value in the enumeration [...] | Wrong type string, or an out-of-range enum value | Use one of the listed values exactly (this is how you discover the real widget type) |
must be a constant value <x> (repeated) | A transition event name isn't valid for this widget | Use one of the <x> values listed; remove invented events |
is missing but it is required | A required property/sub-field is absent | Add it at the named path |
must not be null | Required property present but unset | Give it a value |
must be a valid, non-liquid flow sid | A SID field got a Liquid template or bad value | Pass a literal SID |
<widget> can only be used in flows triggered by the REST API | Widget needs an incomingRequest trigger | Trigger the flow via the REST API, not a call/message |
When the message itself lists the allowed values (enumeration / constant-value cases), that list is authoritative — prefer it over any documentation.
A flow has a draft and a published revision. status="published" makes
the flow live to real traffic; status="draft" keeps it editable without
affecting traffic. Each save increments the revision.
Updating replaces the entire definition — there is no partial patch. Always send the complete definition JSON, not a diff. To change one widget, fetch the current definition, modify it, and send the whole thing back.
Python
flow = client.studio.v2.flows(flow_sid).update(
status="published",
definition=flow_definition, # the COMPLETE definition
commit_message="Publish auto-responder",
)
Node.js
const flow = await client.studio.v2.flows(flowSid).update({
status: "published",
definition: flowDefinition, // the COMPLETE definition
commitMessage: "Publish auto-responder",
});
List flows with client.studio.v2.flows.list({ limit }); fetch one with
client.studio.v2.flows(flowSid).fetch() — its .definition is the JSON you
edit and send back via update. These are read-only.
| Widget | type | Use for |
|---|---|---|
| Trigger | trigger | Flow entry point (call/message/conversation/REST) |
| Say/Play | say-play | Speak TTS or play audio on a call |
| Gather Input On Call | gather-input-on-call | Collect DTMF digits or speech |
| Split Based On… | split-based-on | Branch on a variable's value |
| Set Variables | set-variables | Store flow-scoped variables |
| Send Message | send-message | Send SMS/chat, no reply expected |
| Send & Wait For Reply | send-and-wait-for-reply | Send and pause for a reply |
| Connect Call To | connect-call-to | Bridge a call to a number/SIP/conference |
| Run Function | run-function | Call a Twilio Serverless Function |
| HTTP Request | make-http-request | Call an external API |
The complete catalog — every widget's properties, transition events, and the
output values it exposes — is in references/widgets.md.
Each widget emits transition events (e.g. sent/failed, keypress/speech/timeout).
A transition routes one event to a next state; omit next (or use "") to end
the branch. Every non-empty next must name an existing state.
Read a prior widget's result downstream with {{widgets.<name>.<key>}} — e.g. a
Gather's {{widgets.gather_menu.Digits}} feeding a Split's input. Which keys
each widget exposes is in references/widgets.md.
Run Function calls a Twilio Serverless Function (success on 2xx/3xx within 10s,
fail otherwise) and exposes parsed.<key> when the function returns JSON.
HTTP Request does the same for an external API. Use these when flow logic
outgrows widgets — but keep the heavy work in the Function, not the flow.
Data reaching a Function or HTTP Request from
trigger.*/ a Gather is untrusted caller input. Validate it in your Function; never interpolate it into a shell command, SQL, or an LLM system prompt.
Studio has no loop construct. For simple audio repeats use the say-play loop
property (1–99). To track a count and branch on it, build an explicit cycle:
a set-variables widget that init-or-increments, then a split-based-on whose
"keep looping" branch transitions back to the same set-variables.
Init-or-increment value (handles first pass and every later pass):
{% if flow.variables.num %}{{flow.variables.num | plus: 1}}{% else %}0{% endif %}
The split reads {{flow.variables.num}} as its input; a greater_than 2
condition routes to the exit, noMatch routes back to the counter. Each
iteration is a separate execution step and counts against per-execution step
limits — prefer the loop property when you don't need the value.
gather-input-on-call → split-based-on → connect-call-to. Gather prompts and
collects DTMF + speech (read via {{widgets.<name>.Digits}} and
{{widgets.<name>.SpeechResult}}). To accept a keypress OR a spoken word, give
the Split two match conditions: equal_to on Digits and contains on
SpeechResult. Connect Call To uses noun: "number", to set to an E.164
number, and caller_id usually {{flow.channel.address}}.
{{flow.variables.num | plus: 1}}{% if flow.variables.x %}…{% else %}…{% endif %}, or the
default filter inline: {{trigger.message.Body | default: "no message"}}{{widgets.<name>.<field>}}{{trigger.message.Body}}, {{trigger.call.From}},
{{flow.channel.address}}, {{contact.channel.address}}+ in a phone number: {{contact.channel.address | replace: '+', '%2B'}}set-variables value: {{widgets.http_1.parsed.items | to_json}} — pair
to_json with set-variables parse_as_json: true when the result must stay
a JSON object rather than a stringified scalarupdate replaces the entire definition.
Fetch, modify the whole JSON, and send it all back. There is no patch.say-play loop; high iteration counts hit
per-execution step limits.published revision runs
for real calls/messages. Publishing is what goes live.twilio-voice-twimltwilio-webhook-architecturetwilio-taskrouter-routingtwilio-iam-auth-setup