Web Chat SDK - Sample App

Important

Prior to installation and configuration, thoroughly review the Official SDK Documentation.

Quick Start Guide

To quickly start using the sample app, perform the following steps:

1. Clone the Repository:

   • Execute the command git clone https://github.com/nice-devone/nice-cxone-chat-web-sample.git to clone the project onto your local machine.

2. Install Dependencies:

   • Navigate to the cloned project's directory.
   • Run npm install to install the required dependencies.

3. Environment Configuration:

   • Locate the .env.sample file in the root directory.
   • Create a copy of this file and rename it to .env.
   • Populate the .env file with the necessary environment variables as per your project's requirements.

4. Application Variant Selection:

   • Choose which variant of the app you wish to run.
   • Assign the REACT_APP_VARIANT variable in your .env file to:
     • MESSENGER for a messaging-focused interface.
     • LIVECHAT for real-time customer support chat.
     • MULTITHREAD for handling multiple chat threads simultaneously.
     • THIRD_PARTY_OAUTH for integrating third-party OAuth providers - it requires channel Authentication to be configured. Supports three OAuth grants, see Third-party OAuth grants.
     • SECURED_COOKIE for messenger or livechat with a secured-cookie session - it requires channel Authentication to be configured. Named SECURED_SESSION before; update the value if you have it in an existing .env.

5. Starting the Application:

   • Run the command npm start from the terminal.
   • Open a web browser and navigate to the URL output in the terminal to access the app.

Understanding the Sample App Variants

Before selecting a variant, familiarize yourself with the differences by reading Understanding the DFO Chat Channels.

Livechat

Livechat facilitates real-time interactions between customers and agents. Set up your Livechat variant by following the instructions in the Set Up Digital First Omnichannel Live Chat guide.

Messenger

The Messenger variant allows for asynchronous communication, where contacts can send messages at any time and await responses. Set up the Messenger variant by consulting the Set Up Digital First Omnichannel Chat Messaging guide.

Multithread

The Multithread variant supports multiple concurrent chat threads, enabling customers to engage in several chats at once, potentially with different agents. Set up is consistent with the Messenger variant, as detailed in the Chat Messaging Setup.

Enabling authorization flow

In the .env file, fill in the following variables:

REACT_APP_OAUTH_ENABLED=1
REACT_APP_OAUTH_PROVIDER_URL="https://example.com/oauth"
REACT_APP_OAUTH_REDIRECT_URI="https://localhost:3000"
REACT_APP_OAUTH_CLIENT_ID=clientId

This will enable the authorization flow. The authorization flow is triggered when the user clicks on the login button. The user will be redirected to the authorization provider URL. After the user logs in, the authorization provider will redirect the user back to the redirect URI. The redirect URI will contain the authorization code in the query string. The authorization code will be exchanged for an access token. The access token will be used to authenticate the user.

REACT_APP_OAUTH_REDIRECT_URI may be any path registered with the provider — http://localhost:5174/callback, for instance. The app has no router: it reads the code out of the query and then rewrites the URL back to /, so the callback path never stays in the address bar.

The code and its PKCE verifier are single-use, so the app keeps neither: each page load starts a fresh authorization request rather than replaying a spent code. That is what the grant requires — a THIRD_PARTY session never reuses a cached transaction token, so the SDK re-exchanges the code on every connection it makes.

Third-party OAuth grants

The THIRD_PARTY_OAUTH variant can demonstrate each of the three OAuth grants the SDK accepts for a THIRD_PARTY secured session. Pick one with REACT_APP_OAUTH_GRANT, or use the matching script:

Grant	REACT_APP_OAUTH_GRANT	Command	What the app does
Authorization code	authorization_code (default)	npm run start:livechat:thirdpartyoauth	Redirects to the IdP, then passes the returned code to connect(code).
Authorization code + PKCE	pkce	npm run start:livechat:thirdpartyoauth:pkce	Mints a code_verifier, sends its S256 challenge to the IdP, then passes the code and its verifier together to connect().
Implicit	implicit	npm run start:livechat:thirdpartyoauth:implicit	Skips the redirect and authenticates with an access token you paste in, via connect({ accessToken, grantType: 'implicit' }).

All three need the OAuth variables from Enabling authorization flow, except the implicit grant, which needs no provider URL or client id because it performs no redirect.

A bare string passed to connect() always means an authorization code, so nothing changes for the default grant on the SDK side. PKCE and the implicit grant need the explicit credentials object.

Why the code and its verifier travel together. ChatSDKOptions can carry authorizationCode, codeVerifier and accessToken, but this sample passes them to connect() instead. Both halves of a PKCE exchange are single-use and only valid as a pair, so a verifier left in the options outlives the code it was minted for and the next connect() would send it with an unrelated code. Passing them together — connect({ authorizationCode, codeVerifier, grantType: 'authorization_code' }) — keeps that from happening.

The redirect request changed for both code grants. The authorize URL now sends scope=openid email profile, access_type=offline and prompt=consent, and no longer sends grant_type (which belongs to the token request, not to this one). Offline access is what makes the IdP issue the refresh token the chat gateway needs; access_type is Google's spelling for it, while other providers use an offline_access scope. Each parameter is only set when the configured provider URL does not already specify it, so you can override any of them there.

The sample never stores a real credential in a file. The access token for the implicit grant is typed into the login screen at runtime.