README
Twilio Flex SDK
Table of Contents
About
Flex SDK is a Javascript library that enables businesses to embed Flex's intelligent contact center routing, voice and messaging channels, and realtime reporting capabilities into any user interface. A developer can include Flex SDK in a web application to build contact centre features without requiring in-depth knowledge of the entire Twilio stack.
Important: This package is in active development and is not supported. We do not recommend you use it in your application.
Setup
Requirements
- A Twilio account. Sign up for free here.
- A Twilio Flex Project. See Twilio Flex Documentation.
- Node.js v10+
- NPM v6+ (comes installed with newer Node versions)
Twilio Flex Project
Before you can use the Flex SDK you must set up your Twilio Flex project at https://www.twilio.com. You can find more information about setting up the project at Twilio Flex Documentation page.
Installation
Twilio Flex SDK library is available as a NPM package @twilio/flex-sdk and can be used in any NPM project. The package also includes Typescript type definitions.
The package can be installed using the npm
or yarn
command line clients to your application.
npm install --save @twilio/flex-sdk
or
yarn add @twilio/flex-sdk
Using the Flex SDK
Authentication
In order to instantiate the Flex SDK client, you need an access token. See Configuring SSO and IdP in Flex guide to understand how set up SSO for your Flex project. For development purposes you can obtain an access token using your twilio.com account if you are the a member (or creator) of the Twilio Flex project.
Twilio Flex SDK provides the authentication module that enables obtaining the identity provider URL for SSO as well as fetching and refreshing the access token for the Flex SDK.
If you have set up your Twilio Flex project, you can access the authentication features of the Flex SDK. Just replace "ACXXXXX" with your Twilio Account SID in the following snippet:
import * as FlexSdk from "@twilio/flex-sdk";
const auth = FlexSdk.auth("ACXXXXX");
Identity provider URL with SSO configured
To initiate the authentication flow in the web browser, you need to obtain the identity provider URL from the authentication module. You can optionally provide the redirect URL where to return back after successful authentication:
const idpUrl = await auth.getIdpUrl({ redirectUrl: window.location.href });
(Alternative) twilio.com as the identity provider
Alternatively, if you are an owner, administrator or a member of the Twilio Flex project, then you can sign in using your twilio.com account. Obtain the Twilio identity provider URL for Flex:
import * as FlexSdk from "@twilio/flex-sdk";
const idpUrl = FlexSdk.getTwilioIdpUrl(window.location.port);
Authenticate with the identity provider
Next, you should redirect the web browser to the identity provider URL obtained in the previous step:
window.location.href = idpUrl;
After successful authentication by your identity provider, the web browser will be redirected back to the URL of your application (redirectUrl) and you can parse the access token from the URL:
const token = new URLSearchParams(window.location.search).get("Token");
Create the Flex SDK client
Once you have the access token, you can instantiate the client:
import * as FlexSdk from "@twilio/flex-sdk";
const client = await FlexSdk.createClient(token);
// use client
Once finished using the SDK (for example when logging off), you can destroy the client:
await client.destroy();