Start Conversation widget
The Start Conversation widget creates a new Twilio Conversation during an outbound Studio flow execution (flows that are triggered with the REST API) and assigns it as the default channel for that outbound flow.
With this widget, you can use outbound Studio flows to initiate a two-way Twilio Conversation without requiring custom code or direct API calls. The widget creates a Conversation with a single participant and configures Studio to continue the flow when inbound messages are received.
You can only create one Conversation per execution.
The Start Conversation widget executes when it's reached in a Studio flow that was triggered using the REST API trigger.
When the widget runs, Studio:
- Checks whether a Conversation already exists for the execution. If the execution already has an active communication channel, such as an inbound Conversation channel, the widget doesn't create a new Conversation and transitions to Failed.
- Creates a new Conversation with a single participant.
- Registers an
onMessageAddedwebhook so that inbound messages resume the Studio execution. - Stores Conversation metadata in an execution context for use by downstream widgets.
Downstream Messaging widgets automatically send messages to the active Conversation. Messaging widgets resolve the Conversation from flow.channel.sid.
Conversations created by this widget remain active while the Studio execution is active. When the execution ends, Studio removes the onMessageAdded webhook.
If the execution is handed off, such as by using the Send to Flex widget, Studio blocks further messages from the flow and disconnects the onMessageAdded webhook.
The following properties configure the Conversation resource created by this widget. These fields map directly to the Twilio Conversations API Conversation resource.
For detailed behavior and constraints, see the Twilio Conversations API documentation:
| Property | Description |
|---|---|
| Conversation Service SID | The SID of the Conversation service used to create the Conversation. Defaults to the account's default Conversation service. |
| Messaging Service SID (optional) | The Messaging service associated with this Conversation. |
| Unique Name (optional) | An application-defined unique identifier for the Conversation. |
| Friendly Name (optional) | A human-readable name for the Conversation. Limited to 256 characters. |
| Attributes (optional) | A JSON object containing custom metadata stored on the Conversation. |
| Timers.Inactive (optional) | ISO-8601 duration after which the Conversation becomes inactive. Minimum value is 1 minute. |
| Timers.Closed (optional) | ISO-8601 duration after which the Conversation is closed. Minimum value is 10 minutes. |
| Email Binding - Address (optional) | Default email address used for outbound email messages in this Conversation. |
| Email Binding - Name (optional) | Default display name used for outbound email messages in this Conversation. |
The Unique Name and Friendly Name fields don't allow reserved characters as defined by the Conversations API.
The Start Conversation widget creates the Conversation with a single participant. The participant configuration determines how the user is reached. Group MMS is not supported.
Participant fields map to the Twilio Conversations API Participant resource:
| Property | Description |
|---|---|
| Identity | Unique identifier for the participant when using a Conversations SDK |
| Attributes (optional) | JSON metadata associated with the participant |
| Role SID (optional) | Conversation-level role assigned to the participant |
| Property | Description |
|---|---|
| Messaging Binding - Address | The participant's device address, such as a phone number or WhatsApp number |
| Messaging Binding - Proxy Address | The Twilio phone number or WhatsApp sender used for the Conversation |
| Attributes (optional) | JSON metadata associated with the participant |
| Role SID (optional) | Conversation-level role assigned to the participant |
The Start Conversation widget uses the following transitions:
| Transition | Description |
|---|---|
| Created | The Conversation was successfully created. |
| Failed | The widget could not create the Conversation or couldn't run in the current execution context. |
The widget transitions to Failed if:
- The flow wasn't triggered with the REST API.
- A Conversation already exists for the execution.
- Studio can't create the Conversation.
- Studio can't create the participant.
- Studio can't register the
onMessageAddedwebhook.
When the widget succeeds, Conversation data is stored in execution context under flow.channel.
This channel context is automatically available to downstream widgets, including Send Message and Send and Wait for Reply.
Only one Conversation can exist per execution. If a Conversation is created within a subflow, the channel context is propagated back to the parent flow.