How to Notify Agents in Twilio Flex with Audio for Incoming Calls – Twilio Support

Objective

This article will guide you through the process of notifying Flex agents about inbound voice calls by playing a custom audio alert in the browser. This can be achieved by creating a custom Twilio Flex Plugin that plays a ringtone when a new inbound call is assigned to a worker. This solution helps ensure that agents don't miss any incoming calls even if they are not actively watching their Flex UI.

Product

Twilio Flex

User Account Permission/Role(s) Required

Anyone who can deploy plugins using the Twilio CLI can set this up.

This usually includes:

Flex Admins
Developers with the right access

You’ll need:

Access to your Twilio Flex project
Permission to deploy and release plugins using the CLI

Procedure

Step 1: Install the Required Tools

If not already installed, set up the Twilio CLI and the Flex Plugin CLI:

npm install -g twilio-cli
twilio plugins:install @twilio-labs/plugin-flex
twilio login

Step 2: Create the Plugin

Use the following command to scaffold your Flex plugin:

twilio flex:plugins:create flex-inbound-call-alert-plugin --install

This will generate the plugin project in a new folder called flex-inbound-call-alert-plugin.

Step 3: Add the Plugin Code

Replace the content of src/index.js with:


import * as FlexPlugin from "@twilio/flex-plugin";
import FlexInboundCallAlertPlugin from "./FlexInboundCallAlertPlugin";

FlexPlugin.loadPlugin(FlexInboundCallAlertPlugin);

Then, in src/FlexInboundCallAlertPlugin.js, paste the following code:


import { FlexPlugin } from "@twilio/flex-plugin";

const PLUGIN_NAME = "FlexInboundCallAlertPlugin";

export default class FlexInboundCallAlertPlugin extends FlexPlugin {
  constructor() {
    super(PLUGIN_NAME);
  }

  init(flex, manager) {
    const alertSound = new Audio("https://api.twilio.com/cowbell.mp3");
    alertSound.loop = true;

    const resStatus = [
      "accepted",
      "canceled",
      "rejected",
      "rescinded",
      "timeout",
    ];

    manager.workerClient.on("reservationCreated", (reservation) => {
      console.log(
        `Reservation created: ${reservation.sid} - Status: ${reservation.status}`
      );

      // Play alert only for inbound voice calls
      if (
        reservation.task.taskChannelUniqueName === "voice" &&
        reservation.task.attributes.direction === "inbound"
      ) {
        alertSound.play().catch((error) => {
          console.warn("Error playing alert sound:", error);
        });
      }

      // Stop alert sound on reservation final status
      resStatus.forEach((status) => {
        reservation.on(status, () => {
          console.log(`Reservation ${status}: ${reservation.sid}`);
          alertSound.pause();
          alertSound.currentTime = 0; // reset audio to start
        });
      });
    });
  }
}

Step 4: Test the Plugin Locally

To start your local Flex development environment and test the alert:

twilio flex:plugins:start

Make sure you are logged into a Twilio account with access to your Flex project.

Step 5: Deploy and Release the Plugin

Once you’ve finished testing and everything looks good, you can deploy your plugin. In your terminal, inside the /flex-inbound-call-alert-plugin directory, run:

twilio flex:plugins:deploy --major --changelog "Add inbound call sound alert"

Then release the deployed version:

 twilio flex:plugins:release --plugin flex-inbound-call-alert-plugin@x.y --name
 "Initial Release" --description "Alert for inbound call using custom audio"

Replace x.y with the deployed version number (e.g., 1.0.0) shown in the deploy output.

Make sure the browser has permission to play sound.
You may need to interact with the page (e.g., click anywhere) before audio can auto-play depending on browser settings.
The audio file URL (https://api.twilio.com/cowbell.mp3) should be publicly accessible and properly hosted.

Optional: Hosting Your Plugin on GitHub

You can keep your plugin version-controlled and shareable by hosting it on GitHub. Follow these steps:

Step 1: Create a GitHub Repository

Go to https://github.com
Click "New" to create a new repository
Name your repo (e.g., flex-inbound-call-alert-plugin)
Choose Public or Private
Click Create repository

Step 2: Initialize Git in Your Plugin Directory

In your terminal:

cd flex-inbound-call-alert-plugin
git init

Step 3: Add and Commit Your Code

git add .
git commit -m "Initial commit of Flex call alert plugin"

Step 4: Connect to GitHub

Copy the repo URL from GitHub and run:

git remote add origin https://github.com/your-username/flex-inbound-call-alert-plugin.git

Step 5: Push Your Code

git push -u origin main

Tip: If your default branch is called master, use that instead of main.

Additional Information