Example Custom Virtual Agent Integration

NICE CXone developed a sample proxy tunnel for you to use. You can set up this example custom integration to gain a better understanding of how custom integrations work. This example simulates a custom text virtual agent integration using CXone ACD chat.

The sample code in this example is different from the proxy tunnel used in an actual integration. In a real integration, the proxy tunnel is set up to communicate with a virtual agent's endpoints. The sample code doesn't communicate with an actual virtual agent. Instead, it's configured to echo back the input from the user who tests it. So if you type Hello chatbot in the test window, the reply is Hello chatbot.

To set up the example integration, you must download and install the sample proxy code in your environment. The sample proxy tunnel is available in several different programming languages. Your team can use the language they're most comfortable working with.

The template for the custom virtual agent integration technical design document (TDD) includes examples based on this example integration. The examples in the TDD template can help you better understand a custom virtual agent integration.

Some links on this page open sites outside of the CXone online help.


To test the example integration, you must have: 

  • Studio installed on your computer.
  • Downloaded the sample code ZIP file. Sample code is available in the following languages:
    • C# .NET
    • Java
    • Node.js
    • PHP
    • Python
  • IDE and compiler dependencies for the language of the sample code you're using:
    • C# .NET: VS Code or other code editor.
    • Java: VS Code Community, Jet Brains, Net Beans, Intelli J, Eclipse, or others. If you use the VS Code editor, you need to download and install the Java Extension pack from the Visual Studio Marketplace website.
    • Node.js: NPM.
    • PHP: VS Code or other code editor.
    • Python: VSCode or other code editor.
  • Ngrok installed on your computer. You can find the installation on this site: https://ngrok.com/download.

Complete each of these tasks in the order given.

Set Up the Proxy Tunnel Endpoint

Run this API call on a localhost port. Copy down the port number that the service runs on. You will need the number in a later step. Click the drop-down to view instructions for setting up the endpoint for each available language.

Expose Proxy Tunnel Endpoint

The proxy tunnel endpoint must be exposed so that CXone can access it globally. Use Ngrok to expose the endpoint.

  1. Install Ngrok, if you haven't done so already.
  2. Start Ngrok using this command from the command prompt:

    ngrok http [port number]

    where [port number] is the port number you wrote down when setting up the endpoint.

  3. Copy the server URL that Ngrok exposes and the required API endpoints.

    In the example image, the exposed URL is https://4db3-5-46-62-207.nrgok.io. The is base URL for the webhook. Determine which endpoint to use with your URL. Save the URL to use when you configure the textbot Studio action in a later task.

The steps to determine the endpoint that are described in this section apply only to the example integration. When you create your own endpoint, it can be anything that meets the needs of your organization.

Set Up a Simple Chat Script in Studio

  1. Download this simple chat script.
  2. Extract the TextBotExchangeExample.xml file to your computer.
  3. In Studio, click FileImport from File, select the extracted file, and click Open.
  4. Save the script. Remember the name you give the script. Leave the script open. You will return to it in a later task.

Create a Chat Skill and Point of Contact in CXone

You need to create a chat skillClosed Used to automate delivery of interactions based on agent skills, abilities, and knowledge and point of contactClosed The entry point that an inbound contact uses to initiate an interaction, such as a phone number or email address.. The point of contact calls the script you imported. This is how CXone routes contacts to your virtual agent.

  1. In CXone, click the app selector and select ACD.
  2. Click Contact Settings ACD Skills and create a chat skill. You must give the skill a Name and assign it to a Campaign. You may want to create a campaign to use for the sample integration. You can accept the defaults for all other skill options.
  3. Go to Contact Settings Points of Contact and create a point of contact with the following settings:

    • Media Type: Select Chat.
    • Script: Select the name of the script you imported to use with the example integration.
    • Skill: Select the name of the skill you created in this task.
  4. After you create the point of contact, copy the Point of Contact URL displayed on the Details tab. Paste it into a tab in your browser. You will use this URL in a later task to test the script.

Configure the Textbot Exchange Action

This step configures CXone to communicate with the sample proxy tunnel endpoint.

  1. In Studio, open the sample script you imported, if it's not already open.
  2. Double-click one of the Textbot Exchange actions to open Virtual Agent Hub.

  3. Click Add Bot.
  4. Enter a Virtual Agent (Bot) Name, then select Custom Exchange Endpoint as the Bot Provider.
  5. Click Next.
  6. Enter your Webhook URL. This is the URL you saved after exposing the proxy tunnel endpoint.
  7. Click Next.
  8. On the Voice page, select Text Only under Voice Integration Options, then click Next.
  9. On the Test + Add page, click Start with welcome intent. Test other options, such as sending custom payload, as desired. If there are no errors, continue to the next task. If your test results in errors, review the previous tasks to verify the set up and exposure of the proxy tunnel endpoint and the configuration in Virtual Agent Hub.

Test the Script from a Chat Window

When you have resolved any errors that occurred while testing the configuration of the Textbot Exchange action, you can test the script using the point of contactClosed The entry point that an inbound contact uses to initiate an interaction, such as a phone number or email address. URL you copied in a previous task.

  1. In Studio, open the sample script you imported.
  2. Click Debug > Capture ScriptNext Instance Only.
  3. In the browser tab where you pasted the point of contact URL, type a message in the Enter your text field and click Send.
  4. In Studio, the Trace Output window opens. It displays the progress of the script as you send messages and the script responds.

    Click an action in the main pane in the Trace Output window.

    • The Variables tab shows all of the variables that exist in the script when the selected action has completed. It also shows the value that each variable holds at that point in the script.
    • The Properties tab shows you the properties for the selected action. You can use this to verify the action's current configuration.
  5. Return to the script and make changes, if necessary.
  6. To access the online help for an action, select it on the canvas and press F1 on your keyboard. The online help page for each action describes the properties and other information about using the action in a script.
  7. If you want to start over, click End Chat, refresh the browser window, and repeat this process, starting with step 2.