Technical Design Document Template

Technical design documents (TDD) describe the details of a system. They're an important part of planning your custom virtual agent integration. This page is a guide to creating a TDD for your custom virtual agent integration.

Each section in this TDD template contains examples or additional information about the intended content for that section. Where possible, the examples relate to the example text virtual agent integration.

Use this TDD guide and the example integration as a starting point in the planning of your own custom integration. However, because they're provided as examples, neither the TDD nor the sample proxy tunnel are designed for a specific environment. The TDD and proxy tunnel that you create must take into account your organization's unique network architecture and requirements. You may need to add or remove sections to suit the needs of your environment.

Overview

This technical design document describes the custom integration of [your virtual agent] with NICE CXone. The integration includes the following components that must be described in this document:

Architecture, including the proxy tunnel/gateway middleware.
CXone configuration requirement, including skills, points of contacts, and channels.
Virtual Agent Hub and the endpoint for custom virtual agent integrations (Custom Exchange Endpoint).
Studio scripts, including Snippet code.
Authentication requirements.
Virtual agent configuration, endpoints, message origination details.
Request and response schema mapping.
[other components unique to your architecture and integration].

Architecture Overview

To Do: Create an overview diagram of your integration. Include all components in your environment that are involved in handling an interaction. This includes the proxy tunnel, the virtual agent, an authorization server, and so on. Include an overview description. Create additional diagrams if you need to show certain parts in greater detail.

Example

This is a sample text virtual agent integration on an ACD chat channel. Because this is an example integration, some things are different from a real-world integration:

The proxy tunnel code is one of the sample options provided by NICE CXone. The C# code is used in the examples on this page.
The proxy tunnel doesn't connect to a real virtual agent.
The proxy tunnel endpoint is designed to echo back the text that the user enters.
The chat for this channel A way for contacts to interact with agents or bots. A channel can be voice, email, chat, social media, and so on. is not set up on a live website. The chat channel is tested through a direct link obtained from the Point of Contact page in CXone.

This is a simple integration that doesn't require any authorization.

CXone Configuration

To Do: List the channel A way for contacts to interact with agents or bots. A channel can be voice, email, chat, social media, and so on., skills Used to automate delivery of interactions based on agent skills, abilities, and knowledge, points of contact The entry point that an inbound contact uses to initiate an interaction, such as a phone number or email address., campaigns, and any other relevant CXone configuration settings. For more information, see CXone Configuration Requirements on the Resources page.

Example

Channel: ACD chat.
Skill: Chat skill called IBChat_CEESample.
Point of contact: Chat point of contact called IBChat_CEESample.
Campaign: CEESample.

Channel Requirements

Because this is an example integration, no chat profile is required. However, in a real integration, this section would specify the requirements for the chat profile. The chat profile defines what the chat window looks like. This section would also list the pages on the website where the chat bubble would be located, as well as any other related requirements.

Virtual Agent Hub Configuration

To Do: List the webhook URL for your virtual agent and any parameters that your virtual agent requires be sent with requests. If you determine that you need a different timeout, add it to this section. The complete configuration process for the custom exchange endpoint in Virtual Agent Hub is described on the Implementation page.

Example

Webhook URL: https://https://4db3-5-46-62-207.nrgok.io/proxy/performbotexchange
Endpoint Parameters: None required
Custom Headers (Integration Version 2.0.0 and 3.0.0 only): None required
Timeout: No change needed
Authorization Header: None required
OAuth Configuration: None required
- OAuth URL: N/A
- OAuth Request Parameters: N/A
- OAuth Headers: N/A

Note that in integration version 1.0.0, dynamic authentication must be configured in the script, not in Virtual Agent Hub.

Studio Scripts

To Do: Add screenshots of the scripts you design for your custom virtual agent integration, along with explanations. Include descriptions of the variables, snippet code, and other details as needed. For more information see the script guidelines and requirements.

Example Chat Script

This is the same script used in the sample integration. You can use it as the basis for your own script. Example scripts are also provided for voice virtual agents.

Download this script.

This script begins with a Snippet action that creates several dynamic data objects required by a virtual agent integration:

intentInfo
nextPromptSequence
nextPromptBehaviors
customPayload
botSessionState

The first Textbot Exchange action sets the intent The meaning or purpose behind what a contact says/types; what the contact wants to communicate or accomplish for the virtual agent to respond to as the Welcome intent. When the virtual agent replies, it populates the botSessionState and customPayload objects and converts them to JSON using the .asjson() function.

The first Textbot Exchange action has three branches:

Error: The error branch processes the error and provides an appropriate message to the contact.
Return Control to Script: This branch is taken when the virtual agent signals that the conversation is complete or that the contact needs to be transferred to a live agent.
Prompt and Collect Next Response: This branch continues the conversation, as described below.

The script passes the data received from the virtual agent in the botsessionState, customPayloadFromBot, intentInfo, and nextPrompt objects. The Askcaller action prompts the contact with the virtual agent's response (nextPrompt). This action has four branches:

Error
Return Control to Script
Caller Responded
Default

All branches go to the second Textbot Exchange action, which sends the appropriate information to the virtual agent, including the contact's next request in the RES variable. This Textbot Exchange has the same branches as the first instance of the action in the script.

Service Endpoint Authorization

To Do: Determine the authorization requirements of your virtual agent service. If authorization is required, complete this section of the TDD. Create a diagram that illustrates the authorization requirements for your environment. Include the details of what's required for authorization requests. This may include:

The type of authorization (headers or tokens).
The key-value pairs for all required headers. If you're using custom exchange version 1.0.0, you only need the value for the header.
Any configuration requirements for the virtual agent service if you're using headers or the authorization server if you're using tokens.
The URL of the authorization server, if you're using tokens.
Key-value pairs needed for the OAuth request body and headers.
If you need or want to customize other OAuth settings, specify those changes. You can change the header name, header value prefix, and the token expiration time.

For more information, see the Authorization section on the Resources page.

Example for Non-Authorized (Public) Service Endpoints

The sample integration doesn't need authorization. The following diagram shows an example of what a public service endpoint might look like.

In this example, the request originates from Virtual Agent Hub. It first interacts with the API gateway and then the virtual agent service.

Example Authorized Service Endpoints

When a virtual agent service requires authorization to receive requests, you must send authorization headers with every request. You can also use dynamic authentication, which requires an authorization server (token provider). The architecture for an integration that uses headers would look similar to that in the example of a public service endpoint in the previous section. The following diagram shows an example of a dynamic authentication implementation.

In this example, when the script begins, a REST request is made to the authorization server, which provides a token. The token is sent along to the custom exchange endpoint. As long as the token is valid, the requests can be sent to the virtual agent service.

Proxy Tunnel

To Do: Determine the details for your proxy tunnel, including:

How your proxy tunnel will be hosted.
What language the proxy tunnel will be developed in and any required applications, dependencies, SDKs, extension packs, and so on.
A proxy tunnel failover strategy.

Example

Proxy Tunnel Hosting

The example proxy tunnel will be hosted on the local machine of the person who sets up the example text virtual agent integration.

Language

The proxy tunnel will be developed in C#. It will require the VS Code editor and a .NET SDK.

Failover Strategy

Because this is an example integration, no failover strategy is required.

Virtual Agent Use Case - Proxy to Virtual Agent Endpoint Mapping

To Do: Create a detailed sequence diagram that illustrates the responses and requests used at each point during an interaction. Document the request and response schemas in CXone and your virtual agent service that your custom integration requires. The example in this section show only schemas for CXone. For more information, see the Proxy Tunnel section and the Sequence Diagrams section on the Resources page.

Example

The sequence diagram and everything that follows is an example based on the Swagger available at the time of publishing. Always use the schemas documented in the publicly-available Swagger A square with an arrow pointing from the center outward. for custom virtual agent integrations. The custom exchange endpoint schemas may be periodically updated. For more information about how this impacts your custom integration, see the Resources page.

Request and Response Schemas

The schemas for requests are included on this page, as an example of documenting schemas. For detailed explanations of the custom virtual agent integration schemas, see the Schemas page.

Request - ExternalIntegrationBotExchangeRequest

Parameter	Type	Description
virtualAgentId	String	The name given to the Custom Exchange Endpoint configuration app in Virtual Agent Hub. This name identifies the virtual agent the app invokes.
botConfig	Object	The parameters defined in botConfig are discussed in other sections of this document.
userInput	String	The text input from the user received from the point of contact The entry point that an inbound contact uses to initiate an interaction, such as a phone number or email address. the script is assigned to.
userInputType	Enum	The user input type provided by the script.
executionInfo	ActionExecutionInfo	Telemetry data for the execution of an action Performs a process within a Studio script, such as collecting customer data, playing a message or music, or routing a contact to an agent. within a script.
systemTelemetryData	SystemTelemetryData	Data that can be used for debugging. Contains information about the CXone infrastructure.
base64wavFile	String	Contains the Base 64-encoded WAV file that contains the header of the request and the user utterance What a contact says or types. audio.
botSessionState	Object	Can be used for round-trip session information variables received from the virtual agent.
customPayload	Object	Can be used to send additional variables and parameters from the context of the Studio script.
mediaType	String	Indicates the media type of the script that's running.

Request - ActionExecutionInfo

Parameter	Type	Description
contactID	Integer	The unique identifier for the interaction.
busNo	Integer	The unique identifier for the business unit High-level organizational grouping used to manage technical support, billing, and global settings for your CXone environment.
requestId	Integer	An iterative number that identifies each request in a particular interaction.
actionType	String	The action type that makes the request to the custom exchange endpoint.
actionId	Integer	The unique identifier for the action Performs a process within a Studio script, such as collecting customer data, playing a message or music, or routing a contact to an agent. in the script. Action IDs are based on the order the actions were added to the script.
scriptName	String	The name of the script.

Request - SystemTelemetryData

Parameter	Type	Description
consumerProccessHost	String	The host name of the application calling the API.
consumerProcessName	String	The process or application name of the API caller. For example, EsnMediaServer.exe.
consumerProcessVersion	String	Any version information about the application calling the API.
inContactClusterAlias	String	If applicable and available, supply the NICE CXone cluster alias, such as C7 or M33.
inContactScriptEngineHost	String	If applicable and available, supply the NICE CXone script engine host name, such as lax-c4cor01 or aoa-c32cor01.
consumerMetaData	Object	Arbitrary and extensible data about the API consumer.