# 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.

## How the Start Conversation widget works

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:

1. 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**.
2. Creates a new Conversation with a single participant.
3. Registers an `onMessageAdded` webhook so that inbound messages resume the Studio execution.
4. 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](/docs/conversations/conversations-webhooks#webhook-action-triggers).

## Configure Start Conversation properties

### Conversation properties

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](/docs/conversations/api/conversation-resource):

| 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](/docs/conversations/api/user-resource).

### Participant configuration

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](/docs/conversations/api/conversation-participant-resource):

#### Chat participant

| 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                  |

#### Messaging participant (SMS or WhatsApp)

| 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                         |

## Transitions

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 `onMessageAdded` webhook.

## Execution context

When the widget succeeds, Conversation data is stored in execution context under `flow.channel`.

### Channel context structure

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.