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

Transition to Twilio Flex


(warning)

Twilio Alpha - Developer Preview

AI Assistants is a Twilio Alpha(link takes you to an external page) project that's in Developer Preview. To request access, please join the waitlist(link takes you to an external page).

View the current limitations for details about feature limits during developer preview.

Transitions are crucial for keeping humans in the loop and escalating conversations with your AI Assistant when necessary. Currently, these transitions can be configured by giving your AI Assistant a Tool. In the future, Assistants will support native transitions.

In this guide, you will learn how to transition a conversation with your AI Assistant to a Flex agent.


Prerequisites

prerequisites page anchor

To begin, you will need the following:

  • A Twilio Flex instance.
  • An AI Assistant in the same Twilio account as the Flex instance.
  • A webhook connecting your Assistant with Twilio Conversations (see the guide Use Twilio Conversations as a Channel for the steps).
  • A TaskRouter Workspace SID and Workflow SID to hand off the Conversation to the right Workflow.

Configure your AI Assistant tool for handover

configure-your-ai-assistant-tool-for-handover page anchor

After you've connected your AI Assistant to Twilio Conversations, your AI Assistant will listen to any message that has only one participant (your customer) in the conversation. To hand off the conversation to a human agent, the AI Assistant has to call a Tool that uses the Flex Interactions API to hand off to a Flex agent.

You can do this either by using a Twilio Function that was already deployed into your Twilio account as part of the Conversations setup above, or by creating your own HTTP endpoint.

Either way, once a second participant joins the conversation, your AI Assistant will automatically stop listening.

Use Twilio Functions for your Handover Tool

use-twilio-functions-for-your-handover-tool page anchor

If you followed the AI Assistants with Twilio Conversations guide, one of the Twilio Functions that you deployed as part of this was a Flex Handover tool.

To make sure you hand off the conversation to the right Flex agents, configure environment variables for your Twilio Functions that specify the TaskRouter Workspace SID and TaskRouter Workflow SID for the handoff.

In the ai-assistants-samples project that you cloned and deployed, run the following commands:


_10
twilio serverless:env:set --key=FLEX_WORKFLOW_SID --value=<your-taskrouter-workflow-sid>
_10
twilio serverless:env:set --key=FLEX_WORKSPACE_SID --value=<your-taskrouter-workspace-sid>

Make sure to replace <your-taskrouter-workflow-sid> and <your-taskrouter-workspace-sid> with the respective values.

To use this webhook as a Tool, you will need your Functions domain from the AI Assistants Samples deployment. If you can't find your Functions domain, head to the Twilio Console(link takes you to an external page) and click on Service Details next to your ai-assistants-samples Service. You can find the domain in the Environments section.

Once you have both your Flow SID and your Functions domain, you can go into your AI Assistant in the Twilio Console(link takes you to an external page) and create a new Tool with the following configuration:

FieldExample ConfigurationNotes
NameFlex Agent HandoverYou can modify this if you have multiple handovers.
DescriptionYou MUST use this if you don't know how to fulfill the request to let another customer service agent handle the conversation.Use this description to tell the AI Assistant when to use the tool.
Input
{}
MethodPOST
URLhttps://<your-functions-domain>.twil.io/tools/flex-handoverMake sure to replace <your-functions-domain> with your own value.

Use your own backend to host your Handover Tool

use-your-own-backend-to-host-your-handover-tool page anchor

Alternatively to using Twilio Functions for your Tool, you can host an HTTP endpoint yourself and use the Flex Interactions API to route the conversation to a Flex Agent.

Here is an example of calling the API using the Twilio Python helper library:


_18
interaction = twilio_client.flex_api.v1.interaction.create(
_18
channel={
_18
'type': 'chat', # can be chat or SMS
_18
'initiated_by': 'customer',
_18
'properties': {
_18
'media_channel_sid': conversation_sid # Stored in the `X-Session-Id` request header
_18
}
_18
},
_18
routing={
_18
'properties': {
_18
'workspace_sid': taskrouter_workspace_sid, # your taskrouter workspace sid
_18
'workflow_sid': taskrouter_workflow_sid, # your taskrouter workflow sid
_18
'attributes': {
_18
'from': 'Customer Name' # the name of the customer (you can use the `X-Identity` header to look up the customer's identity)
_18
}
_18
}
_18
}
_18
)


Now you've configured your AI Assistant to hand off a conversation to a Flex agent if it cannot fulfill a user's request.


Rate this page: