Intility Chat

Intility Chat is a React Component that wraps Twilio's WebChat UI with basic configuration and theme.

Purpose

Intility Chat makes it easy for third parties to implement a customized version of Flex WebChat UI that is tailored to fit our design guidelines and then deliver an consistent user experience to the end user.

Intended consumers

This component is intended for customer facing web portals that isn't developed by Intility, but we use in production.

Main technologies

This project utilizes among others the following libraries:

React
TypeScript
Babel
@twilio/flex-webchat-ui
have a look in package.json for complete list of dependencies

Getting Started

Installation

NPM

npm i @intility/flex-chat

Required Configuration

Environment variables

NOTE: If you haven't got these keys, please contact your provided Intility Contact.

REACT_APP_ACCOUNT_SID=xxxxx
REACT_APP_FLOW_SID=xxxxx

Properties

type ConfigProps = {
    flexFlowSid: string;
    flexAccountSid: string;
    user: ChatContext; // User context
    loglevel?: 'debug' | 'superDebug';
    closeOnInit?: boolean;
    theme?: ThemeConfig;
    preEngagementFormMessage?: MultiLangText;
    user: ChatContext;
};

type FlexChatProps = {
    config: ConfigProps;
    isDarkMode: boolean;
    isDisabled?: boolean;
};

NOTE: The properties marked with ? is optional.

Authentication

Since this package initializes an chat session with an Intility Support Agent there is a requirement to provide a authenticated users details in the config object.

NOTE: This components does not give other requirements to authentication implementations but to provide the components with these values.

type AllowedValues = string | number | boolean | undefined | null | string[] | number[] | boolean[] | object;

type ChatContext = { 
    // Value to be displayed as the sender in the chat. 
    // This should be the authenitcated users full name if available, but fallback to the users login EMail.
    userPrincipalName: string;
    
    // The email used for login for the user
    mail: string;
    
    // Telephone number for the user
    mobilePhone: string;
    
    // The preferred language for the user. Should follow ISO 639-1 Code
    preferredLanguage: string;
    
    // Other user context is welcome and can be sent as other optional properties.
    [key: string]: AllowedValues;
};

Example Configuration

import React, { useState } from 'react';
import ReactDOM from 'react-dom';
import { FlexChat, ConfigProps } from '@intility/flex-chat/dist/index';

const App: React.FC = (props) => {
    const [isDarkMode, setIsDarkMode] = useState(false);

    const config: ConfigProps = {
        flexAccountSid: process.env.REACT_APP_ACCOUNT_SID,
        flexFlowSid: process.env.REACT_APP_FLOW_SID,
        user: {
            userPrincipalName: 'ola.normann@intility.no',
            mail: 'ola.normann@intility.no',
            mobilePhone: '815-493-00',
            preferredLanguage: 'nb-NO'
        },
    };

    return (
        <FlexChat config={config} isDarkMode={isDarkMode} isDisabled={false} /> 
    );
};

ReactDOM.render(<App />, document.getElementById('root'));

Optional Configuration

Keep the chat closed on page load

If you want to have the Chat component closed on initialization you can set the property named closeOnInit to true in the config object. Default behavior is for the chat component to expand on page load.

NOTE: If there is an ongoing chat session the chat window will always expand on page load.

const config: ConfigProps = {
    // ...required config
    closeOnInit: true
};

PreEngagementFormMessage

If you want to add a message to the start page you can add a property named preEngagementFormMessage to the config object.

This object is of type MultiLangText and consists of an English (en) and Norwegian (no).

const config: ConfigProps = {
    // ...required config
    preEngagementFormMessage: {
        en: 'Du kan nå teknikere på ansvarlig avdeling innenfor tidspunktene 08:00 - 16:00 (CET/CEST)',
        no: 'You can reach technicians in the responsible department within the hours 08:00 - 16:00 (CET / CEST)';
    },
};

Theming

You can change CSS properties on the MainContainer, EntryPoint and CloseButton components to make them fit your experience, e.g. hide the EntryPoint button or change the height, width or render properties like position.

MainContainer: The expanded chat box.
EntryPont: Toggle button in the bottom right corner.
CloseButton: Toggle button on the top bar in the MainContainer

NOTE: some properties will be default from Twilio or overwritten by Intility's setup of the chat component.

type ThemeConfig = {
    MainContainer?: CSSProps;
    EntryPoint?: CSSProps;
    CloseButton?: CSSProps;
};

const config: ConfigProps = {
    // ...required config
    theme: {
        MainContainer: {
            width: '800px',
            height: '87vh',
            '@media only screen and (min-width: 1415px)': {
                width: `1080px`,
            },
        },
        // Display EntryPoint for small devices (i.e. Smart phones)
        EntryPoint: {
            '@media only screen and (min-width: 767px)': {
                display: 'none !important',
            },
        },
        // Display CloseButton for small devices (i.e. Smart phones)
        CloseButton: {
            '@media only screen and (min-width: 767px)': {
                display: 'none',
            },
        },
    },
};

Usage

Hooks

This component can be interacted with using integrated useChatActions hook.

type UseChatActionsFuncs = {
    setInputFieldContent: (body: string) => Promise<unknown>;
    setAndSendInputFieldContent: (body: string) => Promise<unknown>;
    toggleChatVisibility: () => Promise<unknown>;
    hasUserReadLastMessage: () => Promise<boolean>;
    isChatOpen: () => Promise<boolean>;
};

Intility / IntilityFlexChat