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.


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.
  • Digital Experience rich media content JSON schemas.
  • 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.


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: 

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

CXone Configuration

To Do: List the channelClosed A way for contacts to interact with agents or bots. A channel can be voice, email, chat, social media, and so on., skillsClosed Used to automate delivery of interactions based on agent skills, abilities, and knowledge, points of contactClosed 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. If your integration uses a Digital Experience (DFO) channel, include the Digital Experience channel and the required digital skills or routing queuesClosed The system uses routing queues to determine which agents to route cases to. Your system administrator creates routing queues so that certain cases are routed to agents with expertise in that type of case.. For more information, see CXone Configuration Requirements on the Resources page.


  • ChannelACD chat.
  • Skill: Chat skill called IBChat_CEESample.
  • Point of contact: Chat point of contact called IBChat_CEESample.
  • CampaignCEESample.

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.


  • Webhook URLhttps://
  • 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 and digital 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 intentClosed 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.


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.


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.


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




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 contactClosed 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 actionClosed 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 utteranceClosed 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




contactID Integer The unique identifier for the interaction.
busNo Integer The unique identifier for the tenantClosed 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 actionClosed 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




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.

Rich Media Content for Digital Channels

If you're setting up a custom virtual agent integration for a Digital Experience (DFO) channel, you can opt to support rich media content in messages. Rich media content includes content such as list pickers, images, time pickers, and so on.

To Do: Configure your digital script to send rich media content. Determine which rich media you want to support and add the schemas for the content to this section of your TDD.


The sample integration doesn't use a Digital Experience channel. However, the following is an example of a JSON schema for quick replies on a digital chat channel:

"messageContent": {
"type": "PLUGIN",
"payload": {
	"elements": [
		"id": "Ukm0hRAiA",
		"type": "QUICK_REPLIES",
		"elements": [
					"id": "Akm0hRAiX",
					"type": "TEXT",
					"text": "This is some text"
					"id": "Nkm0hRAiE",
					"type": "BUTTON",
					"text": "Button 1",
					"postback": "click-on-button-1"
					"id": "TkGJ6CAiN",
					"type": "BUTTON",
					"text": "Button 2",
					"postback": "click-on-button-2"
					"id": "EyCyTRCi4",
					"type": "BUTTON",
					"text": "Button 3",
					"postback": "click-on-button-3"