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¶
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
- Skills creation and mapping: 1 skill
- Hours Of Operation: 1
- Points of Contact: 1 (Phone)
- Campaign: 1
- Minimal functionality Voice call script: 2
Kore Bot Platform¶
Telephony Gateway Requisites¶
- DID or TFN phone number to receive the call.
- All SIP header information.
- How to configure Signal API to return control to the NICE CXone platform.
Kore SIP Trunk Configuration¶
Configuration in CXOne Studio¶
- Download the SIP Main Script and SIP Spawn Script and save it locally.
- Import the Studio Script as follows:
- Login to NICE CXOne Studio with your credentials. Learn more.
- On the File menu, select Import from File.
- Open the saved studio script.
- In the SIP Main Script, select the SIP Spawn Script in the Spawn action.
- Add SIP headers in the Sipputheader actions.
- Add the SIP Phone number in the Placecall action.
XO 11 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);
NICE CXone Authentication¶
The following parameters are required for authenticating before calling any CXOne API:
- Authentication API URL from NICE CXone.
- Access key ID.
- Access key secret.
Steps to authenticate NICE CXOne:
- Login to the NICE Cluster.
- Click your profile at the top right corner and select My Profile from the dropdown.
- Go to the ACCESS KEYS tab and Click the Add access key button.
- Copy the Access Key ID and Access Key Secret. This is used to get the access token to be used by the signal API.
- 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
- Send the following POST request body:
- 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¶
-
Add a bot action with a Service Node in the flow to get the access_token.
-
In the Service Node, select the Service Type as Custom Service and the Sub Type as REST.
-
Click EDIT REQUEST.
-
Select POST in the API call method and enter the authentication URL in the requested URL field.
-
Click the Headers tab.
-
Add Content-Type in Key and application/json in Value fields.
-
Click Test.
- Click 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.
-
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¶
-
Add a Bot action with a service node to trigger the Signal API.
-
In the Service Node, select the Service Type as Custom Service and the Sub Type as REST.
-
Click Edit Request.
- Choose the API method as POST.
-
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)
!!! Notehttps://api-{cluster}.NICE-incontact.com/incontactapi/services/v28.0/interactions/{{context.session.BotUserSession.ContactId}}/signal?p1=AgentHandoff&p3={{context.session.BotUserSession.conversationSessionId}}
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.
-
Click the Headers tab.
-
Enter “Authorization” as the Key and
"Bearer{{context.RestAPICall.response.body.access_token}}"
as the value.
-
Click Save.