Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now

Menu

Expand
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?

Twilio Flex Quickstart: Getting Started with React Plugin Development

In just a few minutes, you can extend and modify your Twilio Flex call center instance freely using the JavaScript React framework.

During this Quickstart, you'll use React to customize your Flex instance by integrating a search engine into the Flex CRM container. This Quickstart only involves cutting/pasting some React code. If you want to learn more, check out the official React Docs.

At the end of this Quickstart, you'll know how to develop a Flex plugin, test it locally, and upload your changes to a Twilio-hosted Flex instance. Once you've seen basic changes you can make with React, you can start to make more extensive modifications to your contact center instance.

In this Quickstart, we will:

  1. Create a new Flex hosted instance
  2. Install the create-flex-plugin npm package
  3. Walk through the plugin creation steps locally
  4. Develop your plugins locally
  5. Upload your plugins to Twilio Assets
  6. Verify your changes in the Twilio hosted call center instance

Prefer other styles of learning? See our collection of Flex video tutorials and demos or Flex TwilioQuest mission.

Make an instance this instant

Create a hosted Twilio Flex instance

Before you start working on plugins for Flex, you'll need a cloud call center instance to apply them on. Let's create a new Flex instance now.

If you already have a Twilio Flex instance you'd like to customize, feel free to skip ahead to the plugin prerequisites.

Sign up for (or sign in to) Twilio and create a Flex Project

Before you can work with Flex, you'll need to sign up for a Twilio account or sign into your existing account.

  1. (If you have an account, otherwise go to step 2) In the console's upper-left hand corner click the menu then choose 'Create New Project':
    New project in the console
  2. In 'Templates', click on the 'Flex' tile where it says 'Create Flex Project':
    Flex template for project
  3. Skip adding teammates and wait for Twilio to spin up your instance
  4. Choose any of the themes

And that's all you need for now. Let it go through its setup, and you'll get a vanilla hosted Flex instance for us to modify.

Make Me React

Prerequisites for developing a Flex React plugin

Before you can start creating Flex plugins with React, you'll need a few things in place.

  • A Twilio account with a Flex environment provisioned (the previous section)
  • NPM version 5.0.0 or later installed (type npm -v in your terminal to check)
  • Node version 8.0.0 or later installed (type node -v in your terminal to check)

Set up a Flex environment with create-flex-plugin

Once you have NPM and Node of the proper version, you're ready to develop your Flex Plugin. The create-flex-plugin node module is the easiest way to build a Flex plugin. This package gives you a clean environment in which to develop your Flex Plugin as well as tools to build and deploy your plugin. With create-flex-plugin, you know that your Flex plugins will be modular - that is, Plugin A won't interfere with the behavior of Plugin B.

In your terminal, run the following command:

npm install -g create-flex-plugin

Once the package is installed, run the following command (Flex plugins must start with "plugin-"):

create-flex-plugin plugin-sample --install
# Or if you prefer a typescript project run
create-flex-plugin plugin-sample --install --typescript

cd plugin-sample

If you are prompted for your account SID, you can find it in the Twilio Console:

account_sid_flex.png

(Optional) For NPM version 6.1 and beyond, you can skip global installation. If you'd like to try this, uninstall create-flex-plugin first:

npm init flex-plugin plugin-sample --install

Once you have created your plugin development environment, you can run the plugin builder:

npm start

A Flex instance should now be running on localhost:3000.

My Environment is Ready! What Next?

Build your Flex plugin

Open your favorite text editor and change the directory to the plugin folder we just built. At the moment, our plugin just adds a black bar to the top of the task list - but we're to configure the CRM to be an instance of the Bing search engine instead.

  1. Navigate into the folder created for plugin-sample (or the name you picked)
  2. Open the file src/SamplePlugin.js
  3. Replace the code in that file with the following:
    import { FlexPlugin } from 'flex-plugin';
    import React from 'react';
    import CustomTaskListComponent from './CustomTaskListComponent';
    
    const PLUGIN_NAME = 'SamplePlugin';
    
    export default class SamplePlugin extends FlexPlugin {
      constructor() {
        super(PLUGIN_NAME);
      }
    
      init(flex, manager) {
        flex.CRMContainer.defaultProps.uriCallback = (task) => {
          return task 
            ? `https://bing.com/?q=${task.attributes.name}`
            : 'https://bing.com';
        }
      }
    }
    
    
  4. Save it
  5. Your browser will automatically reload. Now your instance should look like the following:
    flex_plugin_bing.png
  6. (Optional) Text in and see if there are any Bing results for your phone number!

You might notice that all we changed was a couple of lines of code:

const options = { sortOrder: -1 };
  flex.AgentDesktopView
    .Panel1
    .Content
    .add(<CustomTaskListContainer key="demo-component" />, options);

is replaced by

flex.CRMContainer.defaultProps.uriCallback = (task) => {
  return task 
    ? `https://bing.com/?q=${task.attributes.name}`
    : 'https://bing.com';
}

This tells Flex to target the CRMContainer (instead of the TaskList). Instead of adding a component to the TaskList, we update the URI that the CRMContainer uses as a default prop to render its contents. In this case, we also add a bit of logic to make the container dynamic. We check to see if there's an active task. If there is an active task, we search for the task's name attribute, otherwise, we just show the https://bing.com landing page.

Flex allows you to add, remove, and replace components so that you can tailor your contact center to your business needs. As you build more complex plugins, your workflow will remain similar. When you save files, your environment will reload and you can see the changes locally.

Next up, you'll build the plugin and deploy it to your hosted instance.

Show Me How to Deploy the Flex Plugin

Load a Flex plugin to your hosted instance

Now you just need to build and deploy your plugin to the hosted Flex Instance. We'll be using Twilio's Assets in the console to host our code.

  1. In your terminal, within the plugin-sample directory we created, run: npm run build
  2. Find the path to the newly built plugin. It should be located in a new build folder in the plugin directory.
    1. It can be found in plugin-name/build/plugin-name.js (in our case, plugin-sample/build/plugin-sample.js)
  3. Navigate to your hosted Flex Instance
  4. Click to the 'Admin' pane
  5. Hit the 'Edit' button under 'Developer Setup'
  6. Click the 'Assets' button:
    Developer setup asset upload in Flex
  7. In the Twilio Console Assets page, either drag and drop the bundle, or click on 'Add an Asset'
    Add Asset
  8. Hit 'Upload' and wait for the deployment to complete.
  9. Reload your Flex Instance Agent Dashboard. You should now see the new Bing-powered CRM panel!

You can also get to plugins directly in the Console by searching for Assets in the top right-hand corner of the Console, or by going to the Runtime section of the Console.

This is great! What's next?

Building Flex plugins with React

You now know how to build Flex Contact Center plugins using React, test them locally, then upload them to the cloud. You have the scaffolding to build whatever plugins you desire and see them reflected almost instantly in your call center instance.

Depending on your goals, we have a few paths you might want to follow next. Either explore more around plugin development with Flex and React or visit some of our other Flex Quickstarts.

We can't wait to call what you build!

Building React plugins in Flex

Other Flex Quickstarts

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.