Custom Virtual Agent Integrations

CXone supports custom virtual agent integrations. This enables your organization to use a virtual agentClosed A software application that handles customer interactions in place of a live human agent. or bot that CXone doesn't natively support. You can use virtual agents and bots on voice, CXone chat, and chat-based Digital Experience channels.

This online help provides the high-level information about custom virtual agent integrations. Use it to plan, design, build, and configure the integration for your organization. You may also need:

  • Other CXone resources, including the CXone online help, knowledge base articles, and the NICE CXone Community site.
  • Documentation for your virtual agent. In particular, you need documentation about configuring endpoints.
  • Documentation for the third-party digital channel you're using with the virtual agent, if applicable. For example, if you're setting up a virtual agent integration on an Apple Messages for Business channel, you need the documentation for Apple Messages for Business.
  • Documentation for any component of your network environment impacted by the integration with CXone. This may include API gateways, security or authorization systems, cloud hosting environments, and so on.

Introduction

A custom virtual agent integration with CXone has the following core components:

  • API Endpoints: Communication between your virtual agent and CXone happens via API endpoints. CXone has an endpoint designed for custom virtual agent integrations. The endpoint is called the Custom Exchange Endpoint.
  • Proxy Tunnel and Webhook: The proxy tunnel acts as the relay between CXone and your virtual agent environment. It integrates with CXone through a webhook and uses HTTP as the information relay method.
  • Studio Scripts: Studio scripts define the flow of requests and responses between CXone and your virtual agent. Scripts may also handle authentication, if required.

Custom virtual agent integrations only work in synchronous contexts. CXone doesn't currently support asynchronous communication for custom integrations.

API Endpoints

An API (Application Programming Interface) allows one system or application to communicate with another. Communication happens through endpoints, which give access to specific parts of the program. An endpoint waits for a request to arrive, then it responds to the request.

Custom virtual agent integrations rely on API endpoints in CXone and your virtual agent. During an interaction between a contact and your virtual agent, all communication passes between these endpoints. This is shown in the following image:

A diagram with CXone and a virtual agent in squares, each with a line labeled "endpoint" and arrows showing that data passes between the endpoints.

The CXone endpoint for custom virtual agent integrations is managed in Virtual Agent Hub. You can configure the endpoint to meet the unique needs of your organization and virtual agent. For example, if your virtual agent requires specific information to be sent with each request, you can configure that in Virtual Agent Hub.

The CXone endpoint for custom virtual agent integrations works in a REST request and response paradigm. CXone makes the requests, sending information about the contact's utterances. The virtual agent service determines the contact's intentClosed The meaning or purpose behind what a contact says/types; what the contact wants to communicate or accomplish and sends appropriate responses.

Proxy Tunnel and Webhook

A proxy tunnel allows communication between two systems where network connectivity is limited or restricted by firewalls and other security measures. A webhook is similar to an API endpoint.

In a custom virtual agent integration, the webhook passes the event for an incoming contact to the proxy tunnel. Before the proxy tunnel passes the event on to the receiving system, it translates the requests and responses into the formats that the receiving system can use. CXone has one set of parameters and your virtual agent has another set. The parameters are different, but there is correlation between the information they hold. Both CXone and the virtual agent service expect the parameters to be formatted in different ways. The proxy tunnel converts one set of parameters into the other before passing the request or response on. This is shown in the following image:

A diagram of CXone. , a virtual agent, and a proxy tunnel, with arrows showing data passing from one endpoint through the proxy to the other endpoint.

Every proxy tunnel must be unique. Every organization's network architecture, authorization requirements, and so on are different. The proxy tunnel and webhook must be custom-designed to fit your specific requirements. Your organization or the SI you hire is responsible for creating and maintaining the proxy tunnel and webhook.

How Custom Integrations Work

The following diagram and table describe the flow of information through a custom virtual agent integration.

A diagram showing the flow of an interaction from a contact through CXone, proxy tunnel, to virtual agent with STT, TTS, and NLU steps, and back again.

The following table explains the flow of requests and responses in a custom virtual agent integration.

Step

Details
1

A contact initiates a voice or chat interaction. This invokes a point of contactClosed The entry point that an inbound contact uses to initiate an interaction, such as a phone number or email address. in CXone. CXone routes the contact to the Studio script that handles that point of contact.

For voice interactions: If the script is configured to transcribe the audio from the contact using CXone Turn-by-Turn Transcription, it is done at this time.
2

The script routes the request to the proxy tunnel endpoint via Virtual Agent Hub. The request includes the contact's utterancesClosed What a contact says or types. either as audio in the format of the G-711 codec or as transcribed text. The proxy tunnel translates the request into a format the virtual agent can understand, then passes it to the virtual agent.

Depending on the architecture of your environment, steps 3, 4, and 5 may require up to three round trips to complete the speech-to-text (STTClosed Also called STT, this process converts spoken language to text.), natural language understanding (NLUClosed This process expands on Natural Language Processing (NLP) to make decisions or take action based on what it understands.), and text-to-speech (TTSClosed Allows users to enter recorded prompts as text and use a computer-generated voice to speak the content.) processing. This is different from the diagram, which shows these steps being completed in one trip. Note that a scenario that requires three round trips may introduce latency into the handling of each request.

For chat interactions and voice interactions that are already transcribed: Skip to step 4.

For untranscribed voice interactions: Continue to step 3.
3

For untranscribed voice interactions only: The virtual agent transcribes the contact's audio using its STT transcription service.

4

The virtual agent's natural language processingClosed Also called NLP, this process understands human speech or text and responds with human-like language. engine processes the text (transcribed or from a chat). It determines the contact's intentClosed The meaning or purpose behind what a contact says/types; what the contact wants to communicate or accomplish.

The virtual agent determines the appropriate response to the intent.

For chat interactions or voice interactions that will be synthesized by CXone Cloud TTS Hub: Skip to step 6.

For all other voice interactions: Continue to step 5.
5 For voice interactions only: The response is converted into synthesized speech by the virtual agent's text-to-speechClosed Allows users to enter recorded prompts as text and use a computer-generated voice to speak the content. (TTS) process.
6

The response passes back through the proxy tunnel via Virtual Agent Hub to the Studio script. The response is received as: 

  • Virtual agent voice interactions: Audio and payload if using the virtual agent's TTS service is used; text and payload if using CXone Virtual Agent Hub.
  • Virtual agent chat interactions: Text and payload.

The proxy tunnel returns payload with every conversational turn. The script configuration is used to parse the payload.

The script routes the response to the contact.

7 The contact responds with another utteranceClosed What a contact says or types. and the process begins again, starting at step 2.

Example Integration

NICE CXone has provided an example chatbot integration that you can set up. The example integration allows you to see how a custom virtual agent integration works. It uses ACD chat and a sample proxy tunnel provided by NICE CXone.

The example integration doesn't connect with a real virtual agent. Instead, the proxy tunnel is designed to echo back the text sent through CXone chat. It simulates a real interaction so you can see how the script, proxy tunnel, and Custom Exchange Endpoint work together.

Code for the proxy tunnel is provided in a number of programming languages, so you can implement the sample in a language you're comfortable with.

Custom Virtual Agent Integration Versions

Three versions of endpoint for custom virtual agent integrations are available. The versions differ primarily in the number of authorizations headers they support.

The options are: 

  • 1.0.0: Supports a single authorization header. The header is sent with the ExternalIntegrationBotExchangeRequest request.
  • 2.0.0: Supports multiple authorization headers. The headers are sent with the ExternalIntegrationBotExchangeRequest request as key-value pairs.
  • 3.0.0: Supports multiple authorization headers and StandardBot. The headers are sent with the ExternalIntegrationBotExchangeRequest request as key-value pairs.

    • Integration versions 1.0.0 and 2.0.0 will be deprecated in a future release. Version 3.0.0 is the preferred version to use with custom virtual agent integrations. If you currently use version 1.0.0 or 2.0.0, plan to upgrade to 3.0.0. Version 3.0.0 is nearly identical to version 2.0.0. The primary difference is that 3.0.0 adds support for StandardBot.

Features Supported for Custom Virtual Agent Integrations

Custom virtual agent integrations can support: