Enable Analytics-Based Text Routing

You can use the NiCE CXone analytics-based text routing (ABTR) service to analyze incoming text interactions and route them based on the dataset, priority, sentiment, language, or a combination of these factors. ABTR sends interaction text to the routing service for analysis. The service returns annotated data that your script uses to route the interaction to an appropriately skilled agent.

Every ABTR script follows the same three-part flow:

  1. Authenticate against the NiCE CXone API to get an access token.
  2. Call the ABTR annotation service with the interaction text. The service returns the access token to analyze it.
  3. Use the returned data, such as sentiment, language, and category, to determine how to route the interaction.

Enabling ABTR requires using Integration Hub to store the credentials in an encrypted format.

Before You Begin

Register Interaction Analytics (CXone) with NiCE CXone to get an access key ID and access key secret. Follow the registration and authentication Icon of a square with an arrow pointing out the top right corner process explained on the developer portal.

You must include these credentials in your API calls. Follow the registration and authentication process described in the developer portal.

Ensure you have Integration Hub enabled on your system.

Create Requests in Integration Hub

Required permissions: ACD > Studio > Studio Scripts Edit, Launch Connections Hub

  1. In Integration Hub, create a connection template and a connection for the ABTR annotation service.
  2. Set Authentication Type to OAuth 2.0 and include POST as an available verb.
  3. On the connection's Authentication tab, configure the authentication request:
    1. Set URL to https://cxone.niceincontact.com/auth/token.
    2. Set REST Method to POST.
    3. Add your access key ID and access key secret as encrypted variables (secrets) on the connection's Variables tab, then reference them in the authentication body using double brackets. For example: [[accessKeySecret]].
  4. On the connection's Requests tab, add a Studio request for the annotation call:
    1. Enter a Request Name, such as Annotate Text.
    2. Set Trigger to Studio.
    3. Copy the example request payload that Integration Hub provides.
    4. Use the example request payload to build a dynamic object in a SNIPPET action with the URL https://analytics.incontact.com/studio-gateway/annotate, the POST method, and a body that includes the interaction text you want to analyze.
  5. In Studio, open your routing script.
  6. Add a CONNECTAUTH action and link it to your connection to authenticate and retrieve the access token.
  7. Add a CONNECTREQUEST action and link it to the Studio request you created to send the interaction text to the annotation service.
  8. Use the response from the CONNECTREQUEST action to build your routing logic.

Build Your Routing Logic

Required permissions: ACD > Studio > Studio Scripts Edit, Launch Connections Hub

Whichever method you use, the ABTR service returns a JSON response that includes:

  • documentSentiment: The overall sentiment of the interaction, such as POSITIVE or NEGATIVE.
  • language: The detected language of the interaction text.
  • frustration.frustrationType: The detected frustration level, such as HIGH.
  • categories: A list of matched categories, each with a categoryPath you can check against categories of interest.

You can use a SNIPPET action to parse this response and build your routing logic. This doesn't make an API call, so it isn't subject to the performance concerns of using SNIPPET for REST calls.

The following example assigns a skill based on language, frustration, sentiment, and category. Replace [result] with the name of the variable that holds your response, such as your REST API action's Result Set output or your CONNECTREQUEST action's response variable. Customize the logic to fit your own routing needs.

//The sentiment, language, frustration, and categories variables are pulled from the response.
ASSIGN sentiment=[result].documentSentiment
ASSIGN language=[result].language				
ASSIGN customerFrustration=[result].frustration.frustrationType				
ASSIGN categories=[result].categories				
ASSIGN categoryCount=categories.count()				
IF language = "english"	
{			
 IF customerFrustration = "HIGH" && sentiment = "NEGATIVE"			
  {
   ASSIGN SkillNo=123456 //Example text: "I'm very frustrated."				
  }				
 ELSE				
 {
  IF categoryCount > 0				
  {				
   //Cycle through categories to find a match to a category of interest.				
   //This example looks for a Shipping contact purpose.				
   ASSIGN SkillNo=123457 //Default skill when categories exist but none matches.										   FOR i = 1 TO categoryCount			
   {				
    IF categories[i].categoryPath = "Contact Purpose/Transaction/Shipping"				
    {				
     ASSIGN SkillNo=123458 //Example text: "Where is my shipment?"				
    }				
   }
  }				
 ELSE				
  {				
  ASSIGN SkillNo=123457 //Example text: "Nothing to see here."				
  }
 }				
}				
ELSE
{				
 ASSIGN SkillNo=123459 //Example text for a non-English interaction.
}