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

Send to Flex Widget

Studio uses Widgets to represent various parts of Twilio's functionality that can then be stitched together in your Studio Flow to build out robust applications that require no coding on your part.



New to Twilio Studio? Check out our Getting Started Guide!

Send to Flex is a Studio widget that can be used for transferring incoming calls, messages, or conversations to Flex.


The Send To Flex widget is a Studio widget that transfers a call, message, or conversation to Flex.

For the incoming Call trigger, Send to Flex will enqueue the Voice and the caller will hear hold music while waiting for an agent to respond.

For the incoming Message trigger, Messages are transferred to Flex as new tasks for assignment to an agent. The widget requires a Workflow and a Task Channel.

In Flex Conversations (which requires Flex UI 2.0), a new Trigger widget, Incoming Conversation, has been added. In this case, Send to Flex will create a new Interaction using the /Interactions endpoint which then creates new tasks for assignment to a worker.



If you are using Flex Conversations, remember to handle certain terminal TaskRouter events according to you application's needs, as conversations may stay orphaned with an open state.

See Conversations Best Practices for details.

Out-of-the-box Studio Flows for Flex

out-of-the-box-studio-flows-for-flex page anchor

While you can use the Send to Flex Widget from any Studio Flow you build, Twilio Flex accounts come enabled with three Studio Flows out of the box. These Flows use the Send to Flex Widget with the following default attributes:

Voice IVR Flow

voice-ivr-flow page anchor

{ "type": "inbound", "name": "{{}}" }

Messaging and Chat Flows

messaging-and-chat-flows page anchor

For legacy SMS and Webchat addresses, the following default attributes are set on the Send to Flex widget for incoming messages:

"name": "{{trigger.message.ChannelAttributes.from}}",
"channelType": "{{trigger.message.ChannelAttributes.channel_type}}",
"channelSid": "{{trigger.message.ChannelSid}}"

For SMS, WhatsApp, and Chat Conversations, SendToFlex widget adds channelType, customerAddress, from, name, and customerName when it creates the interaction. These are all set to the phone number of the sender (E.164 format for SMS and whatsapp:E.164 for WhatsApp numbers).

Furthermore, the default Chat address's Studio flow adds the following attribute:

{"from": "{{trigger.conversation.ChannelAttributes.pre_engagement_data.friendlyName}}"}

This pre_engagement_data.friendlyName is what the demo Chat app sends.

After creating your Flex instance, you will be able to find these default Studio Flows in the Studio section of the Twilio Console(link takes you to an external page).

Required configuration for Send to Flex

required-configuration-for-send-to-flex page anchor

When working with the Send to Flex Widget, you must select both a Workflow and a Channel so that your Studio Flow can properly route the inbound request to your Flex instance.

WorkflowThe name of the TaskRouter Workflow you want to assign to your Studio Flow (the SID of your selected Workflow is reflected on the widget itself)Assign to Anyone
ChannelThe Task Channel used by your Studio Flow when forwarding to your Flex InstanceProgrammable Chat

With these two pieces of information, the Send to Flex Widget will be able to enqueue the call and play hold music while waiting for a matched Flex Worker to accept the task, or transfer a message to Flex as a new task for worker assignment.

Optional configuration for Send to Flex

optional-configuration-for-send-to-flex page anchor

The Send to Flex Widget also accepts a number of configuration options that you can use to customize task priority, hold music, and other specifics for this transfer:

PriorityThe priority of this task in the TaskQueue. Tasks with a higher priority are assigned before older tasks with a lower priority - 0 is the highest priority.0
TimeoutThe amount of time in seconds that the task is allowed to live, with a maximum value of two weeks (1209600 seconds).3600 (1 hour)
AttributesJSON representing the Task attributes (maximum 1024 characters). See below for more details.Default values shown above
URL methodHTTP method to be used when requesting the Hold Music TwiML URL - GET or POST.None
Hold music TwiML URLThe URL for custom hold music while the customer waits in the queue.If no URL is specified, Flex's default hold music will play

Considerations for JSON attributes

considerations-for-json-attributes page anchor

When working with the JSON for custom attributes in the Send to Flex widget, make sure to consider the Flex Insights Data Model. Flex Insights is opinionated about where you put metadata about the Task (conversation) and customer. For a list of known Conversations attributes consumed by Flex Insights and/or the Flex UI, see Task Attributes on the Interactions API overview.

How to pass objects as an attribute in Send to Flex Widget

how-to-pass-objects-as-an-attribute-in-send-to-flex-widget page anchor

If you want to pass an object — for instance, data that you retrieved via a function — as an attribute value in the Attributes configuration, you can use the to_json Liquid Template Filter like this:

"customer_attributes": {{widgets.CustomerFunction.parsed | to_json}}

Note that for incoming Message and Conversation triggers, attributes set on the message are treated as string and cannot be parsed to JSON. Only attributes set on the Channel /Conversation, ChannelAttributes, data are parsed as JSON by default.

Send to Flex Transitions

send-to-flex-transitions page anchor

These events trigger transitions from the Send to Flex Widget to another Widget in your Flow. For more information on working with Studio Transitions, see the Getting Started Guide.

Task createdFor Voice calls, transition is triggered when the Enqueue action URL is requested. For Messages, transition is triggered as soon as the TaskRouter Task is created. For Conversations, the transition is triggered when an Interaction and a corresponding TaskRouter task are created.
Failed to create taskFor Voice calls, transition is triggered if enqueuing of the call fails. For Messages and Conversations, transition is triggered immediately when TaskRouter returns an error for Task creation.
Call failedOnly applies to Voice calls. Transition is triggered if QueueResult is "system-error".

When the Send to Flex Widget executes, it will have stored the following variables for use throughout your Studio Flow (where MY_WIDGET_NAME is the name of your actual widget). For more information on working with variables in Studio, see this guide.

Find definitions and examples for these variables at the Task Resource page.

NameLiquid Template Language
Task SID{{widgets.MY_WIDGET_NAME.TaskSid}}

Example: Studio IVR with Send to Flex

example-studio-ivr-with-send-to-flex page anchor

This example Studio Flow takes an incoming call and asks the caller if they'd like information (business hours or location), or to talk to a customer support representative. If the caller opts to speak to an agent, Send to Flex handles passing off the call to Flex.

An Interactive Voice Response Studio Flow. The starting trigger is an incoming call, then the caller is prompted to select 1, 2, or 3: if they select 1, the Send to Flex Widget executes and forwards the call.

Want to further explore customizing your Studio Flow with the Send to Flex Widget? Follow along with these guides to see Studio and Flex in action:

We can't wait to see what you build!

Rate this page: