AXP Core

Overview

The AXP Core module provides a set of basic functionalities to initialize, shutdown the SDK, and get the default conversation of the end user. The AXP Core establishes the session with Avaya Experience Platform™ for the end user, manages the session inactivity, and participants involved in the conversation.

Installation

To install the AXP Core, run the following command:

npm install --save @avaya/axp-omni-sdk-core

AXP Core exports a set of types and classes. Out of all the exports, the class AxpOmniSdk is the origin point of the AXP Core usage flow. It can be imported as follows:

import { AxpOmniSdk } from "@avaya/axp-omni-sdk-core";

Usage

Prerequisites

Before using the AXP Omni SDK refer to this page for a list of prerequisites.

Using additional functionalities

The Conversation of Core module is extended by other modules of AXP Omni SDK. This extensibility is achieved using the concept of Mixins.

Each additional functionality exports a mixin which enhances the conversation object with its own set of properties and methods. For example, if you use AXP Messaging module, then the conversation object will have additional properties and methods to send and receive messages.

Please refer to the documentation of the additional functionality module that you are using to know more about the methods that it adds on the Conversation.

List of currently available additional functionalities:

• AXP Messaging

How to use the additional functionalities

To use the additional functionalities, the Client has to install the additional functionality module (refer to the installation instructions of each additional functionality module for more details).

Each additional functionality module exports a mixin function. The base conversation from AXP Core module can be enhanced by applying this mixin. This will come in handy when we add new functionalities in future releases.

Example of adding AXP Messaging functionality to the AXP Core Conversation:

// TS/JS
import { AxpOmniSdk } from '@avaya/axp-omni-sdk-core';
import { AxpMessagingConversation } from '@avaya/axp-omni-sdk-messaging';

const EnhancedConversationClass = AxpMessagingConversation();

// All arguments are not shown for brevity, refer to the Initialization section for the complete initialization example.
const userSession = await AxpOmniSdk.init(..., EnhancedConversationClass);

Authentication

The AXP Omni SDK uses JSON Web Tokens (JWT) for client authentication and requires a valid JWT to function. The JWT is obtained from your own backend web application that communicates with AXP's authentication API.

The SDK expects an implementation of the JwtProvider interface to be provided during initialization. The JwtProvider implementation must have two methods:

1. onExpiryWarning: This method is called when the JWT is about to expire. In the argument of this method, the remaining time in milliseconds before the JWT expires is provided.
2. onExpiry: This method is called when the JWT has expired.

The consumers of SDK should call the AxpOmniSdk.setJwt() to provide a new JWT to the SDK.

JWT Provider example (in TypeScript):

import { JwtProvider } from "@avaya/axp-omni-sdk-core";

class MyJwtProvider implements JwtProvider {
	onExpiryWarning(timeToExpiry: number): void {
		// ...
	}

	onExpiry(): void {
		// ...
	}
}

JWT Provider example (in JavaScript):

class MyJwtProviderJS {
    onExpiryWarning(timeToExpiry) {
        // ...
    }

    onExpiry(): void {
        // ...
    }
}

Initialization

Before any operation can be performed with the SDK, it must be initialized. The initialization process creates a new session for the current user (identified by the JWT) and returns a UserSession object that contains the Conversation object corresponding to the User's ongoing conversation. For more details see the Conversation section.

Initialization can be done by calling the static method init() on the class AxpOmniSdk. The init() method takes two arguments:

1. initParams: An object which has all the initialization parameters and configurations.
2. AdditionalFunctionality: A Conversation class enhanced by applying the additional functionalities using mixins.

Initialization Example:

import { AxpOmniSdk } from '@avaya/axp-omni-sdk-core';
import { AxpMessagingConversation } from '@avaya/axp-omni-sdk-messaging';

const EnhancedConversationClass = AxpMessagingConversation();

const initParams = {
    host: 'na'
    integrationId: '<integrationId>',
    appKey: '<appKey>',
    token: '<JWT>',
    JwtProvider: new MyJwtProvider(),
    displayName: 'John Doe',
    logLevel: 'debug',
    idleTimeoutDuration: 5 * 60 * 1000, // in milliseconds
    idleShutdownGraceTimeoutDuration: 1 * 60 * 1000, // in milliseconds
}

const userSession = await AxpOmniSdk.init(initParams, EnhancedConversationClass);

The init() method returns a Promise that resolves to a UserSession object. The UserSession object contains the conversation object(s) that can be used for further operations.

Waiting for initialization to complete

Being an async method, the Client can await on the promise returned by the init() (as shown in above example) method to wait for the SDK initialization to complete.

Alternatively, the SDK emits an initialized event after the SDK initialization has completed. The Client can listen to these events by providing a listener function to SDK.

Important: In order to receive the initialized event, it is imperative to provide the listener function before calling the init() method.

AxpOmniSdk.addSdkInitializedListener((userSession) => {
	// userSession object contains the conversation object that can be used for further operations. More details on the conversation object are below.

	console.log("SDK Initialized");
	// ... your code.
});

Conversation

A conversation object represents the conversation of the current user with the Contact Center.

The AXP Core Conversation contains -

• Method to get the details of the participants involved in the conversation.
• Method to provide listeners for the participant change events.
• Method to set the context parameters used for routing.
• Property conversationId.

💡 INFO: Based on additional functionality that is included, the conversation will have additional properties and methods. Check out the documentation of each functionality that has been added to know more about the methods that it adds on to the Conversation.

❗ NOTE: On initialization, the default Conversation for the user gets automatically created on AXP. The default conversation of the user never ends and currently the only conversation that the user can use.

The default conversation can be accessed from the UserSession object returned by the init() method.

// Arguments are not shown for brevity, refer to the Initialization section for the complete initialization example.
const userSession = await AxpOmniSdk.init(...);

const conversation = userSession.conversations[0];

Alternatively, the AxpOmniSdk class exposes another method getDefaultConversation() which returns the default conversation object. Important thing to note here is that this method can be called only after the SDK has been initialized.

const userSession = await AxpOmniSdk.init(...);

const conversation = AxpOmniSdk.getDefaultConversation();

Context Parameters

Context parameters are used to provide routing information to the AXP platform. These parameters are used to route the conversation to the appropriate agent or queue. The context parameters can be set using the setContextParameters() method on the conversation object.

conversation.setContextParameters({
	key1: "value1",
	key2: "value2",
	// ...
});

Participants

The Client can get the list of participants involved in the conversation by using the property participants on the conversation object. The participants property is an array of Participant objects. Each Participant object contains that participant's details like id of the participant, their display name, their role and the channel on which they are participating in the conversation.

const participants = conversation.participants;

Events

Apart from the initialized and shutdown events, the SDK emits a few more events that the consumers can listen to. These events are specific to the Conversation and hence the APIs to listen to these events are provided on the Conversation object.

| Event Name | Description | API to provide listener | | ------------------- | ------------------------------------------------------------ | --------------------------------------------------- | | Participant Added | Emitted when a new participant is added to the conversation. | conversation.addParticipantAddedListener() | | Participant Removed | Emitted when a participant is removed from the conversation. | conversation.addParticipantDisconnectedListener() |

The APIs to provide listeners returns a handlerId for that listener. This handleId can be used to remove the listener for that event.

const participantAddedHandlerId = conversation.addParticipantAddedListener((participant) => {
	console.log("Participant Added:", participant);
	// ... your code.
});

// To remove the listener
conversation.removeParticipantAddedListener(participantAddedHandlerId);

// Similarly for Participant Removed event

const participantDisconnectedHandlerId = conversation.addParticipantDisconnectedListener((participant) => {
	console.log("Participant Removed:", participant);
	// ... your code.
});

// To remove the listener
conversation.removeParticipantDisconnectedListener(participantDisconnectedHandlerId);

User Activity

The SDK provides mechanism to automatically clear up the session if the User's session has not been active for the configured amount of time. The following sections explain what is considered as User Activity along with various timers and events that support this feature.

Timeouts

The AXP Core provides two timeouts to manage the session inactivity:

The first timer is the idle timer which is started right after the session is created. Any activity from the User or Client (mentioned below) resets this timer. This timer expires when there are no activities for the configured duration. Once this timer expires the SDK will emit the Idle Timeout event and provide the configured grace period duration in the event's payload. The Client can show an appropriate message on the UI, warning the User about inactivity, by handling this event.

The second timer is idle shutdown grace timer which runs after the idle timer has expired. This timer provides additional grace period for User or the Client to extend the session. After this timer expires, the session is terminated automatically and the SDK will raise the shutdown event and shut itself down (see shutdown section for more details). If the Client wants to continue it must be reinitialize the SDK to do so.

Both the timeout values can be configured during the initialization by providing their values in the init params object passed as the first argument to the AxpOmniSdk.init() method.

await AxpOmniSdk.init({
	// Other init params
	idleTimeoutDuration: 5 * 60 * 1000, // in milliseconds
	idleShutdownGraceTimeoutDuration: 1 * 60 * 1000, // in milliseconds
});

The Idle Timeout event can be listened to by providing a listener for the same.

function warnUser(message) {
	// Show warning on UI.
}

const handlerId = AxpOmniSdk.addIdleTimeOutInvokedListener((eventPayload) => {
	warnUser("You have been inactive for a while. Do you want to continue?");
});

// It can be removed by calling the removeIdleTimeoutListener method.
AxpOmniSdk.removeIdleTimeOutInvokedListener(handlerId);

Extending the session

The AxpOmniSdk provides a method called resetIdleTimeout() which can be used to reset the idle timer or the grace timer. This method can be called whenever there is any activity from the User or the Client.

This method also helps the Client to extend the session in scenarios where the Client is aware that the User is active based on events from its UI.

Apart from this method, calling a subset of other methods provided by the Additional Functionalities is also considered as User activities. The list of methods that are considered as User Activity are provided in the documentation of the respective Additional Functionality.

The resetIdleTimeout() method only impacts the timers as opposed to calling methods of Additional Functionalities which also perform the operation that the method is supposed to do.

function showWarningBox(eventPayload) {
	const continueChatButton = document.getElementById("inactivity-warning-continue-chat");

	continueChatButton.onclick = () => {
		AxpOmniSdk.resetIdleTimeout();
	};
	// ...
	setTimeout(hideWarningBox, eventPayload.gracePeriod);
}

function hideWarningBox() {
	// ...
}

Shutting down the SDK

The current user's session can be terminated by calling the shutdown() method of AxpOmniSdk. This will end the session and cleanup all the corresponding data within the SDK. Irrespective of the success or failure of the termination operation, the SDK cleanup will be performed.

To shut down the SDK, call the shutdown() method on the AxpOmniSdk class. The shutdown() method returns a Promise that resolves when the SDK has been successfully shut down.

await AxpOmniSdk.shutdown();

! Important

Once the SDK is shutdown the Conversation object(s) are also removed, hence the Client must re-initialize the SDK incase it wants to start again. However, this doesn't close the conversation of the User. Post re-initialization, the User can continue the conversation from where it was left.

Similar to the initialization process, the SDK emits a shutdown event after the SDK has been successfully shut down. The consumers can listen to these events by providing a listener function to SDK.

AxpOmniSdk.addSdkShutdownListener(() => {
	console.log("SDK Shutdown");
	// ... your cleanup code.
});