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 — SMS, WhatsApp, etc. — which you can integrate with Studio or your own backend application.

In order 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, agents are automatically added (upon acceptance) and removed from Conversations tasks (upon completion). To override this behavior, see WebChat Actions. Without the override, the Flex UI will attempt to add agents to your Conversations channels when they accept a task.

Flex will add new features and functionality to support future Conversations 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.

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, like so:

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

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

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

Or, using Task Channel name:

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

File attachments are enabled by default on your Flex account. If this is not the case, you will need to update your account service configuration with a new 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.

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?

1. Check that the message arrived at Twilio by checking your Programmable Messaging Logs in the Console under Monitor > Logs> Messaging.
2. If the message does not appear here, it means that the message has not yet arrived at Twilio. If the incoming message is present, drill into it by clicking the date and verifying that it was handled by the right messaging service.
3. 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.
4. Double check that you have your Messaging Service set 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 is 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, this may be an "orphaned" conversation. If this happens, please consider filing a support ticket.

In the meantime, for orphaned conversations, you could manually send them to Flex by invoking the Interactions API.

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, or the Chat Flow if you're debugging a web chat interaction) 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 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 should have a reference to the relevant Interaction and Conversation SID in its Attributes.

Was the agent able to accept the Reservation?

When an Agent accepts the Reservation related to this Task, the agent user will be added as a Participant to the conversation. The role linked with that Agent user is "agent".

Please do not modify the standard permissions of this role (sendMessage, sendMediaMessage, leaveConversation, editConversationAttributes, 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 find the agent's message.

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

1. Task changes status to Completed and is deleted after 10 minutes.
2. Agent is removed from the Conversation.
3. The Conversation state is set 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.