Skip to content

Voice Automation NiceCX (CXOne) – SIP Integration

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 the Bot, and seamlessly transition to NICE CXOne once the bot flow concludes. A VAH (Virtual Agent Hub) license and proxy are not required to host a SIP Backchannel configuration.

This document provides a high-level solution design for the scripting-only approach, 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

Architecture Diagram

Shared Responsibilities for the Script Integration Approach

Activity CXOne CUSTOMER Responsibility KORE Responsibility
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 scripts (2)		 - Minimal functionality Voice call scripts (2)
- Main Script: Accept call on DID
- Spawn Script: SIP Trunk 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:
SIP Main Script
SIP Spawn Script
Setup Authentication Configure CXOne Authentication to access the CXOne Signal API from the Kore bot.
Kore IVR Configuration
Setup Kore IVR Create an XO 11 account
Setup Voice Channel
SIP Trunk 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: TLS
Inbound Calls: Forward-to-PhoneNumber: same as DID		 SIP URI (pre-filled)
SIP Trunk Attach Flow Create a Flow
Attach SIP configuration to Experience flow
Kore XO 11 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 Trunk Configuration

  1. SIP Trunk Setup.
  2. Attach Flow.

Configuration in CXOne Studio

  1. Download the SIP Main Script and SIP Spawn Script 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.
      Import from File
    3. Open the saved studio script.
      Save Studio Script
      Entry Script Flow
      Place Call
    4. In the SIP Main Script, select the SIP Spawn Script in the Spawn action.
      Choose Script
    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.
        Enter Header Value
    6. Add the SIP Phone number in the Placecall action.
      1. Provide the SIP DID number you configured in the Kore XO 11 platform SIP Trunk in the PhoneNumber property in the Placecall action.
        Placecall
        SIP Number

XO11 Configuration

  • A flow should be configured with an app on XO 11.
    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);

Flow

Script Task

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 at the top right corner and select My Profile from the dropdown.
    My Profile
  3. Go to the ACCESS KEYS tab and Click the Add access key button.
    Access Keys
  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.

Bot Configuration

Configure a dialog task in Bot Builder to transition the request to NICE CXOne once the customer requests for agent transfer.

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.
    Rest API Call

  2. In the Service Node, select the Service Type as Custom Service and the Sub Type as REST.
    Edit Request

  3. Click EDIT REQUEST.

  4. Select POST in the API call method and enter the authentication URL in the requested URL field.
    POST Method

  5. Click the Headers tab.

  6. Add Content-Type in Key and application/json in Value fields.
    Content Type

  7. Click the Body tab and add the request body as follows:
    Body

  8. Click Test.

  9. Click Save as Sample Response.
    Save as Sample Response

Fetch the SIP Headers in the Bot

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

    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.

Trigger the Signal API on Kore Bot

  1. Add a Bot action with a service node to trigger the Signal API.
    Bot action-Signal API

  2. In the Service Node, select the Service Type as Custom Service and the Sub Type as REST.
    Signal API-Edit Request

  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&p3={{context.session.BotUserSession.conversationSessionId}}

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.

Post Signal API

  1. Click the Headers tab.

  2. Enter “Authorization” as the Key and "Bearer{{context.RestAPICall.response.body.access_token}}" as the value.
    Authorization

  3. Click Save.

Code Snippets

Main Script

Spawn Script