Chat and SMS Transfers

Transfer chats and SMS between agents

This solution features sample code that is provided “as is” and is not production grade. The featured code does not account for edge case handling, scalability, and reliability. It is not covered under Twilio's Service Level Agreement (SLA) and support plans.

The Chat and SMS Transfer solution helps contact center administrators set up transferring of Chats and SMS between Agents. When a customer is interacting with an Agent via Chat or SMS, they can be transferred to another agent or to a queue of agents. This solution supports "cold" chat or SMS transfers.





To deploy this solution, you will need:

  • An active Twilio account with Flex provisioned. Refer to the Flex Quickstart to create one.
  • npm version 5.0.0 or higher (type npm -v in your terminal to check)
  • Node.js version 10.12.0 or higher (type node -v in your terminal to check)
  • Twilio CLI along with the Flex CLI Plugin and the Serverless Plugin. Run the following commands to install them:
    # Install the Twilio CLI
    npm install twilio-cli@latest -g
    # Install the Serverless and Flex as Plugins
    twilio plugins:install @twilio-labs/plugin-serverless
    twilio plugins:install @twilio-labs/plugin-flex

If you're running Linux, click on the Linux tab for the Twilio CLI installation instructions. If you're running Windows, make sure to run the Windows command prompt as an administrator to install the Serverless and Flex plugins for the Twilio CLI. The Windows commands in this guide use PowerShell (for Node.js/npm installation).

Deployment Time

30 minutes

Tested Flex Versions and Operating Systems

  • Flex v1.18.1-1.23.1
  • macOS / Unix
  • Windows 10

Configure your Flex Workspace

In order to use the solution, you need to prepare your Flex Task Assignment workspace.

Retrieve your Flex settings

Step 1

Navigate to your Flex project in the Twilio Console. Copy your ACCOUNT SID and AUTH TOKEN, and create a new Twilio CLI profile using those credentials:

twilio profiles:create

You will be prompted to enter your Twilio Account SID, Auth Token, and a shorthand identifier for your profile. When choosing a shorthand identifier, pick one that is meaningful and easy to remember. Once your profile has been created, activate it by running:

twilio profiles:use <profile_name>

Keep in mind that this account will be used for the rest of the deployment. In order to switch accounts, use the following command:

twilio profiles:use <different_profile>

Step 2

Retrieve your Flex Task Assignment workspace ID:

twilio api:taskrouter:v1:workspaces:list

Example Workspace SID

SID                                      Friendly Name               Prioritize Queue Order

To retrieve your Flex workspace SID from the Twilio Console, navigate to the TaskRouter Dashboard.

Step 3

Retrieve the unique IDs (or SIDs) of the queues you wish to associate with your Chat Transfer workflow. Copy these values for the next step.

twilio api:taskrouter:v1:workspaces:task-queues:list --workspace-sid WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 

Example Task Queue SID

SID                                     Friendly Name               Task Order

To retrieve your Flex task queue SID from the Twilio Console, navigate to TaskRouter > "Flex Task Assignment" > TaskQueues.

Create a new TaskRouter Workflow

To create a new workflow, run the following command in your terminal. Replace the field queue and workspace SID details with the SIDs of the queue and workspace you retrieved from the previous steps.

    "task_routing": {
        "filters": [
                "filter_friendly_name": "Worker Filter",
                "expression": "transferTargetType == 'worker'",
                "targets": [
                      "expression":"worker.sid == task.targetSid"
                "filter_friendly_name": "Sales Queue",
                "expression": "transferTargetType == 'queue' AND targetSid == 'WQYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY'",
                "targets": [
                "filter_friendly_name": "Support Queue",
                "expression": "transferTargetType == 'queue' AND targetSid == 'WQZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ'",
                "targets": [
        "default_filter": {

twilio api:taskrouter:v1:workspaces:workflows:create --workspace-sid WSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX --friendly-name "Chat Transfers" --configuration "$CONFIGURATION"

First, set your required Queue SIDs and your Flex workspace SID as environment variables.


To confirm that an environment variable has been set, run echo %ENVVAR%.

twilio api:taskrouter:v1:workspaces:workflows:create --workspace-sid=%WORKSPACESID% --friendly-name "Chat Transfers" --configuration="{ ""task_routing"": { ""filters"": [ { ""filter_friendly_name"": ""Worker Filter"", ""expression"": ""transferTargetType == 'worker'"", ""targets"": [ { ""queue"": ""%EVERYONEQUEUE%"", ""expression"": ""worker.sid == 'task.targetSid'"" } ] }, { ""filter_friendly_name"": ""Sales Queue"", ""expression"": ""transferTargetType == 'queue' AND targetSid == '%SALESQUEUE%'"", ""targets"": [ { ""queue"": ""%SALESQUEUE%"" } ] }, { ""filter_friendly_name"": ""Support Queue"", ""expression"": ""transferTargetType == 'queue' AND targetSid == '%SUPPORTQUEUE%'"", ""targets"": [ { ""queue"":""%SUPPORTQUEUE%"" } ] } ], ""default_filter"": { ""queue"": ""%EVERYONEQUEUE%"" } }}"

Example Workflow Confirmation

SID                                  Friendly Name         Document Content Type

For more details on expected workflow settings, see Plugin Details. To learn about configuring more complex workflows, see Create a Workflow Resource and Configuring Workflows: Complex Routing Example.

Download the Chat/SMS Transfer Flex Plugin

Download the plugin source code and unzip the files in a local directory.

Deploy your Twilio Function

We will deploy the Chat/SMS Transfer function to your Flex instance. The function is called from the plugin you will deploy in the next step and integrates with TaskRouter, passing in required attributes to perform the chat transfer.

Step 1: Change into the functions directory and rename .env.example.

plugin-chat-sms-transfer $ cd functions && mv .env.example .env
C:\Users\username\plugin-chat-sms-transfer> cd functions && move .env.sample .env


1 file(s) moved.

Step 2: Open .env and set the environment variables mentioned in the file.

TWILIO_ACCOUNT_SID = your Account SID from 
TWILIO_AUTH_TOKEN = your Auth Token from
TWILIO_WORKSPACE_SID = your Flex Task Assignment workspace ID

Step 3: Deploy the Twilio function to your account using the Twilio CLI:

twilio serverless:deploy

When running on Windows, you may see an error with the Twilio Serverless deployment command. To work around the issue, set your TWILO_ACCOUNT_SID and TWILO_AUTH_TOKEN as environment variables. Refer to the previous section for examples on how to set an environment variable in Windows.

Example Function Deployment Output

⠇ Creating 1 Functions
✔ Serverless project successfully deployed

Deployment Details

Step 4: Copy and save the domain returned when you deploy a function. You will need it in the next step.

If you forget to copy the domain, you can also refer to it by navigating to Functions > API.

Debugging Tip: Pass the -l or logging flag to review deployment logs. For example, you can pass -l debug to turn on debugging logs.

Deploy your Flex Plugin

Once you have deployed the function, it is time to deploy the plugin to your Flex instance.

Run the following commands in the plugin directory. We will leverage the Twilio CLI to build and deploy the Plugin.

plugin-chat-sms-transfer $  npm install

You need to modify the source file to mention the serverless domain of the function that you deployed previously.

  • Open src/helpers/actions.js in a text editor of your choice.

  • Paste the Function deployment domain in the variable SERVERLESS_FUNCTION_DOMAIN. Make sure to prefix the domain with https://.


When you are ready to deploy the plugin, run the following in a command shell:

twilio flex:plugins:deploy --major --changelog "Update the plugin to use Builder v4" --description "Chat and SMS Cold Transfers in Flex"

Example Plugin Deployment Output

✔ Validating deployment of plugin plugin-chat-sms-transfer
⠧ Compiling a production build of plugin-chat-sms-transferPlugin plugin-chat-sms-transfer was successfully compiled with some warnings.
✔ Compiling a production build of plugin-chat-sms-transfer
✔ Uploading plugin-chat-sms-transfer
✔ Registering plugin plugin-chat-sms-transfer with Plugins API
✔ Registering version v1.0.0 with Plugins API

🚀 Plugin (private) plugin-chat-sms-transfer@1.0.0 was successfully deployed using Plugins API

Enable the Plugin on your Flex application

The previous step only deploys your plugin. You still need to enable the Plugin on your Flex application. To enable, run the following:

twilio flex:plugins:release --plugin plugin-chat-sms-transfer@1.0.0 --name "Chat and SMS Transfers" --description "Enabling chat and SMS transfers using Solution Guide"

View plugin on your Plugins Dashboard

After running the suggested next step, navigate to the Plugins Dashboard to review your recently deployed plugin and confirm that it’s enabled for your contact center.

You are all set to test Chat and SMS Transfers on your Flex application!

Keep in mind that your agents need to refresh their browsers in order to get the latest changes.

Testing the solution

Step 1: Log in as an admin to your Flex instance where you deployed the plugin.

Step 2: Change your status to Available on the upper right corner of the Flex UI. This enables you to receive incoming calls and messages (SMS or chat).

Step 3: To test SMS transfer in Flex, send a text to the number associated with your Flex instance (you can find the Twilio-provisioned number for your Flex instance on the Admin panel under "Test Drive").

Step 4: To test chat transfer, click "Launch" (on the Admin panel) to launch the Flex web chat widget. This will open up a new tab where you can enter a test message.

Step 5: To see the incoming text or chat request, navigate to the Agent Desktop in your Flex Instance.

Step 6: Upon clicking "Accept", you should now see a Transfer button next to End Chat.


Step 7: Click Transfer to initiate a transfer. You have the option to either transfer the chat to another agent (via the Agents tab) or reassign the chat to a queue of agents (via the Queues tab).

Step 9: Click the Right Arrow icon to perform a cold transfer. This autocompletes the initial chat task for the agent who initiated the transfer, and creates a new chat task for the agent receiving the transfer.


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 Community Forums or browsing the Twilio tag on Stack Overflow.

Thank you for your feedback!

We are always striving to improve our documentation quality, and your feedback is valuable to us. Please select the reason(s) for your feedback or provide additional information about how we can improve:

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

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more