@microsoft/omnichannel-chat-widget v1.6.5-main.cf61c9e

Omnichannel Live Chat Widget UI Components

\

@microsoft/omnichannel-chat-widget is a React-based UI component library which allows you to build your own live chat widget experience using @microsoft/omnichannel-chat-sdk.

NEW! Check out our new Developer Guide, which has detailed explanations of all component interfaces accompanied with sample code.

Table of Contents

1. Introduction
2. Installation
3. Example Usage
4. Components
5. See Also

Introduction

Omnichannel Live Chat Widget UI Components offers a re-usable component-based library to help create a custom chat widget that can be connected to the Dynamics 365 Customer Service experience.

For more information about Live Chat Widget, see here.

Installation

npm i @microsoft/omnichannel-chat-sdk
npm i @microsoft/omnichannel-chat-widget

or

yarn add @microsoft/omnichannel-chat-sdk
yarn add @microsoft/omnichannel-chat-widget

The repo also contains the @microsoft/omnichannel-chat-components package, which is a collection of UI components. The @microsoft/omnichannel-chat-widget package is an integration of the Chat SDK and the UI components. To install the UI components separately, do

npm i @microsoft/omnichannel-chat-components

or

yarn add @microsoft/omnichannel-chat-components

Example Usage

The basic example below takes in the <LiveChatWidget/> component along with the Chat SDK to create a customized Omnichannel chat widget.

:warning: The Chat SDK has to be initialized before being passed in.

import * as React from "react";

import { LiveChatWidget } from "@microsoft/omnichannel-chat-widget";
import { OmnichannelChatSDK } from "@microsoft/omnichannel-chat-sdk";
import ReactDOM from "react-dom";
//Below version numbers will help us to troubleshoot issues with specific package
import { version as chatSdkVersion } from "@microsoft/omnichannel-chat-sdk/package.json";
import { version as chatWidgetVersion } from "@microsoft/omnichannel-chat-widget/package.json";
import { version as chatComponentVersion } from "@microsoft/omnichannel-chat-components/package.json";

const render = async () => {
    const omnichannelConfig = {
        orgId: "00000000-0000-0000-0000-000000000000", // dummy config
        orgUrl: "https://www.org-url.com", // dummy config
        widgetId: "00000000-0000-0000-0000-000000000000" // dummy config
    };
    const chatSDK = new OmnichannelChatSDK(omnichannelConfig);
    await chatSDK.initialize(); // mandatory
    const chatConfig = await chatSDK.getLiveChatConfig();
    const liveChatWidgetProps = {
        styleProps: {
            generalStyles: {
                width: "700px",
                height: "800px"
            }
        },
        headerProps: {
            controlProps: {
                hideMinimizeButton: true
            }
        },
        chatSDK: chatSDK, // mandatory
        chatConfig: chatConfig // mandatory
    };

    ReactDOM.render(
        <LiveChatWidget {...liveChatWidgetProps}/>,
        document.getElementById("my-container")
    );
};

render();

A javascript sample widget can be found in this repo here. To build it, do yarn build-sample or yarn build-sample:dev from chat-widget project root.

A typescript sample widget can be found here. To build it, do yarn install then yarn build then yarn start from typescript sample project root. See Create LiveChatWidget with Webpack5 and TypeScript for additional typescript sample project resources.

Components

For a detailed guide on how to customize each component with sample usages, please see our new Developer Guide.

Stateless UI Components

These are components that are included in the @microsoft/omnichannel-chat-components package.

:warning: Because the components extend Microsoft's Fluent UI components, the base interface for all the styleProps in the above table is IStyle, which extends the IRawStyleBase interface, which is the most useful reference.

Stateful Components

Some of the interfaces listed in the Stateless table have Stateful counterparts defined in the @microsoft/omnichannel-chat-widget package. For example, IConfirmationPaneStatefulProps extends IConfirmationPaneProps with additional attributes that only makes sense in the stateful context.

Custom Components

There are two ways to custom the components provided in the library - 1) Replacing components using ComponentOverrides, and 2) Adding custom components in header and footer.

ComponentOverrides

Most sub-components and the default panes provided can be overriden. Components have "componentOverrides" as part of props interface, which consists of ReactNodes or strings for each part of the component. For example, the "ProactiveChatPane" component has a close button, and the close button can be overriden by creating a custom react node and setting it to the "closeButton" attribute of "componentOverrides" interface that is part of the props.

const customButton = (
    <button style={{
        background: "green",
        height: "80px",
        margin: "30px 15px 0 0",
        padding: "10px",
        width: "160px"
    }}>
        This is a custom button
    </button>
);

const liveChatWidgetProps = {
    proactiveChatPaneProps: {
        componentOverrides: {
            closeButton: customButton
        };
    };
}

Custom Components in Header and Footer

Header's and Footer's child components consist of three parts:

1. "leftGroup" - adding child components at the left of the Header/Footer
2. "middleGroup" - adding child components in the middle of the Header/Footer
3. "rightGroup" - adding child components at the right of the Header/Footer

By default Header has the header icon and title on the left and minimize and close buttons on the right, and Footer has Download Transcript and Email Transcript buttons on the left and audio notification button on the right. These components can be overriden with ComponentOverrides. In addition, other custom child components can be added to both Header and Footer by creating custom react nodes and adding them to attributes "leftGroup", "middleGroup" or "rightGroup" of "controlProps".

const buttonStyleProps: IButtonStyles = {
    root: {
        color: "blue",
        height: 25,
        width: 25,
    }
};

const calendarIcon: IIconProps = { iconName: "Calendar" };
const calendarIconButton = <IconButton
    key="calendarIconButton"
    iconProps={calendarIcon}
    styles={buttonStyleProps}
    title="Calendar">
</IconButton>;

const emojiIcon: IIconProps = { iconName: "Emoji2" };
const emojiIconButton = <IconButton
    key="emojiIconButton"
    iconProps={emojiIcon}
    styles={buttonStyleProps}
    title="Sentiment">
</IconButton>;

const uploadIcon: IIconProps = { iconName: "Upload" };
const uploadIconButton = <IconButton
    key="uploadIconButton"
    iconProps={uploadIcon}
    styles={buttonStyleProps}
    title="Upload">
</IconButton>;

const customizedFooterProp: IFooterProps = {
    controlProps: {
        leftGroup: { children: [uploadIconButton] },
        middleGroup: { children: [calendarIconButton] },
        rightGroup: { children: [emojiIconButton] }
    }
};

:pushpin: Note that WebChat hooks can also be used in any custom components.

See Also

Customizations Dev Guide\ Telemetry\ Create LiveChatWidget with Webpack5 and TypeScript\ Omnichannel Features\ How to Add Visual Regression Tests\ Security\ Third Party Cookie Support\ Storybook