APIs and Scripts

The information on this help page applies to both Studio and Desktop Studio.

In your Studio scripts, you can connect to web services that use SOAP or RESTful API standards.

Supported Options

Studio supports the following ways of connecting to web services:

Option Details
REST API Studio action

The REST API  Studio action allows you to make RESTful API calls from your scripts. This method: 

  • Can handle higher loads compared to making RESTful calls in a SNIPPET action, particularly at scale.
  • Is the preferred method of making API calls in scripts.
  • Is one of the options to use if your calls include JSON.

Integration Hub

Integration Hub is a NiCE CXone application that enables you to configure authentication and API requests to use in the platform. It also allows you to store sensitive data, such as passwords or keys, in an encrypted format to use in scripts.

The CONNECTREQUEST action and the CONNECTAUTH action allow you to use the configured authentication details and requests in your scripts.

Integration Hub is the other option to use if your calls include JSON.
NiCE CXone API  Studio actions  Studio has numerous API actions that allow you to make calls to NiCE CXone APIs from your scripts. Not every NiCE CXone API is available as an action, but when one is available, you should use it instead of another method. You can find the API actions in the API section of the Framework tab in Desktop Studio and the API Actions palette in Studio.
SNIPPET actions

You can write code in a SNIPPET action to connect to RESTful or SOAP web services from your script. This is not the recommended method for making REST calls because it can slow down contact handling and cause serious performance issues with the platform. However, you must use this method if:

  • Your calls include XML. 
  • You are connecting to a SOAP service.

If you must use SNIPPET, review the recommendations for minimizing the impact on your system before connecting to RESTful or SOAP web services.

CRM workflow integrations Set up CRMClosed Third-party systems that manage such things as contacts, sales information, support details, and case histories. workflow integrations when you need to make API calls to your organization's CRM. This is supported in Agent Workspace (Agent), Agent Workspace (Embedded) (Agent Embedded), and Agent Workspace (Browser Extension) (Agent Integrated).

Limitations on Returned Data Size

The NiCE CXone platform lets REST APIs return up to 32 KB of data. This limit prevents cluster instability and outages. It is strictly enforced.

This limit applies to any method of connecting to web services, including the REST API action, Integration Hub, and making calls with the SNIPPET action. If you can, use the REST API action instead of the SNIPPET action for your REST APIs. REST API has a return limit of 32 KB, but it can handle a heavier load than the SNIPPET method can.

To reduce the size of your returned data:

  • Filter the data in the API response: For example, if you're using the NiCE reporting API to get contacts, you can filter the results by the startDate and endDate of the contact. This API call also allows you to return and limit a top count of items. Refer to the API documentation that came with your script integration to determine what filtering you can use.

  • Update the API request to return only the data you need: For example, if you're using the NiCE reporting API to get contacts, you can use the contactId or agentId fields to return only relevant data. Refer to the API documentation that came with your script integration to determine what data limits you can use.

  • Build middleware: If you cannot do either of the previous options, build middleware that does filtering based on custom criteria you define. If you do this, ensure that your middleware does not add latency to the call.

 

-1 Error Code

The -1 error code is an internal code used to identify that an error has been encountered with an API call. Specifically, this code indicates that it's a situation where an HTTP status code will not be returned, or where it is returned but cannot be passed on to the script.

The status description that accompanies the -1 error code can help you determine the issue. The status descriptions that can accompany this code include: 

  • The request was aborted: The operation timed out. The request may or may not have been processed. Validation should occur before setting up a loop in response to a -1 status code. You may need to change the timeout setting in the call using the ProxyTimeoutSeconds property.

  • Invalid JSON Primitive. The JSON parser was confused by the response. The response may have included invalid characters or wasn't JSON. Often, this error occurs when the response is sent in HTML. You can test the response in the snippet debugger. The REST API Response is not valid JSON or XML A square with an arrow pointing from the center to the upper right corner. knowledge base article may help.

  • Data at the root level is invalid. The XML parser was confused by the response. The response may have included invalid characters or wasn't XML. Often, this error occurs when the response is sent in HTML. The REST API Response is not valid JSON or XML  A square with an arrow pointing from the center to the upper right corner. knowledge base article may help.

  • 'doctype' is an unexpected token. The expected token is 'DOCTYPE'. See Data at the root level is invalid in this list.

  • The 'br' start tag on line x position x does not match the end tag of 'body'. See Data at the root level is invalid in this list.

  • The underlying connection was closed: An unexpected error occurred on a send. Often this means that there is a problem with the TLS handshake. It can also be caused by an IP or port not being open on a firewall; using an old, unsupported version of TLS; invalid or expired certificates; using an IP address in combination with HTTPS; or similar issues. Troubleshoot this response with the firewall logs on the receiving server side.

  • The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel. See The underlying connection was closed: An unexpected error occurred on a send in this list.

  • The request was aborted: Could not create SSL/TLS secure channel. See The underlying connection was closed: An unexpected error occurred on a send in this list.

  • Response too large. (> 32 KB). The response contains more than 32 KB of data. When this happens, the response is discarded because the system has no way of storing more than 32 KB in one variable. The response must be modified or filtered to reduce the amount of data returned.