# Migrate from Programmable Chat to Flex Conversations

## Overview

For Flex customers, the [Programmable Chat API](/docs/chat) has been replaced with [Flex Conversations](/docs/flex/conversations), the latest, enhanced architecture for Flex that uses the [Twilio Conversations API](/docs/conversations) and the [Interactions API](/docs/flex/developer/conversations/interactions-api). This platform is where we'll continue to add new functionality, capabilities, and channels.

Flex Conversations provides the following benefits compared to Programmable Chat:

* Richer orchestration primitives
* [Cross-channel messaging](/docs/flex/conversations)
* [Native email channel](/docs/flex/email)
* [Native messaging transfers](/docs/flex/admin-guide/setup/conversations/messaging-transfers)
* [Read receipts](/docs/flex/conversations)
* [Leave and pause tasks for all channels](/docs/flex/admin-guide/setup/conversations/leave-and-pause-for-conversations)

To help you migrate to Flex Conversations, this guide provides the steps that you need to take in Console, Studio, and TaskRouter. There's no impact on Twilio Functions. Because this migration will cause some Flex downtime, this guide also outlines steps to plan for downtime before you migrate.

This guide covers standard Flex setup and processes. It doesn't cover any backend modifications or Flex UI plugin customizations for [Programmable Chat](/docs/chat) APIs or SDKs. If you've customized these areas, you'll need to consider other factors that are not described in this guide. For more information, consult other resources related to your modifications and customizations, such as the [Conversations API](/docs/conversations), [Interactions API](/docs/flex/developer/conversations/interactions-api), and [Flex 2.0.x enhancements](/docs/flex/developer/ui/20-enhancements#messaging-channels).

To migrate to Flex Conversations, you must be using [Flex UI 2.0.0 or later](https://console.twilio.com/us1/develop/flex/settings/ui-versions).

## Plan for scheduled downtime before your migration

Before starting your migration, plan for some downtime with Flex messaging. The length of your downtime varies depending on the complexity of your migration, which increases with your level of customization. Typical downtime ranges from a few minutes to a few hours.

While it's possible to complete the migration with minimal downtime, this approach requires significant development efforts and is beyond the scope of this guide. For personalized help with migration, contact [Professional Services](https://www.twilio.com/en-us/professional-services).

We recommend following the [steps in this guide for scheduled downtime](/docs/flex/developer/conversations/programmable-chat-to-flex-conversations#handle-downtime). If you don't complete the downtime steps, agents and customers may have a disrupted experience:

* **Agents**: If agents are actively messaging customers, messages will suddenly stop. With SMS, messages will appear in an agent's chat window, but they won't be sent to the customer's device.
* **Customers**: If a customer is actively messaging a Flex agent or is in an interaction that's managed by a Studio flow, their interaction will be disrupted. Any reply they send triggers a new message with the agent through the new Conversations address, which restarts any connected Studio flows.

## Handle downtime

### Step 1: Prevent new SMS messages and create a downtime message for customers

To prevent new SMS channels during scheduled downtime, connect your Flex messaging phone numbers to a temporary Studio flow. In the flow, add a message that informs customers about service interruption.

1. [Create a temporary Studio flow](/docs/studio/user-guide/get-started#create-a-flow):
   1. Connect the **Incoming Message** [trigger](/docs/studio/user-guide/get-started#work-with-widgets) to a **Send Message** widget.
   2. Configure the widget to send a message about your system being temporarily down.
2. Update Twilio phone numbers so they connect to the new flow. See [Configure a Twilio Phone Number to connect to a Studio flow](/docs/studio/user-guide/get-started#configure-a-twilio-phone-number-to-connect-to-a-studio-flow).

**Note**: The temporary downtime message only applies to new inbound messages. Customers in active chats won't receive the message.

### Step 2: Prevent new Webchat messages

Remove the Webchat widget embedded on your website to prevent new webchats from being created during scheduled downtime.

We don't recommend creating a temporary downtime message with Webchat. While this approach is possible, it may result in unmonitored chats if customers reply to a downtime message.

If you're using both SMS and Webchat channels, be aware they have distinct downtime and migration processes. Webchat may require more development effort and time, since Webchat 2.x.x is not compatible with Conversations. We cover Webchat migration later in the guide, under [Step 5: Migrate to Webchat 3.x.x](/docs/flex/developer/conversations/programmable-chat-to-flex-conversations#step-5-migrate-to-webchat-3xx-optional).

### Step 3: Instruct agents to wrap up active tasks for Programmable Chat

As the downtime period begins, instruct agents to wrap up active tasks. Agents should inform customers their chat is ending because of scheduled downtime.

**Tip**: Rather than waiting for agents to complete their in-progress tasks, you can automatically close these tasks by [building a custom solution](/docs/flex/developer/conversations/programmable-chat-to-flex-conversations#automate-closing-programmable-chat-tasks).

### Step 4: Cancel pending tasks for Programmable Chat

There may be pending tasks in TaskRouter that haven't been assigned to a Flex agent. You can either manually cancel these tasks using Twilio Console or the [TaskRouter API](/docs/taskrouter/api/task), or allow TaskRouter to assign them to agents and let agents complete them. Make sure not to *delete* tasks.

**Note**: Canceling unassigned tasks results in an abrupt end for the customer. Letting agents complete tasks provides a better customer experience, but it will increase overall downtime.

### Step 5: End any Studio executions in progress

If you have [Studio executions](/docs/studio/rest-api/v2/execution) in progress, you can either wait for these to be processed into a task and then assigned and closed by a Flex agent, or you can manually close any [stuck Studio flow execution](https://help.twilio.com/articles/360019383714) caused by the migration.

## Review migration considerations

Familiarize yourself with the following considerations before you begin:

### Migrating phone numbers and Studio flows

Because each Conversations address must be connected to a Studio flow, you may need to migrate multiple phone numbers at once if they share the same flow.

We recommend migrating one Studio flow at a time—even if that means handling several numbers together. This approach lets you perform end-to-end testing and ensure functionality for a set of numbers before moving on to the next flow, which minimizes the service disruption if issues arise.

### Automate closing Programmable Chat tasks

Instead of waiting for an agent to manually wrap up Programmable Chat tasks, you can automate the process. Using Twilio's APIs, you can notify customers in open channels about the upcoming downtime and automatically close the agent's task. While this approach speeds up migration, it may interrupt the customer experience by ending conversations with customers abruptly. The steps you need to take depend on your configuration. For help, contact [Support](https://help.twilio.com/).

### Overlap of Programmable Chat and Flex Conversations

You can technically use both platforms at the same time, but you can't use the same phone number across both services. You need to disconnect the number from Programmable Chat before it becomes available to use with Conversations.

### Messaging history for Programmable Chat

Messaging history from Programmable Chat won't be available for agents in Flex unless you take additional measures, such as building a custom solution with your development team. If you need to retrieve chat history as a record, see [Migrating from Programmable Chat](/docs/conversations/migrating-chat-conversations).

## Start your migration

After you have prepared for downtime and reviewed considerations, you can start the migration process.

### Step 1: Map existing legacy addresses, Studio flows, and phone numbers

Prepare a detailed list of your current legacy addresses, Studio flows, and phone numbers and how they map to one another. This will prepare you to recreate the legacy addresses as new Conversation addresses later in the guide.

### Step 2: Migrate Studio flows

If you're using Console, migrate one Studio flow at a time. To migrate your existing flows, you need to change the **Trigger** from **Incoming Message** to **Incoming Conversation**. For more details, see [Create a Studio flow for Conversations](/docs/flex/admin-guide/setup/conversations/prerequisites#create-a-studio-flow-for-conversations).

Wherever you previously used **Incoming Message** trigger variables, like `{{trigger.message.ChannelSid}}`, you need to update these to match the new **Incoming Conversation** trigger format, like `{{trigger.conversation.ConversationSid}}`. For more details about the new variables, see [Incoming Conversation Trigger Variables](/docs/studio/widget-library/trigger-start#incoming-conversation-trigger-variables).

Some variables, like **Twilio Number** (previously `{{trigger.message.To}}`) and **From Number** (previously `{{trigger.message.From}}`), were available in Programmable Chat but are no longer available with Conversations.

### Step 3: Verify your Default Conversation Service in Console

Verify that your **Default Conversation Service** is set to a service using Flex.

1. In [Console](https://console.twilio.com/), go to **Conversations** > **Manage** > **Defaults**.
2. Under **Default Conversation Service**, confirm that you're using a service that connects with Flex Conversations. In most cases, this should say **Flex Chat Service** or **Flex Conversations Service**. **Flex Chat Service** uses the Conversations API service despite "Chat" in the name. If you're unsure if the service is correct, make sure the **Default Conversation Service** matches the `ISxxxx` identifier in the `chat_service_instance_sid` property of your [Flex configuration](/docs/flex/developer/config).
3. Under **Messaging Features**, ensure [**Handle Inbound Messages with Conversations**](/docs/conversations/inbound-autocreation#enabling-autocreation-through-the-twilio-console) is set to **Unlocked**.

**Troubleshooting tip**: If you have concerns or are unable to verify your Flex Configuration, run the Flex [System checkup](https://console.twilio.com/us1/develop/flex/resources/system-checkup). Ensure that **Conversation Service exists** and
**Conversation Service registered for Flex** show **Success**. If you have any concerns from running the Flex System checkup, contact [Support](https://help.twilio.com/).

### Step 4: Migrate addresses

In Console, delete the legacy address or number that corresponds to the Studio flow you migrated. Then, add it back in as a Conversations address. To do this:

1. Remove a legacy address:
   1. From [Console](https://console.twilio.com/), go to **Flex** > **Channel management** > **Messaging** > **Legacy Addresses**.
   2. Delete the address.
2. Under **Conversations Address**, click **Create new Address**, and create a new address for the legacy address that you deleted. For more information, see:
   * **SMS**: [Manage Conversations SMS addresses](/docs/flex/admin-guide/setup/conversations/manage-conversations-sms-addresses)
   * **WhatsApp**: [Manage Conversations WhatsApp addresses](/docs/flex/admin-guide/setup/conversations/manage-conversations-whatsapp-addresses)
   * **Webchat**: [Create a Webchat Conversations address](/docs/flex/admin-guide/setup/conversations/manage-conversations-chat-addresses#create-a-chat-address-via-flex-console)
   * **Email**: [Email in Flex for administrators](/docs/flex/admin-guide/setup/email)
   * **Facebook Messenger**: [Manage Conversations addresses for Facebook Messenger (public beta)](/docs/flex/admin-guide/setup/conversations/manage-conversations-fbmessenger-addresses).
     **Note**: With Conversations, the channel type property changes to `Messenger` instead of `Facebook`.
3. Repeat these steps until you've migrated each legacy address to a Conversations address.

### Step 5: Migrate to Webchat 3.x.x.

We recommend updating from Webchat 2.x.x to Webchat 3.x.x, as Webchat 2.x.x is no longer supported. Updating Webchat is a separate process that's covered in [Migrate to Webchat 3.x.x](/docs/flex/developer/conversations/webchat/migrate). Using Conversations is a prerequisite for Webchat 3.x.x. To minimize downtime, you can update to Webchat 3.x.x immediately after migrating to Conversations.

## After migration

### Disconnect your temporary Studio flow

After you've completed downtime and migration, disconnect your temporary Studio flow about service disruption.

## Additional resources

* [Migrating to Conversations from Programmable Chat](/docs/conversations/migrating-chat-conversations)
* [Migrate from Flex UI 1.x.x to 2.x.x](/docs/flex/developer/ui/migration-guide)