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:

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

Or, using Task Channel name:

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.

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 more easily 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 Flex UI 1.x and legacy channels for messaging, please ensure you follow these steps:

• Downgrade your Flex UI version
  From the Flex Versioning and updates page in the Admin dashboard, select a 1.x.x version from the Version list. Ensure you test your plugins before you confirm the version installation and refresh. To pin to a specific Flex UI version, see "Flex UI Versioning" on the Flex UI Core Concepts page .
• Remove Conversations addresses from your account
  Navigate to Flex > Manage > Messaging in the Twilio Console and select the Conversations Addresses tab. Take note of the address details before deleting each Conversations address. Next, select the SMS Numbers tab. Remove addresses with the "Conversations" label in the Status field of each address.

• Create legacy addresses
  To revert to using Programmable Chat and Proxy for SMS and chat, click Legacy Addresses and follow the steps on Manage SMS Addresses and Manage WebChat Addresses respectively. When creating a legacy address, you can reuse the same Studio Flow previously associated with a Conversations address. However, you need to ensure that the Send to Flex widget is connected to the "Incoming Message" trigger and that it uses the attributes structure for Messaging and Chat Studio flows.

  Expand image
• Configure your phone number to use the Flex Proxy Service for incoming messages
  After updating the address configuration for your phone number, navigate to Phone Numbers > Manage > Active Numbers and make sure it is using the Flex Proxy Service for handling inbound messages.
• If you're running a Flex plugin, check your React version for compatibility
  Flex UI 1.x.x uses React 16.5.2 by default. If your plugin was built on a later version, navigate to Flex Admin dashboard > Developer Setup and select "Latest" from the React Version dropdown. Click Save to apply the change.

If you see "Failed to fetch session because Could not find any web chat flows for user" errors after downgrading from Flex UI 2.x.x to 1.x.x, please review these downgrade steps.