Conversations FAQ and Troubleshooting

Flex Conversations is based on the single Twilio Conversations primitive, which reduces the complexity of building async channel workflows. You can configure addresses for your Flex Conversations channels, including SMS, WhatsApp, and others, which you can integrate with Studio or your own backend application.

To build your own messaging orchestration, continue to have the number or sender ID configured as a Conversations address. However, you must not use the Send To Flex widget or the Interactions API to route to Flex. You can use the TaskRouter API to create a customer task to route to Flex.

By default, Flex adds agents to Conversations tasks when they accept the task and removes them when the task is complete. To change this default behavior, see WebChat Actions. Unless you change this behavior, Flex UI attempts to add agents to your Conversations channels when they accept a task.

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

If you don't configure Conversations addresses, remove the addresses. Don't use the Send to Flex Widget.

Additionally, you need to override the "wrapup" and "complete" actions for your custom channels.

Use known agent routing in your workflow to assign a task to a specific agent. You can also use the Interactions API to specify an agent-initiated interaction as well as add a specific agent to an existing interaction.

You can auto-accept the task using the Flex Actions Framework, as shown in the following example:

1
init(flex, manager) { 
2
  // Auto-accepts tasks
3
  manager.workerClient.on('reservationCreated', reservation => { 
4
    if (reservation.task.attributes.autoAnswer === 'true') {
5
      flex.Actions.invokeAction('AcceptTask', { sid: reservation.sid }); // Accept the task
6
      flex.Actions.invokeAction('SelectTask', { sid: reservation.sid }); // Select the task
7
    } 
8
  }); 
9
}

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

1
const myOwnChatChannel = flex.DefaultTaskChannels.createChatTaskChannel(
2
  "my-chat-channel",
3
  (task) => task.channelType === "custom"
4
);
5
flex.TaskChannels.register(myOwnChatChannel);

Or, using Task Channel name:

1
const myOwnChatChannel = flex.DefaultTaskChannels.createChatTaskChannel(
2
  "my-chat-channel",
3
  (task) => task.taskChannelUniqueName === "custom1"
4
);
5
flex.TaskChannels.register(myOwnChatChannel);

File attachments are enabled by default on your Flex account. If this isn't the case, update your account service configuration to add an entry in the channel_configs array.

For a list of address types and accepted file extensions, see Channel Attachment Limits. To disable file attachments for a channel, set "enabled" to false for that specific channel_configs entry. Make sure to specify your account_sid in your POST request.

1
curl --location --request POST 'https://flex-api.twilio.com/v1/Configuration/' \
2
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
3
--header 'Content-Type: application/json' \
4
--data-raw '{
5
"account_sid":"ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
6
   "channel_configs":[
7
      {
8
         "cbm_attachments":{
9
            "max_file_size":16777216,
10
            "max_total_file_size":67108864,
11
            "accepted_extensions":[
12
               "jpg",
13
               "jpeg",
14
               "png",
15
               "amr",
16
               "mp3",
17
               "mp4",
18
               "pdf",
19
               "heic",
20
               "txt",
21
               "gif"
22
            ],
23
            "enabled":false,
24
            "number_of_attachments":1
25
         },
26
         "address_type":"web"
27
      },
28
      ...
29
   ]
30
}'

Note that the code sample has been clipped with ... for brevity.

Using the example of testing an inbound SMS message flow that Twilio Studio handles, here are some questions you might ask:

Did Twilio receive the incoming message?

1. Check that the message arrived at Twilio by checking your Programmable Messaging logs in the Console under Monitor > Logs> Messaging.
2. If you don't see the message here, it means that the message hasn't yet arrived at Twilio. If the incoming message is present, click the date and verify that it was handled by the right messaging service.
3. If you don't see your message in the logs, something prevented your number from receiving the message. Consider filing a support ticket and contacting your account executive.
4. Double check that you set your Messaging Service to perform auto-create as per the setup instructions.
5. You can enable live debugging on the Twilio Function, which may give some hints if it's failing here.
6. For the Flex UI, open the browser console to check for errors. You can also see our troubleshooting guide for Flex UI.

Did your message trigger a Conversation to be created?

Any message to a Conversations address that's outside of a conversation should cause the auto-create functionality to create a new conversation, add the sender as a participant, and append the message to the newly-created conversation. To find if the sender has an active conversation, use the Conversation Participant resource to find the active conversation. If there is no active conversation for this participant, check that your Conversation address is configured correctly and that the Messaging and Conversations services are also configured correctly.

Does the Conversation have a webhook or Studio configured as the scoped webhook?

If you found an active conversation for the sender in the previous step, check if a Studio or webhook integration is configured correctly by querying the Conversation Scoped Webhook resource. The configuration should have either a Studio target or webhook target as per the Conversation address. If not, the conversation may not have been processed because it isn't associated with a handler. If this happens, consider filing a support ticket. You could also try sending unprocessed conversations to Flex by invoking the Interactions API.

Did your Studio Flow receive the message?

All Studio interactions are captured in a Flow's Execution Logs. Find "Messaging Flow" (the default flow created for Flex, or the Chat Flow if you're debugging a web chat interaction) and go to the 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 end the entire execution.

Did Studio create an Interaction (and Task)?

You can inspect the Studio Flow logs to see the Interaction SID, the Interaction channel SID, and the Task SID.

You can inspect Tasks in the TaskRouter section of the Twilio Console. The Task attributes should contain a reference to the relevant Interaction and Conversation SID.

Was the agent able to accept the Reservation?

When an agent accepts a Reservation related to a Task, Flex adds the agent user as a Participant to the conversation. The role linked with that agent user is agent.

Don't modify the standard permissions of the agent role. These include the following permissions:

• sendMessage
• sendMediaMessage
• leaveConversation
• editConversationAttributes
• editOwnMessage
• editOwnMessageAttributes
• deleteOwnMessage

You can see messages sent by an agent in the Phone Number or Messaging logs. Optionally, you can filter messages by outgoing messages to find the agent's message.

Once an agent completes a Task, Flex does the following:

• Changes the Task status to Completed and deletes it after 10 minutes.
• Removes the agent from the Conversation.
• Sets the Conversation state to closed.

If you're having trouble with Flex Conversations and need to use legacy channels for messaging, see Switch from Flex Conversations to Legacy Messaging for instructions.