Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Flex UI Configuration


(warning)

Warning

For Customers building HIPAA-compliant workflows with Flex UI, Customers are required to ensure that there is no PHI in any Properties of Configuration Objects. Details on Configuration Objects and Properties can be found on the official Flex UI documentation(link takes you to an external page). To learn more about building for HIPAA compliance, please visit the latest requirements here(link takes you to an external page).

There are two main ways to define Flex configuration:

  • For Twilio-hosted Flex deployments (flex.twilio.com), use the Flex Configuration API to set the configuration attributes.
  • For customer self-hosted Flex deployments, you can define configuration via both the appConfig.js configuration object or via Flex Configuration API. appConfig.js takes precedence.

Flex UI's configuration allows you to control the way the overall app loads, as well as the behavior of individual Flex Components.

Flex Components can be modified in two ways:

  • via componentProps in the Configuration Object
  • via the defaultProps API

Modifying Configuration for flex.twilio.com

modifying-configuration-for-flextwiliocom page anchor

The appConfig.js configuration object detailed below is not directly accessible when using Twilio-hosted Flex (flex.twilio.com). However, all of the same values can be set as ui_attributes using Flex Configuration REST API.


appConfig.js configuration object

appconfigjs-configuration-object page anchor

In the configuration object, you can define the default properties of your Flex Components. You can also configure properties that are not tied to specific Components.

Example: public/assets/appConfig.js


_32
var appConfig = {
_32
serviceBaseUrl: "https://dancing-owl-1234.twil.io/",
_32
sso: {
_32
accountSid: "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_32
},
_32
sdkOptions: {
_32
chat: {},
_32
insights: {},
_32
voice: {},
_32
worker: {}
_32
},
_32
logLevel: "debug",
_32
colorTheme: {
_32
baseName: "GreyDark",
_32
colors: {},
_32
light: false,
_32
overrides: {}
_32
},
_32
componentProps: {
_32
CRMContainer: {
_32
uriCallback: (task) => task
_32
? `https://www.bing.com/search?q=${task.attributes.name}`
_32
: "http://bing.com"
_32
}
_32
},
_32
router: {
_32
type: "memory",
_32
history: {
_32
initialEntries: [ "/agent-desktop" ]
_32
}
_32
}
_32
};

Some configuration options are only available through the configuration object. Below is the list of all available configuration options.

colorTheme: string | object

colortheme-string--object page anchor

Redefines the color scheme.


_12
appConfig.colorTheme = {
_12
baseName: "GreyDark",
_12
colors: { base2: "red"},
_12
light: true,
_12
overrides: {
_12
MainHeader: {
_12
Container: {
_12
background: "green"
_12
}
_12
}
_12
}
_12
};

componentProps: object

componentprops-object page anchor

Adjusts the properties of separate Flex Components. For a list of available components, see Components.


_10
appConfig.componentProps = {
_10
AgentDesktopView: {
_10
showPanel2: false
_10
}
_10
};

disableTransfers: boolean

disabletransfers-boolean page anchor

Disables conference transfers.


_10
appConfig.disableTransfers = false;

logLevel: string | number (Default: 'error')

loglevel-string--number-default-error page anchor

Sets the specificity of log output. Can be either a number or a string matching:

  • trace or 0
  • debug or 1
  • info or 2
  • warn or 3
  • error or 4
  • silent or 5

_10
appConfig.logLevel = 'info';

Whether to load plugins to modify the Flex UI. Provides an optional URL to override Flex's default plugins source.


_10
appConfig.pluginService = {
_10
enabled: true,
_10
url: "https://example.com/plugins-list.json"
_10
};

Sets the use of browser or in-memory routing for Flex.


_10
appConfig.router = {
_10
type: "memory",
_10
history: {
_10
initialEntries: [ "/agent-desktop" ]
_10
}
_10
};

Flex initializes four standard Twilio SDKs, which are accessible via the Flex Manager. These sdkOptions will pass through as parameters used when initializing those SDKs. (example: Twilio.Device parameters for voice)


_10
appConfig.sdkOptions = {
_10
chat: {},
_10
insights: {},
_10
voice: {},
_10
worker: {}
_10
};

serviceBaseUrl: string

servicebaseurl-string page anchor

Currently not used. This value defaults to the Runtime Domain that is associated with your Twilio Account. This is an easy reference to Functions you may be hosting to power backend API requests.

Enables support for authentication and Single Sign-On using 3rd party Identity Providers such as Okta.


_10
appConfig.sso = {
_10
accountSid: "ACxxx" // AccountSid of your Twilio project
_10
};

Currently not used.


You may also configure default properties for components within a Plugin by using the React defaultprops API programmatically:

componentProps: { [Component Name]: { [Prop Name]: [PropValue] } }

Example


_10
flex.CRMContainer
_10
.defaultProps
_10
.uriCallback = (task) => task
_10
? `https://www.bing.com/search?q=${task.attributes.name}`
_10
: "http://bing.com/";
_10
_10
flex.MainHeader
_10
.defaultProps
_10
.logoUrl = "https://static0.twilio.com/marketing/bundles/archetype.alpha/img/logo-wordmark--red.svg";

Below is the list of Flex Components and their defaultProps that can be modified.

Flex Agent and Supervisor UI

flex-agent-and-supervisor-ui page anchor

CRMContainer

crmcontainer page anchor

uri: string

The URI that is displayed in the CRM container. This URI must be generated by the uriCallback.

uriCallback: (task: Task) => string

A callback that returns a URI to be displayed in the CRM container based on a selected task. If you want to replace the CRMContainer component entirely, use the replace method instead.


_10
flex.CRMContainer
_10
.defaultProps
_10
.uriCallback = (task) => task
_10
? `https://www.bing.com/search?q=${task.attributes.name}`
_10
: "http://bing.com/";

logoUrl: string

The logo URL displayed in the main top header.

logoUrl: string

The URL for the login view image (by default the Twilio Logo).

staticTaskFilter: (task: Task) => boolean

A callback function describing a tasks' presence and order in the Flex UI. If a task returns true (i.e., it's a static or "pinned" Task for the User's Flex UI) it will appear in the upper section of the TaskList Container.

By default, both live and incoming calls are treated as static Tasks.

itemSize: 'Small' | 'Large' | 'LargeSelected'

The task list item size. Legal values include:

  • Small (default) - regular task list item size
  • Large - all task list items are 156px bigger in height, allowing for custom info below the default task list item content via TaskExtraInfo template
  • LargeSelected - selected tasklist item is shown as Large , others as Small

keepSideNavOpen: boolean

Indicates whether the Sidebar preview panel should be always visible. Default is false, which shows the preview only after the whole app is wide enough.

showNotificationBar: boolean

If set to false, NotificationBar notifications won't be shown. Read more about Notifications on the Notifications Framework page.

showLiveCommsBar: boolean

Displays an incoming call bar for views different from Agent UI.

compareFunction: (task1: Task, task2: Task) => number

Callback to control how tasks should be sorted in the task list. A negative number means task1 should be above task2. A positive number that task1 should be below task2. 0 indicates equal priority.

showPanel2: boolean

When set to false, will completely remove the right side area of the Agent View, where usually CRM resides, including the splitter control separating left and right side areas.

splitterOptions: object

Allows specification of the default values for the main horizontal splitter in Agent Desktop view (separates the left view from the CRM area to the right). Values can either be pixels or % values.


_10
{
_10
initialFirstPanelSize?: string;
_10
minimumFirstPanelSize?: string;
_10
minimumSecondPanelSize?: string;
_10
}

AgentDesktopView.Panel1

agentdesktopviewpanel1 page anchor

splitterOrientation: 'auto' | 'vertical' | 'horizontal' (Default: auto)

Determines whether the orientation of the content will be vertical, horizontal, or auto (automatic) based on the content size.

tablePlaceHolder: ReactNode

The React element to display when the list of agents is empty.

initialCompareFunction: (worker1: IWorker, worker2: IWorker) => number

Callback to control how agents should be sorted in the agent list. A negative number means worker1 should be above worker2. A positive number that worker1 should be below worker2. 0 indicates equal priority.

showSkill: boolean

Display the skills section for the agent details.

details: Array<WorkerProfileDetail>

Add details to the agent's profile.

icon: string | ReactNode

An image displayed in the task header of a task. If you provide an icon string, it needs to match an icon name from a list of Flex Icons.

ActionsComponent: ComponentType<{ task: ITask }>

An action component displayed in the header of a task. Defaults to an "end task" button.

titleTemplateContext: object

Context object used for rendering the task title template.

alignment: 'left' | 'center'

Defines how the tab header is aligned.

Chat/Messaging Component for Flex UI

chatmessaging-component-for-flex-ui page anchor

These properties apply to both the Flex Agent Desktop UI and the Twilio WebChat UI - everywhere the Chat/Messaging component is used.

avatarCallback: (identity: string) => string

Callback function to return the avatar URL of a member.

memberDisplayOptions: object

Allows overriding chat participant names, e.g. setting agent to Agent and customer to Customer.


_10
{
_10
yourDefaultName?: string;
_10
theirDefaultName?: string;
_10
yourFriendlyNameOverride?: boolean;
_10
theirFriendlyNameOverride?: boolean;
_10
}

messageStyle: 'Rounded' | 'Squared' | 'Minimal'

Defines the visual style of the message area. Options are Rounded, Squared, Minimal.

showReadStatus: boolean

Controls whether to show the message read indicator.

showTypingIndicator: boolean

Controls whether to show "[SomeOne] is typing" in chat.

showWelcomeMessage: boolean

Controls whether to show the welcome message at the beginning of the conversation.

welcomeMessageText: string

The welcome message text to display.

showTrayOnInactive: boolean

Displays the message tray component, indicating that the chat is no longer active whenever channel status is inactive.

useFriendlyName: boolean

Overrides the chat participant name with a friendly name.

areaStyle: 'Bubble' | 'Line' | 'Boxed'

The visual style of the text input element. Options are Bubble, Line, Boxed.

returnKeySendsMessage: boolean

Whether pressing the return key should send a message.

showButton: boolean

Display a 'Start new chat' button in the tray.

onButtonClick: () => void

A handler for a 'Start new chat' button click.


Configure Authentication and Single Sign-On

configure-authentication-and-single-sign-on page anchor

To configure an integration with an Identity Provider and enable Single Sign-On, set the


_10
appConfig.sso = {
_10
accountSid: string; // AccountSid of your Twilio Project
_10
loginPopup: boolean; // whether to launch IdP login in new window
_10
loginPopupFeatures: string; // standard window.open() features param to be applied to popup window
_10
};

The session state in Redux Store will contain:

  • loginState - state of the login
  • ssoTokenPayload - the token payload from the Identity Provider
  • identity - user identity used for SSO procedure
  • loginError - an error occurred during login
  • loginHandler - an object that contains parameters of the login procedure

Configuring CRM Integration

configuring-crm-integration page anchor

CRM integrated into an iFrame controlled by Flex

crm-integrated-into-an-iframe-controlled-by-flex page anchor

uriCallback: (task: ITask) => string

Callback function which is called every time an active task is changed. You can provide a CRM URI for that particular task or a constant URI.


_10
flex.CRMContainer
_10
.defaultProps
_10
.uriCallback = (task) => task
_10
? `https://www.bing.com/search?q=${task.attributes.name}`
_10
: "http://bing.com/";


Rate this page: