Introduction

This Technical Design Document (TDD) presents a comprehensive overview of integrating a Bot platform with the NICE CXOne platform using Studio Script.

This approach exclusively employs studio scripting to dispatch SIP headers, effectuate call transfer from Bot, and seamlessly transition to NICE CXOne once the bot flow concludes, and there is no requirement to have a VAH (Virtual Agent Hub) license or the need to host a proxy for SIP Backchannel configuration.

The purpose of this document is to provide a high-level solution design for the scripting-only approach by utilizing SIP actions from the studio.

Supporting Documentation

DOCUMENT	LINK
SIP headers	SIP headers
Voicebot Conversation	Voicebot Conversation
Signal API	Admin API (NICEincontact.com)

Architecture Diagram

Shared Responsibilities for the Script Integration Approach

Activity	Responsibility
	CXOne CUSTOMER	KORE
NICE CXOne Platform
NICE SIP Trunk Configuration	NA	NA
DID Number Procurement	DID numbers range from NICE	–
Channel Specifications
ACD Configuration	Skills creation and mapping Hours Of Operation Points of Contact Campaign Customization of Minimal functionality Voice call script, Main script, and Spawn script (2)	Minimal functionality Voice call scripts (2) Main Script: Accept call on DID Spawn Script: SIP Transfer the call to Kore
CXOne Studio Script	Customize Main and Spawn Scripts Add SIP Headers Add DID	Share a sample of the main and spawn scripts. Main Script Spawn Script
Setup Authentication	Configure CXOne Authentication for accessing the CXOne Signal API from the Kore bot.
Kore IVR Configuration
Setup Kore IVR	Create SmartAssist account
Setup Voice Channel
SIP Transfer Configuration	Network – Incoming IP address:NICE IP address 216.20.235.167 – Dallas 216.20.237.167 – Los Angeles DID Number: <To be Procured & Provisioned > Transport Type: TLSInbound Calls: Forward-to-PhoneNumber: <same as DID>	SIP URI (pre-filled)
SIP Transfer Attach Flow	Create an Experience Flow Attach SIP configuration to Experience flow
Kore SmartAssist Bot Flow	Create a bot flow and read the SIP headers defined in the CXOne Studio script.
Signal API to return call to CXOne	Get CXOne Authentication in Kore Bot Trigger Signal API from Bot*- The domain in the URL should match the customer’s NICE account domain.

CXOne Channel Specifications

ACD configuration includes

1. Skills creation and mapping: 1 skill
2. Hours Of Operation: 1
3. Points of Contact: 1 (Phone)
4. Campaign: 1
5. Minimal functionality Voice call script: 2

Kore Bot Platform

Telephony Gateway Requisites

1. DID or TFN phone number to receive the call.
2. All SIP header information.
3. How to configure Signal API to return control to the NICE CXone platform.

Kore SIP Transfer Configuration

1. On SmartAssist, go to CONFIGURATION > SYSTEM SETUP > Channels > Voice.
   
   
2. Click SIP Transfer.
3. Click + New.
   
4. Select List of IP Address.
5. Enter the Incoming IP Address and DID numbers from the Kore IVR Configuration table above.
   
6. Under SIP Transport Type, select TLS from the dropdown.
7. Click Next.
   
8. On the Forward to Phone Number page, select Inbound Calls.
9. Click Save.
   
10. Click SIP Transfer.
    
11. Click + Attach Flow.
    
12. Select a default flow from the list for the created flow.
13. Click Done.
    

Configuration in CXOne Studio

1. Download the Studio Script Link and save it locally.
2. Import the Studio Script as follows:
   1. Login to NICE CXOne Studio with your credentials. Learn more.
   2. On the File menu, select Import from File.
      
   3. Open the saved studio script.
      
      
      
   4. In the SIP Main Script, select the SIP Spawn Script in the Spawn action.
      
   5. Add SIP headers in the Sipputheader actions.
      1. Enter the key starting with X-* in the headerName.
      2. Enter the value in the headerValue.
         
   6. Add the SIP Phone number in the Placecall action.
      1. Provide the SIP DID number you configured in the Kore SmartAssist platform SIP Transfer in the PhoneNumber property in the Placecall action.
         
         

SmartAssist Configuration

• A flow should be configured with a bot on SmartAssist.
• In the Script Task window, add the following code to pass the headers to the bot before the Run Automation action.

  setCallFlowVariable('SIPHeaders', context.BotUserSession.channels[0].handle.SIPHeaders);
  var headers =getCallFlowVariable('SIPHeaders');
  userSessionUtils.put('SIPHeaders', headers);

  
  

• A bot action with Script Node is used to extract the headers in a bot.
  
  

  const headers = context.session.UserSession.SIPHeaders;
  if(headers) { let contactId = headers.find(o => o.name === 
  'X-ExternalCallId'); if(contactId && contactId .value) {
  koreDebugger.log('Inbound SIP Contact ID: ' +
  contactId.value); BotUserSession.put("ContactId", 
  contactId.value); }}
  

• The BotUserSession is used to save the SIP header value as ContactId and trigger the Signal API.
  

  Note: If the bot triggers the Signal API to transfer to a live agent or to end the conversation, the call must end from Kore, or the user should be disconnected from the Kore bot and SmartAssist flow.

NICE CXone Authentication

The following parameters are required for authenticating before calling any CXOne API:

1. Authentication API URL from NICE CXone.
2. Access key ID.
3. Access key secret.

Steps to authenticate NICE CXOne:

1. Login to the NICE Cluster.
2. Click your profile on the top right corner and select My Profile from the dropdown.
   
3. Go to the ACCESS KEYS tab and Click the Add access key button.
   
4. Copy the Access Key ID and Access Key Secret. This is used to get the access token to be used by the signal API.
5. The API URL for Authorization is (For different regions, the base URL will change accordingly. For example: na1.NICE-incontact.com): https://{region}.NICE-incontact.com/authentication/v1/token/access-key
6. Send the following POST request body:

   {
    "accessKeyId":"<Your Access Key Id>",
    "accessKeySecret":"<Your Access Key Secret>"
   }
   

7. An access_token that will be used to authenticate the Signal API is returned.

Fetch the NICE Authentication Access Token in the Bot

1. Add a bot action with a Service Node in the flow to get the access_token.
   
   
2. In the Service Node, select the Service Type as Custom Service and the Sub Type as REST.
   
3. Click EDIT REQUEST.
4. Select POST in the API call method and enter the authentication URL in the requested URL field.
   
5. Click the Headers tab.
6. Add Content-Type in Key and application/json in Value fields.
   
7. Click the Body tab and add the request body as follows:
   
8. Click Test.
9. Click Save as Sample Response.
   
   

Trigger the Signal API on Kore Bot

1. Add a Bot action with a service node to trigger the Signal API.
   
2. In the Service Node, select the Service Type as Custom Service and the Sub Type as REST.
   
3. Click Edit Request.
4. Choose the API method as POST.
5. Enter the Signal API URL in the requested URL field as follows (For different clusters, the base URL must be changed based on the cluster. For example: api-b32.NICE-incontact.com)

   https://api-{cluster}.NICE-incontact.com/incontactapi/services/v28.0/interactions/
   {{context.session.BotUserSession.ContactId}}/signal?p1=AgentHandoff

   Note: We extract the ContactId from the SIP headers and add it to the BotUserSession as {{context.session.BotUserSession.ContactId}}. This value is accessed to initiate the signal API trigger. The p1 parameter is configured as “AgentHandoff” to facilitate transferring the user to an agent.

   
6. Click the Headers tab.
7. Enter “Authorization” as the Key and “Bearer {{context.RestAPICall.response.body.access_token}}” as the value.
   
8. Click Save.

Code Snippets

Main Script SIP Main

Spawn Script SIP Spawn