@twilio/flex-sdk

Twilio Flex SDK

With the Twilio Flex SDK, you can embed Twilio Flex contact center features into any web application.

This SDK can only be consumed together with Twilio Flex. Visit https://twilio.com/flex and https://www.twilio.com/docs/flex/developer/flex-sdk to find out more.

Getting started

Installation

To install the Twilio Flex SDK, run the following command in your terminal:

npm install @twilio/flex-sdk

API usage

Initializing the SDK

import { createClient } from "@twilio/flex-sdk";

// Initialize the client
const client = await createClient("SDK_TOKEN");

To initialize the Flex SDK, simply call createClient with your SDK token:

Providing a Custom Worker and Workspace

If you already have or want to manually manage the Worker and/or Workspace, you can pass them to the SDK during initialization. However, it’s important to ensure that you import and initialize them correctly to maintain full compatibility with Flex SDK functionalities.

import { createClient } from "@twilio/flex-sdk";
import { Worker, Workspace } from "@twilio/flex-sdk/taskrouter";

const TOKEN = "SDK_TOKEN";

// Initialize Worker and Workspace correctly
const worker = new Worker(TOKEN);
const workspace = new Workspace(TOKEN);

// Pass them to the SDK client during initialization
const client = await createClient(TOKEN, { worker, workspace });

📌 Note: Incorrect initialization may cause unexpected behavior or compatibility issues with Flex SDK features.

Using a Custom Voice Device

To customize how voice calls behave, you can make use of the Twilio Voice SDK @twilio/voice-sdk package. Create a custom Device object and pass it as a parameter to any voice actions.

Prerequisite

The @twilio/flex-sdk package automatically pulls in @twilio/voice-sdk.
If you install @twilio/voice-sdk separately, make sure the version exactly matches the one bundled with FlexSDK to avoid conflicts.

import { Device } from "@twilio/voice-sdk";
import { AddVoiceEventListener, createClient } from "@twilio/flex-sdk";

async function setVoiceDevice() {
    // Get user permission to access audio devices
    const token = "REPLACE_WITH_ACCESS_TOKEN";
    await navigator.mediaDevices.getUserMedia({ audio: true });

    const device = new Device(token);
    await device.register();
    const inputDevices = Array.from(device.audio?.availableInputDevices.values() || []);
    const myCustomMicrophoneId = inputDevices[1].deviceId;
    await device.audio?.setInputDevice(myCustomMicrophoneId);

    const client = await createClient(token);
    client.execute(
        new AddVoiceEventListener(
            "incoming",
            (call) => {
                console.log("Incoming Call", call);
            },
            { voiceDevice: device }
        )
    );
}

Troubleshooting and debugging

General issues

Errors when making API calls

Ensure you’re making the correct API calls by referring to the API documentation.
Double-check your API credentials and ensure they are properly configured.
Review any error messages for specific error codes or details.

Debugging the SDK

To debug the SDK, enable logging and monitor the console output. You can configure logging as follows:

import { createClient } from "@twilio/flex-sdk";

// Set the desired log level (e.g., TRACE)
const client = await createClient("SDK_TOKEN", {
    logger: { level: "DEBUG" } // Set level (TRACE | DEBUG | INFO | WARN | ERROR)
});

Log Level	Description	Typical Use‑case
TRACE	Verbose, includes every request/response, payloads, stack traces.	Deep debugging.
DEBUG	Shows SDK internals, error details, and important state changes.	General development
INFO	High‑level operational messages (e.g., connection opened).	Monitoring
WARN	Indicates recoverable problems (e.g., retrying a request).	Production alerts
ERROR	Critical failures that halt a feature or request.	Production monitoring

Default – ERROR (ensures you only see real problems in production).