Migrate from Programmable Chat to Flex Conversations

For Flex customers, the Programmable Chat API has been replaced with Flex Conversations, the latest, enhanced architecture for Flex that uses the Twilio Conversations API and the 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
• Native email channel
• Native messaging transfers
• Read receipts
• Leave and pause tasks for all channels

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 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, Interactions API, and Flex 2.0.x enhancements.

To migrate to Flex Conversations, you must be using Flex UI 2.0.0 or later.

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.

We recommend following the steps in this guide for scheduled 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.

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:
   1. Connect the Incoming Message trigger 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.

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

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.

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.

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

If you have Studio executions 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 caused by the migration.

Familiarize yourself with the following considerations before you begin:

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.

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.

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

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

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.

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.

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.

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.

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

1. In Console, 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.
3. Under Messaging Features, ensure Handle Inbound Messages with Conversations is set to Unlocked.

Troubleshooting tip: If you have concerns or are unable to verify your Flex Configuration, run the Flex 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.

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, 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
   • WhatsApp: Manage Conversations WhatsApp addresses
   • Webchat: Create a Webchat Conversations address
   • Email: Email in Flex for administrators
   • Facebook Messenger: Manage Conversations addresses for Facebook Messenger (public beta). 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.

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. 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 you've completed downtime and migration, disconnect your temporary Studio flow about service disruption.

• Migrating to Conversations from Programmable Chat
• Migrate from Flex UI 1.x.x to 2.x.x