Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Building Flex Plugins

Flex plugins are essential to customizing Flex instances so your development team can share components with agents and supervisors across your organization. Plugins are simply React code, packaged for hosting on Twilio's Runtime platform as Assets. Let's take a look at the plugin creation workflow.


In order to complete this activity, you’ll need the following:

  • A Twilio account with a Flex environment provisioned (start here)
  • NPM version 5.0.0 or later installed (type npm -v in your terminal to check your version)
  • Node version 8.0.0 or later installed (type node -v in your terminal to check your version)
  • The create-flex-plugin npm package
  • An editor of your choosing

Default state: Flex

We're going to start with a fresh instance of Flex with no existing customizations. It should look something like this:

Default Flex

Set up the Plugin Builder

Start by installing the create-flex-plugin tool from npm:

npm install -g create-flex-plugin

Next, create a new plugin project by running the following commands in your terminal:

create-flex-plugin plugin-sample

cd plugin-sample

npm install

Please note that your plugin's name has to start with plugin-. If you have a version of npm that is 6.1 or higher, you may skip installing create-flex-plugin globally and instead run:

npm init flex-plugin plugin-sample --install

If you already have create-flex-plugin installed, you'll need to uninstall it to avoid conflicts with flex-plugin.

Once you've set that up, you can run npm start to start up the webpack dev server with a version of Flex.

Customize Flex for your plugin

Plugins come in many forms, and resemble the UI customizations you have probably already done with your local instance of Flex -- for example, you may use the Actions Framework, customize language strings, or build a component. For organizational purposes, component code should be stored in the /src directory of the plugin builder repo.

Your plugin customization (Action override, string change, component add/replace, etc.) happens in the init function in src/SamplePlugin.js:

import { FlexPlugin } from 'flex-plugin';
import React from 'react';
import CustomTaskListComponent from './CustomTaskListComponent';

const PLUGIN_NAME = 'SamplePlugin';

export default class SamplePlugin extends FlexPlugin {
  constructor() {

  init(flex, manager) {
    flex.TaskList.Content.add(<CustomTaskListComponent key="demo-component" />, {
      sortOrder: -1,

For this sample, we'll do a simple plugin that replaces the CRMContainer with a Bing search that updates when a task comes in. Our init function will look like this:

init(flex, manager) {
  flex.TaskList.Content.add(<CustomTaskListComponent key="demo-component" />, {
    sortOrder: -1,
  flex.CRMContainer.defaultProps.uriCallback = (task) => {
      return task ? "" + : "";

Save your changes, and reload your local instance of Flex in the browser. It should look something like this, with the CRMContainer replaced with Bing's home page:

Flex with Bing

Build your plugin locally

To create your plugin bundle, run npm run build. A file called plugin-name.js will output in the /build folder.

You can rename this file as long as it matches the naming convention of plugin-*.js so that Flex will recognize it as a Flex plugin. For this sample, we'll call ours plugin-bingsearchplugin.js.

Upload your plugin to Twilio Assets

The next step is to upload the plugin file (the one you just renamed) as a public Twilio Asset. Navigate to the Assets manager in your Twilio console and drag-and-drop your plugin file (or click the red + sign) to upload your Asset. Be sure to keep the "Make Private" checkbox on the upload confirmation modal deselected, as plugins need to be public Assets.

Drag plugin to assets

See your Plugin in action

Load (or refresh) your hosted Flex instance. Your plugin should now be available.

Jennifer Aprahamian Ben Getson Tom De Carlo Kat King
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 browsing the Twilio tag on Stack Overflow.