API Server Web API Service

The NICE Uptivity API Server can be utilized by any program that can communicate over HTTP. The WebAPI service accepts specially-formatted URLs that contain API data and translates the URL into a Uptivity API function call which is then executed by the API Server. This allows the same API functionality as the API socket service provider for users more familiar with or applications only capable of making HTTP requests.

For more information, see API Overview.

General Architecture Overview

The NICE Uptivity Web API Service runs on the Uptivity server via a custom HTTP listener. Proper network firewall, security, and access measures must be in place to allow a custom or third-party application to access the server.

An example of WebAPI service calls is shown in this diagram.

The WebAPI service is a built-in component on every Uptivity system. The service has custom configuration options that must be set, and all calls to the service must follow the syntax that is accepted by the WebAPI.

TCP Port Settings

By default, the web service runs on port 2012 (2013 if SSL is used). These port settings can be modified if needed. See API Server Settings for more information on API Server configuration settings.

To call the WebAPI properly, you must pass the API web service port number in the URL. The port number syntax is highlighted in the examples below.

Non SSL-Enabled Connections Example:

http://discoverserveraddress:2012/webAPI.aspx

SSL-Enabled Connections Example:

https://discoverserveraddress:2013/webAPI.aspx

WebAPI Call Syntax

To use the WebAPI functions, requests are passed to a specially-formatted URL that is accepted by the WebAPI service. An example of a WebAPI request call is below:

http://ccserveraddress:2012/webAPI.aspx?type=callupdate&requestid=18213567&deviceid=200&user1=SpecialCall&user2=10121968&keepdays=3650

Each request call must include the following:

  • Protocol Identifier — This determines whether the call will be sent as plain text or will use SSL encryption. For plain text, set the value to HTTP. For SSL encryption, set the value to HTTPS.
  • Host Address — This is the hostname or IP Address of the server running the Uptivity API Service.
  • TCP Port — This is the port number on which the API Service is listening for web requests.
  • API Page — Calling this page allows an application to access any functions in the Uptivity API, or allows an application access retrieve recorded audio files for any purpose, be it immediate playback or long-term storage. The value can be either /webAPI.php or /webAPI.aspx.
  • Function Type — This indicates which API function you are passing to the API Service.
  • Function Parameters — These are the required and optional parameters for the specified API function as defined for each function call type (call handling, status, and so forth). All API functions are available via the WebAPI method. For more information, see API Server Parameters and Data Types

To make a successful WebAPI call, the API function parameters must be passed to the WebAPI page. The parameters are passed using the question mark (?) character, and each parameter is delimited by the ampersand (&) character. The desired value for each API parameter is set using an equal (=) sign, followed directly with the desired value for that parameter. Parameters are case-insensitive.

You cannot use the same parameter more than once in a single WebAPI call as the parameters will be combined before passing to the Uptivity API. For example:

  • Your WebAPI call contains “deviceid=1234&deviceid=5555”.
  • The values are combined into the comma-separated list “deviceid=1234, 5555” before the Uptivity API receives the command.
  • The Uptivity API treats this as a single value “1234,5555” and not two separate DeviceIDs.

If your call contains duplicate parameters with different casing (for example, “deviceid=1234&DEVICEID=5555”), the API returns an error message: “parameters must be unique but duplicates were found.” However, if you use multiple parameters with the same casing (for example, “deviceid=1234&deviceid=5555”), the command simply will not return the correct results.

Examples of WebAPI Calls

Update a Call Record

This example will update/mark the record with the listed data using the CALLUPDATE function. This function must be passed while the call is being actively recorded. For parameter requirements, see CALLUPDATE in API Server Commands.

The WebAPI call should be formatted as follows:

http://ccserveraddress:2012/webAPI.aspx?type=callupdate&requestid=18213567&deviceid=200&user9=SpecialCall&user10=10121968&keepdays=3650

This example URL was constructed from the following components:

  • Protocol — http
  • Host Address — ccserveraddress
  • TCP Port — 2012
  • API Page — WebAPI.aspx
  • Function Type — callupdate
  • Parameters:
    • RequestID — A unique identifier for the transaction generated by the user making the WebAPI call. The value must be an integer. In the example, the value is 18213567.
    • DeviceID (required) — The phone extension for the call being recorded. In the example, the value is 200.
    • User9 — Custom-defined field (in this example, used to display a text phrase). In the example, the value is SpecialCall.
    • User10 — Custom-defined field (in this example, a transaction ID number). In the example, the value is 10121968.
    • Keepdays — The number of days this record will be maintained before being purged. In the example, the value is 3650.

Export a Recorded Audio File

EXPORT is a function type unique to the WebAPI. This function allows Uptivity to export recorded media from a call any time after recording has completed.

The EXPORT function supports exporting audio only in the following formats: WAV (PCM), MP3, and VOX. You can also export the entire recording, including metadata, using the proprietary CAV format.

The EXPORT function has three required parameters: UNIQUEFIELD, UNIQUEID, and MEDIA_FORMAT. These parameters are used to identify the desired audio file and specify the export format.

  • UNIQUEFIELD — Parameter name that contains the identifying information for the record. This can be any parameter inserted from a Call Handling API function, or any parameter returned from a DEVICELIST or DEVICESTATUS API function. The parameter used must contain data that is unique to an individual record. Any parameters that will not contain unique data (such as deviceid or devicealias) will return the most recent record that contains matching data. The possible values for UNIQUEFIELD are listed in API Server Parameters and Data Types.
  • UNIQUEID — Value in the UNIQUEFIELD parameter that uniquely identifies the record.
  • MEDIA_FORMAT — File format of the exported audio file.

Optional parameters ENCRYPT and PASSWORD may be used to encrypt an exported CAV file.

  • ENCRYPT — Used to encrypt the exported CAV file, requires PASSWORD.
  • PASSWORD — Password used to access the encrypted exported CAV.

The WebAPI call should be formatted in the following manner:

http://ccserveraddress:2012/webAPI.aspx?type=export&requestid=10482345&uniquefield=user2&uniqueid=10121968&media_format=mp3&encrypt=Y&password=test

This example URL was constructed from the following components:

  • Protocol — http
  • Host Address — ccserveraddress
  • TCP Port — 2012
  • API Page — WebAPI.aspx
  • Function Type — export
  • Parameters:
    • REQUESTID — Unique identifier for the transaction generated by the user making the WebAPI call. The value must be an integer. In the example, the value is 10482345.
    • UNIQUEFIELD — Required parameter name that contains identifying information for the record. In the example, the value is the user-generated transaction ID user2.
    • UNIQUEID — Value contained in the UNIQUEFIELD parameter for the record. In the example, the value is 10121968.
    • MEDIA_FORMAT — File format of exported audio file. In the example, the value is mp3.
    • ENCRYPT — Optional parameter used to encrypt exported CAV file. In the example, the value is Y.
    • PASSWORD — Required parameter if encryption is used. In the example, the value is test.

Possible error returns are:

  • API_FILE_NOT_FOUND — Appears if the specified file cannot be found.
  • API_INVALID_MESSAGE_FORMAT — Appears if parameters are missing or the request is not formatted correctly.

Export Multiple Recorded Audio Files

COMBINEDEXPORT is unique to the WebAPI. This function type combines multiple audio files into a single file (post-recording) and exports the file in the specified format. It uses these values:

  • IDENT — These are comma-separated call record IDs.
  • MEDIA_FORMAT — File format of the exported audio file.

The COMBINEDEXPORT call should be formatted in the following manner:

http://ccserveraddress:2012/webAPI.aspx?type=combinedexport&requestid=10482345&ident=10121967,10121968,10121969&media_format=mp3

This example URL was constructed from the following components:

  • Protocol — http
  • Host Address — ccserveraddress
  • TCP Port — 2012
  • API Page — WebAPI.aspx
  • Function Type — combinedexport
  • Parameters:
    • REQUESTID — Unique identifier for the transaction generated by the user making the WebAPI call. The value must be an integer. In the example, the value is 10482345.
    • IDENT — Required parameter specifying the recordings to be combined. In the example, the values are the comma-separated call record IDs 10121967,101219168,10121969.
    • MEDIA_FORMAT — File format of exported audio file. In the example, the value is mp3.

Possible error returns are:

  • API_FILE_NOT_FOUND — Appears if the specified file cannot be found.
  • API_INVALID_MESSAGE_FORMAT — Appears if parameters are missing or the request is not formatted correctly.

Export Multiple Recorded Audio Files as a ZIP File

MULTIEXPORT is unique to the WebAPI. This function type combines multiple audio files into a ZIP file (post-recording) and exports that file. It only uses these values:

  • IDENT — These are comma-separated call record IDs.
  • MEDIA_FORMAT — File format of the exported audio file.

The MULTIEXPORT call should be formatted in the following manner:

http://ccserveraddress:2012/webAPI.aspx?type=multiexport&requestid=10482345&ident=10121967,10121968,10121969&media_format=mp3

This example URL was constructed from the following components:

  • Protocol — http
  • Host Address — ccserveraddress
  • TCP Port — 2012
  • API Page — WebAPI.aspx
  • Function Type — multiexport
  • Parameters:
    • REQUESTID — Unique identifier for the transaction generated by the user making the WebAPI call. The value must be an integer. In the example, the value is 10482345.
    • IDENT — Required parameter specifying the recordings to be combined. In the example, the value is comma-separated call record IDs 10121967,101219168,10121969.
  • MEDIA_FORMAT — File format of exported audio file. In the example, the value is mp3.

Possible error returns are:

  • API_FILE_NOT_FOUND — Appears if the specified file cannot be found.
  • API_INVALID_MESSAGE_FORMAT — Appears if parameters are missing or the request is not formatted correctly.

See Also