Menu

UI Configuration

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:

Modifying Configuration for flex.twilio.com

The Configuration Object detailed below is not directly accessible when using flex.twilio.com. However, all of the same values can be set as ui_attributes using Flex's Configuration REST API.

When POST-ing configuration values to ui_attributes, a full JSON object must be provided. This means you should:

  • GET the existing configuration
  • Modify the JSON to add/update/remove your desired properties
  • POST the result as the new configuration
        
        
        
        

        Make any updates to the updated configuration. For example, you can set the ui_attributes property to the value {"logLevel": "debug"}. Once you've made your changes, POST the new object as your configuration

        ui_attributes is loaded even for self-hosted deployments of Flex. Any conflicting properties provided in an appConfig configuration object are given precedence when Flex loads.

              
              
              
              

              Configuration Object

              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

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

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

              colorTheme: string | object

              Redefines the color scheme.

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

              componentProps: object

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

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

              disableTransfers: boolean

              Disables conference transfers.

              appConfig.disableTransfers = false;
              

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

              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
              appConfig.logLevel = 'info';
              

              pluginService: object

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

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

              router: object

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

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

              sdkOptions: object

              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)

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

              serviceBaseUrl: string

              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.

              sso: object

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

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

              language: string

              Currently not used.

              React defaultProps API

              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

              flex.CRMContainer
                .defaultProps
                .uriCallback = (task) => task
                  ? `https://www.bing.com/search?q=${task.attributes.name}`
                  : "http://bing.com/";
              
              flex.MainHeader
                .defaultProps
                .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

              CRMContainer

              uri: string

              The URI that is displayed in the CRM container.

              uriCallback: (task: Task) => string

              A callback that returns a URI to be displayed in the CRM container based on a selected task.

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

              MainHeader

              logoUrl: string

              The logo URL displayed in the main top header.

              LoginView

              logoUrl: string

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

              TaskListContainer

              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 88px 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

              MainContainer

              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.

              TaskList

              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.

              AgentDesktopView

              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.

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

              AgentDesktopView.Panel1

              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.

              AgentsDataTable

              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.

              WorkerCanvas

              showSkill: boolean

              Display the skills section for the agent details.

              WorkerProfile

              details: Array<WorkerProfileDetail>

              Add details to the agent's profile.

              TaskCanvasHeader

              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.

              Tabs

              alignment: 'left' | 'center'

              Defines how the tab header is aligned.

              Chat/Messaging Component for Flex UI

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

              MessagingCanvas

              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.

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

              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.

              MessageListItem

              useFriendlyName: boolean

              Overrides the chat participant name with a friendly name.

              MessageInput

              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.

              MessageCanvasTray

              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

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

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

              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

              CRM integrated into an iFrame controlled by Flex

              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.

              flex.CRMContainer
                .defaultProps
                .uriCallback = (task) => task
                  ? `https://www.bing.com/search?q=${task.attributes.name}`
                  : "http://bing.com/";
              
              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.

              Thank you for your feedback!

              We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

              Sending your feedback...
              🎉 Thank you for your feedback!
              Something went wrong. Please try again.

              Thanks for your feedback!

              Refer us and get $10 in 3 simple steps!

              Step 1

              Get link

              Get a free personal referral link here

              Step 2

              Give $10

              Your user signs up and upgrade using link

              Step 3

              Get $10

              1,250 free SMSes
              OR 1,000 free voice mins
              OR 12,000 chats
              OR more