APIs and Scripts

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 than making RESTful calls in a SNIPPET action, particularly at scale. Is the preferred method of making API calls in scripts. Is the option to use if your calls include JSON.
CXone API Studio actions	Studio has numerous API actions that allow you to make calls to CXone APIs from your scripts. Not every 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 CXone 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. However, you must use this method if: Your calls include XML. You are connecting to a SOAP service.

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 than making RESTful calls in a SNIPPET action, particularly at scale.
Is the preferred method of making API calls in scripts.
Is the option to use if your calls include JSON.

CXone API Studio actions

Studio has numerous API actions that allow you to make calls to CXone APIs from your scripts. Not every 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 CXone 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. However, you must use this method if:

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

Limitations on Returned Data Size

The 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 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 documentation for the API you're calling 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 documentation for the API you're calling determine what data limits you can use.

If you can't do either of the previous options, build middleware.

-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 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 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.