Menu

Manage Flex Flows

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 or the Flex Flow API.

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.

TaskRouter Task

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

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

Channel Janitor

When enabled with the API or in the Twilio Console, 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.

Long-Lived Channels

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.

Next Steps

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 by visiting Twilio's Community Forums or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

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

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more