# Resume Conversation widget

The **Resume Conversation** widget connects an outbound Studio flow to an existing Twilio Conversation and assigns that Conversation as the default channel for the flow execution.

With this widget, you can use outbound Studio flows to resume two-way messaging on a Conversation that was created outside of Studio, such as through the Conversations API or another system. The widget fetches the existing Conversation, lists its participants, and configures Studio to continue the flow when inbound messages are received.

Only one Conversation can exist per execution.

## How the Resume Conversation widget works

The **Resume Conversation** widget runs when it is reached in a Studio flow that was triggered by the REST API trigger.

When the widget runs, Studio performs the following actions:

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 resume a Conversation and transitions to **Failed**.
2. Fetches the existing Conversation using the provided Conversation SID and Conversation Service SID.
3. Lists the current participants on the Conversation.
4. Registers an `onMessageAdded` webhook so that inbound messages resume the Studio execution.
5. Stores Conversation metadata in the 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`.

When the execution ends, Studio removes the `onMessageAdded` webhook. If **Close Conversation on Execution End** is enabled, Studio also closes the Conversation.

If the execution is handed off, such as by using the **Send to Flex** widget, Studio blocks further messages from the flow and removes the [`onMessageAdded` webhook](/docs/conversations/conversations-webhooks#webhook-action-triggers).

## Configure Resume Conversation properties

### Conversation properties

The following properties identify the existing Conversation to resume. The **Conversation SID** and **Conversation Service SID** fields support [Liquid template variables](/docs/studio/user-guide/liquid-template-language).

| Property                                | Description                                                                                                                          |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Conversation SID**                    | The SID of the existing Conversation to resume. Must reference a valid, active Conversation.                                         |
| **Conversation Service SID**            | The SID of the Conversation Service that owns the Conversation.                                                                      |
| **Close Conversation on Execution End** | When enabled, Studio closes the Conversation after the execution ends. When disabled (the default), the Conversation remains active. |

## Transitions

The **Resume Conversation** widget uses the following transitions:

| Transition  | Description                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------- |
| **Resumed** | The Conversation was successfully resumed and the webhook was registered.                      |
| **Failed**  | The widget could not resume 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.
* The Conversation can't be fetched (for example, the SID doesn't exist or the service is incorrect).
* Studio can't list the participants on the Conversation.
* Studio can't register the `onMessageAdded` webhook.

## Widget variables

When the widget succeeds, the following variables are available for use in downstream widgets using Liquid template syntax:

### Conversation

| Name                  | Liquid Template Language                                        |
| --------------------- | --------------------------------------------------------------- |
| SID                   | `{{widgets.MY_WIDGET_NAME.conversation.sid}}`                   |
| State                 | `{{widgets.MY_WIDGET_NAME.conversation.state}}`                 |
| Friendly Name         | `{{widgets.MY_WIDGET_NAME.conversation.friendly_name}}`         |
| Unique Name           | `{{widgets.MY_WIDGET_NAME.conversation.unique_name}}`           |
| Attributes            | `{{widgets.MY_WIDGET_NAME.conversation.attributes}}`            |
| Chat Service SID      | `{{widgets.MY_WIDGET_NAME.conversation.chat_service_sid}}`      |
| Messaging Service SID | `{{widgets.MY_WIDGET_NAME.conversation.messaging_service_sid}}` |
| Date Created          | `{{widgets.MY_WIDGET_NAME.conversation.date_created}}`          |
| Date Updated          | `{{widgets.MY_WIDGET_NAME.conversation.date_updated}}`          |

### Participants

Participants are available as a list under `widgets.MY_WIDGET_NAME.conversation.participants`. Each participant contains:

| Name                            | Liquid Template Language                                                                  |
| ------------------------------- | ----------------------------------------------------------------------------------------- |
| SID                             | `{{widgets.MY_WIDGET_NAME.conversation.participants[0].sid}}`                             |
| Identity                        | `{{widgets.MY_WIDGET_NAME.conversation.participants[0].identity}}`                        |
| Attributes                      | `{{widgets.MY_WIDGET_NAME.conversation.participants[0].attributes}}`                      |
| Role SID                        | `{{widgets.MY_WIDGET_NAME.conversation.participants[0].role_sid}}`                        |
| Messaging Binding Address       | `{{widgets.MY_WIDGET_NAME.conversation.participants[0].messaging_binding.address}}`       |
| Messaging Binding Proxy Address | `{{widgets.MY_WIDGET_NAME.conversation.participants[0].messaging_binding.proxy_address}}` |

### Other variables

| Name                                | Liquid Template Language                                    |
| ----------------------------------- | ----------------------------------------------------------- |
| Webhook SID                         | `{{widgets.MY_WIDGET_NAME.webhook_sid}}`                    |
| Close Conversation on Execution End | `{{widgets.MY_WIDGET_NAME.close_channel_on_execution_end}}` |

## 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 resumed within a subflow, the channel context is propagated back to the parent flow.