Flex Messaging FAQ and Troubleshooting

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

Can I build my own Messaging Orchestration?

In order to build your own messaging orchestration, you need to ensure that the Flex Message handlers are not configured for relevant Numbers or Chat Channels, Chat Services, or Chat Webhook. Instead of using the Flex Message handlers, you can configure your channels to use your custom handler.

You'll also need to override default Flex orchestration with the ChatOrchestrator object available in Flex UI version 1.9 and greater. Without the override, the Flex UI will attempt to add Agents to Chat Channels when they accept a task. Since you would not be using Flex Message Handlers, adding the Agent to the channel will fail.

Flex will add new features and functionality to support future Messaging use cases. These features may not work with your custom messaging orchestration solution, or your team will need to do additional development to make the new features compatible with your custom solution.

How do I route my outbound tasks to a specific agent?

Define a new TaskRouter Workflow that assigns the task to the agent when the Task attribute contact_uri matches that of a specific agent.

Example Workflow:

A view of a TaskRouter workflow in the Twilio console. There is a key expression for matching workers: task.targetWorker == worker.contact_uri

How do I auto-accept a task in the Flex UI?

You can auto-accept the task using the Flex Actions Framework, like so:

init(flex, manager) {
  //auto-accepts tasks
  manager.workerClient.on('reservationCreated', reservation => {
    if (reservation.task.attributes.autoAnswer === 'true') {
      flex.Actions.invokeAction('AcceptTask', {sid: reservation.sid});
      //select the task
      flex.Actions.invokeAction('SelectTask', {sid: reservation.sid});

Can I use custom Task Channels or Channel Types?

Yes. However, you must tell Flex UI that this Task has Messaging/Chat capabilities. For example:

const myOwnChatChannel = flex.DefaultTaskChannels.createChatTaskChannel(
    task => task.channelType === "custom"

Or, using Task Channel name:

const myOwnChatChannel = flex.DefaultTaskChannels.createChatTaskChannel(
    task => task.taskChannelUniqueName === "custom1"

How do I troubleshoot my messaging setup?

Let’s assume you’re testing an inbound SMS message flow that’s being handled by Studio. Some questions you can consider are:

Did Twilio receive the incoming message?
Navigate to the phone numbers section of the Twilio Console, find your Contact Center number that user sent the message to, go to Messages tab and make sure your filter includes Incoming messages. If you don’t see your message in these logs, something is preventing your number from receiving the message. Consider filing a support ticket and contacting your account executive.

Did your message hit Proxy and create a new Session or initiate an existing session?
There should be a Session and related Interaction in the Flex Proxy Service. If you don’t see an Interaction, make sure that the Session status is still Open. If you don’t see a Session, you may need to configure your number in the Flex messaging manager.

Is the Proxy Session linked to a Chat Channel?
Navigate to Programmable Chat in the Twilio Console, pick the Flex Chat Service instance and find the Channel. It contains all interactions from the customer side and from the Contact Center side.

If you don’t see a chat channel, or don’t see any interactions in the chat channel, consider filing a support ticket and contacting your account executive.

Did the message hit your Studio Flow?
All Studio interactions are captured in a Flow’s Execution Logs. Find “Messaging Flow” (the default flow created for Flex) and navigate to Studio logs to see the execution associated with the failed message.

You can inspect error messages in each step of the Studio flow. HTTP Requests and Function Widgets frequently return error codes that can terminate the entire execution.

Did Studio create a Task in TaskRouter?
You can inspect Tasks in the TaskRouter section of the Twilio Console. The Task should have a reference to the relevant Chat Channel in its Attributes.

Was the agent able to accept the Reservation?
When an Agent accepts the Reservation related to this Task, a new Chat User will be visible in that Chat Channel as a Member. The role linked with that Agent user is “agent”.

Please do not modify the standard permissions of this role (sendMessage, sendMediaMessage, leaveChannel, editChannelAttributes, editOwnMessage, editOwnMessageAttributes, deleteOwnMessage).

Any Messages sent by the Agent should be visible under the Phone Number / Messaging Logs. Optionally, you can filter messages by Outgoing Messages to more easily find the agent’s message.

Once the Agent has completed the Task, Flex will take care of the following maintenance:

  1. Task changes status to Completed and is deleted after 10 minutes.
  2. Agent is removed from the Chat Channel.
  3. The Chat Channel status is set to inactive.
  4. The corresponding Proxy Session is deleted.
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 Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

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

Thanks for your feedback!