Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Manage Flex Flows

A Flex Flow is the logic linking a messaging identities, like a Web Chat name or SMS-based phone number, to Flex. Flex Flows can also be referred to as message handlers, because they describe the way a contact identity should handle inbound messages. When you're configuring your contact center, each phone number, chat channel, or other messaging channel contact identity will need a corresponding Flex Flow.

This page discusses some technical considerations for configuring your Flex Flows. To learn more about the Flex Flows API, check out the Flex Flow Resource Documentation.

Integration Types

When a message comes into your Flex Flow, Twilio needs to know how to handle it. You can configure your Flex Flow with a few options:

Studio (default)

Incoming messages are routed to a specific configured Twilio Studio flow. Studio allows you to build chatbots, IVRs and similar functionality. Studio can connect to Twilio Functions or make HTTP Requests to 3rd party services for additional functionality. Studio flows are generally invoked before the task is routed to an Agent. Tasks are passed to Agents via Studio’s Send to Flex widget, which creates a task and removes Studio from the engagement.


Incoming messages immediately generate a Task in TaskRouter and get routed to an Agent. No additional orchestration or chat bot flows are needed.

External Webhook/HTTP Request Widget

Incoming messages are routed to a Webhook of your choosing. Twilio will send incoming messages to you, and you can use the information and metadata to create a custom integration with Flex. For example, you could use the incoming message payload to power an in-house bot flow.

If you are planning to use a different integration type for your inbound and your outbound messages (e.g., inbound messages will be routed through Studio but Outbound messages create a task that's auto-assigned to the agent) then create two Flex Flow Message Handlers.

By default, your project has Flex Flows for inbound SMS and inbound Web chat. If the default Flex Flows work for you, then you don't need to worry about configuring new ones!

Your newly created Outbound handler can be set to enabled=false. Outbound channels will always be created with the Handler specified by the developer. Inbound flows, however, must adhere to strict non-conflict checks across contact identity and integration type.

Chat Channels and Proxy Sessions

When the conversation then ends after the agent presses the End Chat button, two things happen:

  1. The Chat channel is marked as inactive
  2. The Proxy session is deleted

The Flex UI triggers these actions and needs to be open for deletion to occur.

Occasionally, the agent closes the Flex UI while there’s still an active Task. If the Task stays active for 24 hours, it will eventually time out and be deleted.

This removes the Task from the list of agent's tasks. However, because the UI was closed when this happened, it couldn't trigger the two cleanup actions, and both the Proxy session and the Chat channel persist.

  1. This becomes an issue if the same customer writes in again:
    The Proxy session for that phone number is still active, so Proxy adds this message to the existing session
  2. Chat adds it to the existing channel and it is sent to be displayed in the agent's UI.
  3. The Task associated with the original conversation was deleted, though.
  4. Therefore, there is no visual representation of it in the agent's UI. The message isn't shown anywhere and it appears to be "lost".

To solve this scenario, you’ll want to use the Flex Channel Janitor.

The Janitor

When enabled with the API or in the Twilio Console, the Channel Janitor listens to TaskRouter events (e.g., task.canceled, task.deleted, or task.system-deleted). If those events come in & the channel janitor is live, then the janitor will clean up the chat channel and Proxy session, keeping them in sync with TaskRouter.

The janitor marks the chat channel as inactive so that it is ignored for future conversations. You can still access the message history. The proxy session, however, will be completely deleted.

If you’re managing your own messaging orchestration, there’s no need for you to use the channel janitor when you create a new Flex flow.

Long-Lived Channels

When enabled with the API, long-lived channels allow your customers' message history to persist between multiple interactions; for example, a customer could speak with an agent, and then a day later speak with another agent who can scan the channel and see the message history. You can use long-lived channels and the channel janitor together. The channel janitor will clear out Proxy sessions as normal, but leave chat channels alone. When a new communication comes in, Flex's messaging orchestration will fetch the existing chat channel and use it for the interaction.

Using long-lived channels, while helpful for the agent experience, could present problems with security and performance at scale. Learn more about scaling and securing a chat application to learn more about useful considerations for maintaining long-lived channels.

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.