External Cold Transfer Plugin for Twilio Flex

This Twilio Flex Plugin adds external cold transfer functionality with phone number validation. It allows agents to transfer calls to external phone numbers with a custom dialog interface.

Features

• External Cold Transfer Button: Adds a button to the call canvas for initiating external cold transfers
• Custom Transfer Dialog: Modal dialog for entering phone numbers
• Phone Number Validation: Validates phone numbers using Twilio Lookup API before transfer
• Error Handling: Comprehensive error notifications and validation messages
• Serverless Functions: Backend functions for secure call transfer operations

Prerequisites

Make sure you have Node.js as well as npm. We support Node >= 10.12 (and recommend the even versions of Node).

Install the Twilio CLI by running:

brew tap twilio/brew && brew install twilio

Install the Flex Plugin extension for the Twilio CLI:

twilio plugins:install @twilio-labs/plugin-flex

Install the Serverless Plugin for the Twilio CLI:

twilio plugins:install @twilio-labs/plugin-serverless

Setup

1. Install Plugin Dependencies

cd plugin-external-cold-transfer
npm install

2. Deploy Serverless Functions

The plugin requires serverless functions for cold transfer operations and phone number validation.

cd ../external-cold-transfer-functions
npm install
twilio serverless:deploy

After deployment, note the Domain from the output. It will look something like:

Domain: external-cold-transfer-functions-XXXX-dev.twil.io

3. Configure Environment Variables

Copy the .env.sample file to .env:

cd ../plugin-external-cold-transfer
cp .env.sample .env

Edit the .env file and update the REACT_APP_SERVERLESS_DOMAIN with your deployed serverless domain (without https://):

REACT_APP_SERVERLESS_DOMAIN=external-cold-transfer-functions-XXXX-dev.twil.io

4. Configure appConfig.js

cp public/appConfig.example.js public/appConfig.js

5. Run the Plugin Locally

twilio flex:plugins:start

This will start the plugin locally and open Flex in your browser.

Deployment

Deploy the Plugin

twilio flex:plugins:deploy --major --changelog "Added external cold transfer functionality" --description "External Cold Transfer Plugin"

Release the Plugin

twilio flex:plugins:release --plugin flex-external-cold-transfer@1.0.0 --name "External Cold Transfer Release" --description "Release external cold transfer plugin"

Usage

1. During an Active Call: The External Cold Transfer button will appear in the call canvas actions (circular button with phone icon)
2. Click the Button: Opens a dialog to enter the phone number
3. Enter Phone Number: Type the destination phone number
4. Transfer: Click "Transfer" to initiate the cold transfer
   • The phone number will be validated
   • If valid, the call will be transferred
   • The task will automatically complete

Architecture

Plugin Components

• ExternalColdTransferButton: Circular button component in call canvas
• ExternalColdTransferDialog: Modal dialog for entering phone numbers
• StartExternalColdTransfer Action: Custom Flex action for handling transfers
• ProgrammableVoiceService: API service for call operations
• PhoneNumberService: API service for phone number validation

Serverless Functions

• external-cold-transfer: Handles the cold transfer operation using Twilio's Programmable Voice API
• validate-phone-number: Validates phone numbers using Twilio Lookup V2 API

Configuration

Skip Phone Number Validation

To skip phone number validation (useful for SIP addresses or app: URIs), pass skipPhoneNumberValidation: true in the action payload:

Actions.invokeAction("StartExternalColdTransfer", {
  task: task,
  phoneNumber: phoneNumber,
  callerId: callerId,
  skipPhoneNumberValidation: true,
});

Troubleshooting

Button Not Showing

• Ensure you're on an active call
• Check that the plugin is properly deployed and activated

Transfer Fails

• Verify serverless functions are deployed
• Check the .env file has the correct serverless domain
• Ensure phone number is in E.164 format (e.g., +1234567890)

Validation Errors

• Check that your Twilio account has access to Lookup API
• Verify the phone number is valid and in correct format

Development

Run twilio flex:plugins --help to see all the commands we currently support. For further details on Flex Plugins refer to our documentation on the Twilio Docs page.