Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Manage Flex Flows



This guide is for Flex UI 1.x.x and channels that use Programmable Chat and Proxy. If you are using Flex UI 2.x.x or you are starting out, we recommend that you build with Flex Conversations.

A Flex Flow is the logic linking a messaging identity, like a Web Chat name or an 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.

Flex Flows can be managed via the UI in Twilio Console(link takes you to an external page) or the Flex Flow API.

Integration Types

integration-types page anchor

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)

studio-default page anchor

Incoming messages are routed to a specific configured Twilio Studio flow. 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. For Flex Flows created via the API, Studio uses the channel type to populate the Task attributes for the current Task and render them appropriately in the Flex UI. For example, if the channelType is facebook, whatsapp, or line, the Send to Flex widget will set the Task Channel to "Programmable Chat".

For more info, see Configure pre-agent workflow with Studio and Core Concepts: Studio Flows.

To bypass Studio and immediately create a TaskRouter Task for an incoming message, you need to set a Flex Flow's integrationType to Task (i.e., "IntegrationType=task" in an API curl request). When making your Flex Flow request via the API, you also need to set the following properties:

  • Integration.WorkspaceSid and Integration.WorkflowSid to assign the new TaskRouter Task to a Workspace and a Workflow in that workspace. If you update the Flex Flow using the UI, the Workspace SID is set implicitly.
  • Integration.Channel property to define the appropriate Task Channel for the TaskRouter Task that will be created. Defining the Integration.Channel is required for the Flex UI to show messaging conversations properly. If not set, the Tasks will be visible but not rendered as chats. Set it to either the SID or the unique name of the Task Channel (default Task Channel is "default").

    • For SMS, set to "sms" .
    • For WebChat and all other messaging channels, set to "chat" .

For a full list of properties and code samples in different programming languages, see the Flex Flow Resource.

External Webhook/HTTP Request Widget

external-webhookhttp-request-widget page anchor

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

chat-channels-and-proxy-sessions page anchor

When a conversation ends after an 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 Proxy Session.
  2. Chat adds it to the existing Chat Channel and it is sent to be displayed in the agent's UI.
  3. The Task associated with the original conversation has been deleted, though. 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.

When enabled with the API or in the Twilio Console(link takes you to an external page), the Channel Janitor listens to the following TaskRouter events:

  • task.canceled
  • task.wrapup
  • task.completed
  • task.system-deleted

If any of these events come in and Channel Janitor is enabled, then it will clean up the Chat Channel and the Proxy Session, keeping the state in sync with TaskRouter.



Notice that task.deleted is not included into the list of events triggering automatic cleanup. Unfortunately, this event cannot be cleaned up after, as some Flex customizations rely on sending this in scenarios where the Chat Channel needs to be preserved.

If this is causing an issue on your Flex account, please use System Checkup to clean up the stale Chat Channels and Proxy Sessions.

Channel 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 Channel Janitor when you create a new Flex Flow.

When enabled with the API, long-lived Chat Channels allow your customers' message history to persist between multiple interactions; for example, a customer could chat with an agent, and a day later return and chat with another agent, who will be able to see the message history. You can use long-lived channels and Channel Janitor together. Channel Janitor will clear out Proxy Sessions as normal, but leave Chat Channels intact. When a new message comes in, Flex's messaging orchestration will fetch the existing Chat Channel and use it for the interaction.

Using long-lived Chat 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 Chat Channels.

Rate this page: