Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/intility/intilityflexchat
Intility Chat is a React Component that wraps Twilio's WebChat UI with basic configuartion and theme.
https://github.com/intility/intilityflexchat
flex-webchat-ui intility npm react twilio
Last synced: 1 day ago
JSON representation
Intility Chat is a React Component that wraps Twilio's WebChat UI with basic configuartion and theme.
- Host: GitHub
- URL: https://github.com/intility/intilityflexchat
- Owner: Intility
- Created: 2020-05-15T16:04:32.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-11-10T12:07:15.000Z (about 1 year ago)
- Last Synced: 2024-10-29T22:47:52.445Z (19 days ago)
- Topics: flex-webchat-ui, intility, npm, react, twilio
- Language: TypeScript
- Homepage:
- Size: 1.29 MB
- Stars: 11
- Watchers: 3
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Intility Chat
Intility Chat is a React Component that wraps [Twilio's WebChat UI](https://www.npmjs.com/package/@twilio/flex-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](https://reactjs.org/)
* [TypeScript](https://www.typescriptlang.org/)
* [Babel](https://babeljs.io/)
* [@twilio/flex-webchat-ui](https://www.npmjs.com/package/@twilio/flex-webchat-ui)
* have a look in [package.json](package.json) for complete list of dependencies
## Getting Started
### Installation
#### NPM
```bash
npm i @intility/flex-chat
```
### Required Configuration
#### Environment variables
**NOTE:** If you haven't got these keys, please contact your provided Intility Contact.
```env
REACT_APP_ACCOUNT_SID=xxxxx
REACT_APP_FLOW_SID=xxxxx
```
#### Properties
```ts
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.
```ts
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
```ts
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: '[email protected]',
mail: '[email protected]',
mobilePhone: '815-493-00',
preferredLanguage: 'nb-NO'
},
};
return (
);
};
ReactDOM.render(, 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.
```ts
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).
```ts
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.
```ts
type ThemeConfig = {
MainContainer?: CSSProps;
EntryPoint?: CSSProps;
CloseButton?: CSSProps;
};
```
```ts
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.
```ts
type UseChatActionsFuncs = {
setInputFieldContent: (body: string) => Promise;
setAndSendInputFieldContent: (body: string) => Promise;
toggleChatVisibility: () => Promise;
hasUserReadLastMessage: () => Promise;
isChatOpen: () => Promise;
};
```
## Illustration
