@tenfold/web-client-sdk

v1.0.42

Published

a month ago

Tenfold Web Client SDK

Downloads

Tenfold SDK Client Library

Use this package to utilize tenfold features and build your own integration app / UI on top of it. The package is designed to be used in browser alike environments (window object required).

Installation guide

Node

Node - defined in package.json - Node.js 20.11.1

You can use nvm or fnm to install this version.

Rxjs

There is a single peer dependency -> rxjs. Usage of this package requires knowledge of rxjs (https://rxjs-dev.firebaseapp.com/guide/overview) and concept of Observables.

Typescript support

Tenfold SDK Client Library is written with Typescript. This package includes TypeScript declarations for the Tenfold SDK Client Library. We support projects using TypeScript versions >= 4.1.

Installation

Use npm or yarn to install the Tenfold SDK Client Library:

> npm install @tenfold/web-client-sdk

> yarn add @tenfold/web-client-sdk

Architecture overview

To utilize Tenfold SDK Client Library you will need to instantiate a WebClient. It appends to DOM an extra iFrame that encapsulates most of the logic and state and communicates with this iFrame to dispatch actions and listen for data changes via rxjs observables.

Usage

WebClient

To start using Tenfold SDK Client Library you will need to use WebClient.

import { WebClient as TenfoldWebClient } from "@tenfold/web-client-sdk";

const webClient = new TenfoldWebClient({
    sharedWorker: false,
    iframeDivId: "some-sdk-custom-id",
    sdkUrl: "https://app.tenfold.com/sdk.html",
});

<html>
    <head>
        ...
    </head>
    <body>
        <div id="some-sdk-custom-id"></div>
    </body>
</html>

WebClient configuration

When you instantiate WebClient you may pass an optional configuration object. All these properties are optional.

Configuration `sdkUrl` option (optional)

As described in Architecture overview, WebClient requires an iFrame to communicate with. As a default value we pass https://app.tenfold.com/v${sdkVersion}-sdk/sdk.html. As Tenfold, we provide per each sdk version matching iframe.src. So if you have @[email protected] and you don't define this config property, WebClient should attach to your DOM a div with an iframe that src is https://app.tenfold.com/v1.0.24-sdk/sdk.html. This may be exposed as a configuration property for testing purposes but this is not recommended. Latest version is hosted at https://app.tenfold.com/sdk.html.

Configuration `iframeDivId` option (optional)

You can pass id attribute value of your div in HTML. The default value is __tenfold__sdk__iframe__. You can only define <div/> tags for this purpose in your code to add an iFrame to dedicated <div/> in DOM. For both - default or custom provided iframeDivId - WebClient will look into the DOM and if it finds <div/> with iframeDivId value it will insert iframe with src attribute and sdkUrl value. If it doesn't find a <div/> it will create one and prepend to document.body and then insert an iFrame.

Configuration `sharedWorker` option (optional)

Use a shared worker (SW) (https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker) for underlying mechanism in iFrame. Default value is true. Shared worker is not implemented in all browsers, so even if this configuration option is enabled we cannot ensure that it will bootstrap in this mode. WebClient will fallback to non shared worker mode in that case.

This mechanism gives a better UX in your app and better performance. Entire logic and state management in iFrame is bootstrapped only once and iFrame is only a proxy to SW. When SW is disabled, each iFrame bootstraps it's own instance of logic and state, so the UX accross many tabs in browser will not be exact the same. We recommend to check the behavior of your implementation with both values.

Configuration `sharedWorkerContext` option (optional)

Only applies when the Shared Worker (SW) is enabled and implemented in the runtime environment. It defines a context for SW, so many diffrent apps using this SDK will not attach to the same SW. As a default it's sdk_${window.location.origin}. So different apps (under diffrent domains) should not attach to the same SW. You can define your own SW context by passing this option. In Chrome you can inspect your SWs under chrome://inspect/#workers.

WebClient methods and observables

WebClient destroy

When you create a new instance of WebClient, it's important to remember to destroy it too. If you create it once for entire life of your app you can skip this, however, if you create it in some module and your intention is to clean it up when you destroy that module - use destroy method. It ensures that all inner rxjs subscriptions will be completed and iframe injected into given div will be removed from DOM. Your code should look like:

 yourDestroyFn() {
    if (this.webClient) {
      this.webClient.destroy();
      this.webClient = null;
    }
  }

WebClient isReady$

It's an observable that will notify you that everything is established and works (communication with iframe i.e.). You should wait with any manipulations via WebClient until isReady$ emits true value.

webClient.isReady$
    .pipe(
        takeUntil(this.isDestroyed$),
        filter((isReady) => !!isReady),
        tap(() => {
            console.log("WebClient and Iframe are ready!");
        })
    )
    .subscribe();

WebClient isAuthenticated$

It's an observable that will notify you that user is authenticated to Tenfold.

webClient.isAuthenticated$
    .pipe(
        takeUntil(this.isDestroyed$),
        filter((isAuthenticated) => !!isAuthenticated),
        tap(() => {
            console.log("User is authenticated to Tenfold!");
        })
    )
    .subscribe();

WebClient domain services

WebClient has several domain services. Those are responsible for dispatching some actions to iframe (via methods) and listen for data state changes from iframe (via rxjs observables). All of the domain services are only available after the isReady$ observable emits true value, before that those will be undefined.

WebClient.env domain service

It exposes isReady$ observable that indicates iframe's services to be ready when emits true. WebClient.isReady$ is better to use, cause ensures that both sides of communication are ready to use. Exposes also setEnvironment mainly to set environmentUrl that we want to use to communicate with Tenfold APIs (for switching between dev and prod envs). setEnvironment method can be used only when isReady$ emits true value and user is authenticated - otherwise will throw an error. currentEnvironment$ exposes observable with a current state of env configuration - the most important property of this state is environmentUrl of course, which indicates which one is currently set.

webClient.env.currentEnvironment$
    .pipe(
        takeUntil(this.isDestroyed$),
        map(({ environmentUrl }) => environmentUrl),
        tap((environmentUrl) => {
            console.log("environmentUrl changed to:", environmentUrl);
        })
    )
    .subscribe();

webClient.env.setEnvironment({ environmentUrl: "https://api.tenfold.com" });

WebClient.auth domain service

You can listen for user data (can be User or undefined depends on WebClient.isAuthenticated$ value):

webClient.auth.user$
    .pipe(
        takeUntil(this.isDestroyed$),
        filter((user) => !!user),
        map(({ username }) => username),
        tap((username) => {
            console.log("user name is:", username);
        })
    )
    .subscribe();

You can also get phoneSystem$ returns string or null (just a sugar selector on top of user$ one):

webClient.auth.phoneSystem$
    .pipe(
        takeUntil(this.isDestroyed$),
        filter((phoneSystem) => !!phoneSystem),
        tap((phoneSystem) => {
            console.log("Your phone system is:", phoneSystem);
        })
    )
    .subscribe();

It exposes login method for login with credentials:

await webClient.auth.login({
    username: "[email protected]",
    password: "********",
});

You can logout at any time:

await webClient.auth.logout();

You can also implement SSO flow:

const identifier = "[email protected]";
const loginType = "openid_flow"; // 'saml_flow' | 'openid_flow';
webClient.auth
    .startSSOFlow(identifier, loginType)
    .pipe(
        tap(({ redirectTo }) => {
            window.open(redirectTo);
        })
    )
    .subscribe();

startSSOFlow(identifier, loginType) takes two params. identifier is SSO domain or username. loginType is "saml_flow" when you want to perform domain login, "openid_flow" when you want to perform open id connect login. Underneath it starts long polling for user authentication status change (it stops when user becomes authenticated or call startSSOFlow once again).

WebClient.agentStatus domain service

In login flow sometimes not only tenfold authentication is required - you need to perform a login specific for a given phone system. You can do this with login method:

await webClient.agentStatus.login({
    agentId,
    password,
    extension,
});

To perform that you can check for getAgentSettings to get some data to choose from:

webClient.agentStatus
    .getAgentSettings()
    .pipe(
        takeUntil(this.isDestroyed$),
        tap((agentSettings) => {
            console.log("Your prefill agent id is:", agentSettings?.agentId);
            console.log(
                "If your hasPassword is truthy you can set your password to '▪▪▪▪▪▪▪▪'",
                agentSettings?.hasPassword
            );
            console.log(
                "Your preferredExtension is:",
                agentSettings?.preferredExtension
            );
        })
    )
    .subscribe();

After you login you can implement widget with agent status selection:

webClient.agentStatus.agentStatuses$
    .pipe(
        takeUntil(this.isDestroyed$),
        tap((agentStatuses) => {
            console.log(
                "Your options list of agentStatuses is:",
                agentStatuses
            );
        })
    )
    .subscribe();

webClient.agentStatus.currentAgentStatus$
    .pipe(
        takeUntil(this.isDestroyed$),
        tap((currentAgentStatus) => {
            console.log("Your current agentStatus is:", currentAgentStatus);
        })
    )
    .subscribe();

const agentStatusIJustChose = {
    id: "some-id-of-option-from-above-agentStatuses",
    type: "busy",
};
if (!agentStatusIJustChose.readOnly) {
    await webClient.agentStatus.save(agentStatusIJustChose);
}

You can always get current agent login data with getAgentData and use it for logout.

const agentData = await webClient.agentStatus.getAgentData();
webClient.agentStatus.logout(agentData);

IMPORTANT: to implement this flow you will need some parts from WebClient.callControls.

WebClient.interaction domain service

In Tenfold we have an Interaction that is a common type for call, chat, etc. To handle data related to this important scope we have WebClient.interaction domain service.

You can listen for interactions collection changes with webClient.interaction.interactions$ observable. There is also webClient.interaction.newInteraction$ that emits a new Interaction only when it's new one in webClient.interaction.interactions$. We expose also a sugar observable on top of webClient.interaction.newInteraction$ that distinguish call and chat accordingly: webClient.interaction.newCall$ and webClient.interaction.newChat$.

We also track changes and in case if any interaction in collection change we emit a value via webClient.interaction.interactionChange$. It's suitable to handle changes of each one in time.

There is also a sugar observable webClient.interaction.interactionStatusChange$ that emits { id: string, status: InteractionStatus } when for any Interaction from collection its status has changed.

webClient.interaction.interactions$
    .pipe(
        takeUntil(this.isDestroyed$),
        tap((interactions) => {
            console.log(
                "Here is my always up to date list of latest interactions:",
                interactions
            );
        })
    )
    .subscribe();

WebClient.callControls domain service

You can check with webClient.callControls.callControlsEnabled$ observable if call controls for your agent are enabled.

To check if you have an agent with phone system that requires login you can use webClient.callControls.hasSessionCreationPhoneSystem$ observable or webClient.callControls.hasSessionCreationPhoneSystem getter.

To check if you have an agent that requires login you can use webClient.callControls.hasAgentLogin$ observable or webClient.callControls.hasAgentLogin getter.

The easiest and most safe solution to check if login is required (as combination of two above) is to use webClient.callControls.hasSessionCreation$ observable or webClient.callControls.hasSessionCreation getter. This one is the one you need to implement the proper agent login flow. Check: WebClient.agentStatus domain service.

To check if the session is active you can use webClient.callControls.sessionActive$ observable or webClient.callControls.hasSessionActive getter.

The easiest way to logout on agent level is to use webClient.callControls.destroySession. It will logout you from agent login session, but not from Tenfold. If you have webClient.callControls.hasSessionActive truthy and you would like to perform full logout:

await webClient.callControls.logout();
await webClient.auth.logout();

webClient.callControls has a bunch of methods responsible for this domain like:

dial(phoneNumber: string, source: CTDRequestSource, pbxOptions?: DialPbxOptions) with a parameters to setup any dial you want like:

const phoneNumber = "123456789";
webClient.callControls.dial(phoneNumber, "dialer", { type: "external" });

As name of this service suggests it's oriented on Interaction of call type. By tracking webClient.interaction.newCall$ you can answerCall(call: Call),
hangupCall(call: Call, force?: boolean),
switchCall(call: Call),
holdCall(call: Call),
muteCall(call: Call),
unmuteCall(call: Call),
startRecording(call: Call),
stopRecording(call: Call),
retrieveCall(call: Call),
sendDtmf(call: Call, sequence: string).

All above are self explanatory.

WebClient.features domain service

This domain service is responsible for checking availability for features defined in Tenfold. Depends on organization you belong and account configuration you can have access to only part of features.

The most basic observable to check tenfold feature setting is onFeature.

webClient.features
    .onFeature("socialProfile")
    .pipe(
        takeUntil(this.isDestroyed$),
        tap((feature: Feature) => {
            this.socialProfilesEnabled = feature && feature.status === "active";
        })
    )
    .subscribe();

Sugar observable for status extraction is onFeatureStatus observable. Sugar observable for property chain of feature is onFeaturePreference<T>(featureName: string, path: string, defaultValue: T) observable.

Features that are user related can be found under onUserFeature. Features that are organization related can be found under onOrganizationFeature.

On phone system level to check for feature use: webClient.features.onIntegrationCapability. Sugar observable for supports extraction is: webClient.features.onIntegrationCapabilitySupport.

Combination of onFeatureStatus and onIntegrationCapabilitySupport is: onIntegrationCapabilityAndFeatureSupport (logical AND).

WebClient.agentDirectory domain service

We expose agentDirectory to let navigate through tree of agent-alike objects. Method fetchAgentDirectory(search: string) is for getting a config object that you can utilize to navigate through the tree. search param is initial value for search$ pusher. Returned config has also result$ and fetchPath$.

const directoryConfig = webClient.agentDirectory.fetchAgentDirectory('');

directoryConfig.results$.pipe(
    takeUntil(this.isDestroyed$),
    tap((results) => {
        console.log(
            "Fresh results list for current search$ and fetchPath$ values:",
            results
        );
    })
).subscribe();

clickOnAgentItem(item: AgentDirectoryItem) {
    directoryConfig.fetchPath$.next(item.childrenPath);
}

directoryConfig.search$.next('John Smith');

This one is helpful for usage of transfers (see next section).

WebClient.transfers domain service

This domain service supports concept of transfers in Tenfold. You should use it when you want implement a logic, that your agent is on call with some customer and want to:

redirect this call to another agent (without asking him about it first).
switch current call to hanging mode, consult it with another agent and then discuss it with that agent, merge a call to join customer or return to customer.

No matter which scenario you want to implement, you need to set target agent that you want transfer in-progress call to. For this purpose use webClient.transfers.setAgent.

 selectAgent(result: AgentDirectoryItem) {
    const transferAgent = {
      name: result.label,
      agentStatus: result?.data?.state,
      pointsOfContact: result.pointsOfContact,
      hasPrimaryExtension: false,
    } as TransferAgent;

    await this.connectorService.getSDKService().transfers.setAgent(this.interaction.id, transferAgent);
  }

The above code is for case when you select agent after using webClient.agentDirectory.fetchAgentDirectory.

For scenario 1. you just need to use webClient.transfers.blindTransfer. It will redirect call to selected agent and end it with you.

For scenaro 2. you want to use webClient.transfers.handleInternalCall.

Then when you're on call with second agent and you can return to customer (ending a call with second agent) - use the same method webClient.transfers.handleInternalCall.
After discussion with second agent you may want to decide to join customer. You can do it with webClient.transfers.mergeTransfer.
If you want to complete this call with all parties just use webClient.transfers.completeWarmTransfer.
If you're no longer needed on the call with customer and second agent - just leave them on the call with webClient.transfers.handOverCall.
If you want jump from customer and second agent to be a middle-man you can just use webClient.callControls.switchCall. It works like toggle mechanism from one to another.

webClient.transfers.transfers$ is an observable that exposes state of all transfers as map where key is Interaction.id and value InteractionTransferState. It keeps a state with data like: agent, internalCall and transferStage.

If you focus on single interaction that is in progress you might be intrested in that kind of extraction of transfer state for your interaction:

interactionTransferSubState$() {
    return combineLatest([
      this.interaction$,
      this.transfers$,
    ]).pipe(
      takeUntil(this.destroySubject$),
      map(([call, transfers]) => {
        return !!call ? transfers[call.id] : null;
      }),
    );
  }