CXone Agent SDK

SDK Language: Typescript

Current Version: 24.4

Release Date of Current Version: October 15th, 2024

Availability: All regions and all business segments

Browser Support: Google Chrome, Microsoft Edge, Island Enterprise

SDK Repository: GitHub

NPM: ACD , Agent , Auth , Digital , Voice

API Reference: CXone Developer Portal

A software development kit (SDK) is like a toolbox for developers. It provides a set of tools and resources that make building software applications easier. You could think of it as a collection of pre-made building blocks. These building blocks have existing functionality. Your developers can use these existing blocks instead of building the functionality on their own from the ground up. The following are three general benefits to using an SDK:

  1. Efficiency: The SDK provides ready-made tools and pre-built components that save developers time. Instead of reinventing the wheel, they can focus on the unique aspects of their app.

  2. Consistency: The SDK ensures consistency across different apps. By using the same set of tools and libraries, developers maintain a uniform experience for users.

  3. Quality Assurance: With the logger, developers can verify their code, catch bugs early, and deliver more reliable software.

In summary, an SDK simplifies development, ensures quality, and fosters collaboration, making it an essential tool for efficient app creation.

The CXone Agent SDK lets you build an agent application. It also lets you integrate CXone Agent functionality into an existing application. Instead of using CXone APIs directly, developers can use the pre-made functionality through the SDK. This speeds up development time and saves resources. Your developers are not required to understand how all the CXone APIs work. Instead, the SDK lets you use groups of APIs in consumable JavaScript wrappers.

The CXA SDK is a compilation of smaller SDKs. Each smaller SDK focuses on a particular aspect of functionality, like authentication or call controls. To meet your use case, you can choose only the SDKs that you need. For example, you may not need the Voice SDK, which provides WebRTC functionality for an Integrated Softphone. This also means that developers only need to install the necessary SDKs for your use case.

Key facts about the CXA SDK:

  • The SDK works through event subscriptions. Data from the CXone platform is published with an event. To use the data, your app must subscribe to these events.

  • All features of CXone Agent are available through this SDK.

  • You must register the application you will use the SDK with. Complete the registration form to receive credentials for this app. The Getting Started page of the developer portal leads you through the process of registering your app and setting up authentication.

  • The SDK supports OpenID Connect with PKCE authentication flow.

CXA SDK Use Cases

The following are three common use cases of the CXA SDK.

  • Custom Agent Client:
    In this case, you have a unique feature or requirement that the native CXone Agent does not already provide. Also, perhaps you cannot simply embed your required functionality intoCXone Agent. For example, you may need to limit agents' visibility into contact information. This could be for a particular security requirement. You may need to mask all contact data from the agents, which only a custom client can facilitate.

  • Integrate an Agent Client with a Third-Party Application:
    In this case, you cannot embed the agent application into another app. Other apps are often CRMs, online banking sites, or a hotel booking systems. This use case is when you want the functionality of an agent client, but don't necessarily need the client UI. Using the SDK, you can build a piece of functionality into another application. Using the hotel system as an example, staff could call a specific room through the booking system.

  • Event Subscription for Embedded Applications:
    This is commonly used to comply with certain browser security restrictions. For example, Google prevents posting data to an iframed window from another website. This complicates how windows can share messages or data between the two frames. For example, you have a healthcare app that you iframe into CXone Agent. When the agent accepts a contact, you want to use the contact's phone number to look up their information in your healthcare app. This lets you automatically display contact information to the agent. If the agents use Google Chrome, the healthcare app cannot get the contact phone number from CXone Agent. Instead, it needs to subscribe to the VC event stream, which is the same that CXone Agent uses.

SDK Breakdown

The CXA SDK is comprised of the following smaller SDKs:

SDK Details
ACD

This SDK offers features for handling voice calls, voicemails, and work itemsClosed Customizable method of delivering contacts to an agent via Studio scripts.. For example:

  • For voice calls, you can initiate, receive, transfer, and conference the calls.

  • For voicemail, you can receive, store, and manage voicemails.

  • For work items, you can automate the distribution of work items to agents. This optimizes agent workload using predefined rules and criteria.

The following are key technical details about the ACD SDK:

  • After successfully authenticating, you can call initAcdEngagement() to instantiate this module and build ACD features.

  • You can establish a session between an agent and contact using the startSession and joinSession methods.

  • After the session is established, your app can call other methods for features like dialing, transferring, conferencing, and so on.

  • Successfully calling this module's methods produces ACD events.
Agent

This SDK is for handling session events. It lets you start sessions, join a session that's in progress, and so on. Its main focuses are:

  • The get-next-event loop

  • Anything that ACD and Digital Experienceareas of the CXone platform have in common, like WEM or notifications.
Auth

This SDK facilitates secure authentication and authorization. It primarily lets you set up a login flow using the CXone global authentication . The supported authentication flow is OpenID Connect with PKCE. Users must authenticate with a CXone account. This lets you verify user identities and their permissions based on their CXone roleClosed Looks for cues to identify customer frustration. The cues include words and phrases like, "I'm very angry". Frustration isn't the same as negative sentiment. Frustration cues show that a customer is upset rather than just discussing something negative..

Key features include:

  • Automatically refreshing auth tokens. This lets users stay logged in until they close the app or log out.

  • Token management and validation. If a user has already logged in to CXone, you can pass the valid auth token to your app.

The following are key technical details about the Auth SDK:

  • Call cxoneAuth.init() to pass cxoneHostname, clientId, and redirectUri to the SDK.

  • Invoke the getAuthorizeUrl() method to redirect the user to the global CXone authentication page. After logging in, they're redirected back to your app.

  • When the user enters the credentials and initiates the authentication, an AuthSettings object is created with their user information. The CXoneAuth instance is initialized using AuthSettings.

  • Use getAccessTokebByCode() to capture the returned code and generate an authentication token. This also saves the user's information.

  • Subscribe to onAuthStatusChange, which produces events about authentication like AUTHENTICATED or AUTHENTICATEDFAILED. In the case of AUTHENTICATED, this automatically fires the refresh flow, keeping the user logged in.
Digital

This SDK lets you integrate digital communication channels. You can use standard digital channels like email, chat, and SMS, plus social media platforms like WhatsApp. Depending on the number of channels you have set up, you can create multi-channel communication.

The following are key technical details about the Digital SDK:

  • After successfully authenticating, you can call CXoneDigitalClient.instance.initDigitalEngagement(). This instantiates the necessary components for digital messaging and establishes a digital WebSocket connection.

  • Use digital events to receive already-assigned cases and their existing message threads.

  • Your app can reply to digital messages with the reply() method.

  • You can also initiate a new outbound interaction with the reply() method.
Voice This SDK provides you Integrated Softphone functionality. It is a wrapper for WebRTC.

Resources

An SDK lets you create your own custom functionality, therefore your support resources are primarily self-service content. Your technical support options are based on your organization's support agreement with NICE. Contact your CXone Account Representative for more information on your support options.

In addition to this page, your self-service content focuses on developer resources. The SDK package includes the following:

  • READMEs for each individual SDK that provide getting started information.

  • A sample application to showcase basic functionality.

  • Usage examples with code excerpts from the sample application.

  • Code comments.

Events

The following are events that your app can listen to. The events are categorized by the module in which they're available.

ACD SDK

Instance Event Description

CXoneAcdClient.instance.contactManager

conferenceCallEvent

Listens for events related to conference calls.

 

onDispositionEvent

Handles events related to dispositionsClosed Result assigned by the agent or system at the end of a voice (disposition) or digital (status) interaction. of interactions.

 

onTagsEvent

Manages events related to tags associated with interactions.

 

voiceContactUpdateEvent

Listens for updates to voice contacts.

 

voiceMailContactUpdateEvent

Listens for updates to voicemail contacts.

 

workItemContactUpdateEvent

Listens for updates to work item contacts.

CXoneAcdClient.instance.notification

onUpdateMessageEvent

Listens for new messages or notifications for the agent.

CXoneAcdClient.instance.screenPop

agentAssistSubject

Handles events related to agent assistance or copilot applications.

 

contactScreenPopSubject

Handles events related to screen popping for incoming contacts.

 

pageOpenSubject

Handles events related to opening web pages.

 

popUrlSubject

Handles events related to popping out URLs in a new window or tab.

 

runAppSubject

Handles events related to running applications or opening custom forms.

CXoneAcdClient.instance.session

agentLegEvent

Listens for events related to the agent's legClosed The portion of an interaction that takes place between CXone and the agent. in the session.

 

agentStateSubject

Observable that emits events related to changes in the agent's state, like Available to Unavailable.

 

naturalCallingSkillListSubject

Listens for updates to the list of skills enabled for natural calling.

The event types include: SESSION_START, SESSION_END, JOIN_SESSION_SUCCESS and JOIN_SESSION_FAILURE.

 

networkOfflineSubject

Listens for events related to network connectivity issues.

 

onAgentSessionChange

Listens for changes in the agent's session status like start or end.

The event types include: SESSION_START, SESSION_END, JOIN_SESSION_SUCCESS and JOIN_SESSION_FAILURE.

CXoneAcdClient.instance.session.agentStateService

agentStateSubject

Observable that emits updates on the agent's state changes.

Agent SDK

Instance Event Description

CXoneClient.instance

autoSummaryService

Service for managing automatic summaries.

 

copilotNotificationClient

Facilitates receiving real-time notifications for Agent Copilot.

 

cxoneApiPerformanceMetrics

Listens for performance metrics from the CXone API.

CXoneClient.instance.agentSession

agentSessionEndSubject

Emits an event when the current agent's session ends.

CXoneClient.instance.agentSetting

mchAgentSettingsChangeEvent

Listens for changes in the agent's Make Call Heard (MCH) settings.

CXoneClient.instance.autoSummaryService

onAutoSummaryReceived

Observable event triggered when an auto-generated summary is received for a contact.

CXoneClient.instance.commitment

onCommitmentEvent

Listens for events related to the agent's commitments.

 

onCommitmentStatusEvent

Listens for changes in the status of the agent's commitments.

 

onUpdateCommitments

Listens for updates to the agent's commitments.

CXoneClient.instance.contactManager

onDigitalContactEvent

Provides updates on digital contact interactions like chat sessions and outbound messages in CXone.

 

onDispositionEvent

Provides updates on call disposition status after call ends.

 

voiceContactUpdateEvent

Provides real-time updates on ongoing voice call details like caller name and phone number.

CXoneClient.instance.copilotNotificationClient

onMessageNotification

Observable/event emitter used to subscribe to incoming copilot messages or notifications.

The event types include: ADAPTIVE_CARD, RT_SUMMARY, NEXT_BEST_RESPONSE, NEXT_BEST_RESPONSE_LLM, NEXT_BEST_RESPONSE_EXPERT, KB_ANSWERS, SENTIMENT, KB_LINKS, KB_IMAGES, TEXT, FINAL_SUMMARY, FINAL_SUMMARY_NOTES, KB_ANSWERS_VOICE, KB_IMAGES_VOICE, ENLIGHTEN_AGENT_COPILOT and AGENT_COPILOT.

CXoneClient.instance.directory

directoryEvent

Listens for events related to the directory, like agents, teams, or skills.

Provides updates on changes to directory data like new contacts, updates, and permission modifications in CXone.

 

onUpdateSkillsEvent

Listens for updates to the agent's assigned skills.

CXoneClient.instance.directory.dynamicDirectory

searchDirectoryResult

Waits for the results to come back after you've looked up something like a person or department in a directory within the system.

CXoneClient.instance.indicator

agentIndicatorsEvent

Event providing updates on agent indicators like availability, current activity, and custom agent status indicators.

 

contactIndicatorsEvent

Event providing updates on contact indicators that may trigger actions like displaying custom forms to collect additional information.

CXoneClient.instance.notification

onCXoneNotificationEvent

Listens for notifications from the CXone platform.

CXoneClient.instance.screenPop

contactScreenPopSubject

Event triggering opening of a webpage with caller information for an existing call.

 

pageOpenSubject

Event triggering opening of a webpage that's not necessarily related to the current call.

 

popUrlSubject

Event triggering opening of relevant web page for an existing call.

 

runAppSubject

Event triggering the launch of an app or display of custom form for a call.

CXoneClient.instance.session

agentLegEvent

Listens for updates on a specific call leg of the agent, like an incoming or outgoing call.

CXoneClient.instance.session.agentStateService

agentStateSubject

Event providing live updates on agent's availability status and state changes in CXone.

CXoneClient.instance.skillActivityQueue

agentQueueSubject

Event providing updates on agent's assigned queue information like queue name, call count, and agent availability.

 

agentQueuesDetailSubject

Event providing detailed updates on agent's assigned queues, including metrics like average wait time, Service Level Agreements (SLAs), and agent performance.

 

skillActivityEvent

Event providing updates on skill activity metrics like call queue length, average wait time, and available agents.

Auth SDK

Instance Event Description

CXoneAuth.instance

onAuthStatusChange

Observable that listens to user authentication status changes.

The event types include: AUTHENTICATED,AUTHENTICATING, NOT_AUTHENTICATED, AUTHENTICATION_FAILED and REFRESH_TOKEN_SUCCESS

Digital SDK

Instance Event Description

CXoneDigitalClient.instance.digitalContactManager

onDigitalContactEvent

Listens for events related to digital contacts.

The event types include: CASE_INBOX_ASSIGNEE_CHANGED, CASE_STATUS_CHANGED, MESSAGE_ADDED_INTO_CASE, CASE_INBOX_ASSIGNED, CASE_INBOX_UNASSIGNED, MESSAGE_CREATED, MESSAGE_NOTE_CREATED, MESSAGE_NOTE_DELETED, MESSAGE_NOTE_UPDATED, MESSAGE_UPDATED, SENDER_TYPING_START, SENDER_TYPING_END and MESSAGE_PREVIEW.

 

onDigitalContactNewMessageEvent

Listens for new messages from digital contacts.

 

onDigitalContactUserTypingPreviewEvent

Listens for typing preview events from digital contacts.

The event types include: CASE_INBOX_ASSIGNEE_CHANGED, CASE_STATUS_CHANGED, MESSAGE_ADDED_INTO_CASE, CASE_INBOX_ASSIGNED, CASE_INBOX_UNASSIGNED, MESSAGE_CREATED, MESSAGE_NOTE_CREATED, MESSAGE_NOTE_DELETED, MESSAGE_NOTE_UPDATED, MESSAGE_UPDATED, SENDER_TYPING_START, SENDER_TYPING_END and MESSAGE_PREVIEW.

Voice SDK

Instance Event Description

CXoneVoiceClientWrapper.instance

onCallStatusChanged

Handles events related to call status changes.

 

onConnectionStatusChanged

Handles events related to voice connection status changes.