API Server Parameters and Data Types

The Uptivity API Server can be utilized by any program that can communicate over HTTP. It is important to understand parameters and their associated data type values to achieve the desired results when creating and sending commands. For more information, see API Overview.

Parameter Definitions

Field

Description

ALLOWSELFRECORD

Permission given to an agent

The person or people taking the inbound calls. allowing them to record their own calls. Possible values (Y/N).

ALLOWSELFDOWNLOAD

Permission given to an agent allowing them to download their recordings. Possible values (Y/N).

ACTION

Action associated with the request type. See the individual notes for the request type.

AGENTID

The identifier assigned to an agent by Uptivity. This ID is the internal system identifier used by Uptivity to associate agents to phone IDs, calls, and so forth.

AGENTINITIATED

Indicates whether a recording was initiated by the agent. Possible values (Y/N).

ANI

An acronym for Automatic Number Identification - ANI is a service of telecommunications carriers, which identifies the telephone number of the calling party. It is commonly used for billing, call routing and database synchronization. There are several specific technologies that fit under the umbrella of ANI, including caller ID.

An acronym for Automatic Number Identification. The number of the person calling the device (Caller ID).

ARCHIVEACTION

An archive action in Uptivity that specifies how long call recording files are maintained. The archive action ID number must be used. You can find the archive action ID number at Administration → System Settings → Archive Actions.

CALLCOUNT

Number of calls a user requests when using the CALLLIST function.

CALLDIRECTION

Denotes whether the call was inbound or outbound. Possible values (I/O).

CALLID

The call identifier that originally comes from the PBX

An acronym for Private Branch Exchange. A telephone switching device owned by a private company that serves a particular business or office..

CALLINSTANCE

Each call on a phone is considered an instance. For example, an agent is on a call with a customer. The agent puts the customer on hold to call a supervisor for assistance. The phone has two call instances.

COREIDENT

ID of the Uptivity Core used to record a call. For more information, see Managing CTI Cores.

COUNT

Number of items for a particular function such as number of channels. Varies by function.

CRM_USER

Name of the user in a customer relationship management system. For more information, see API Server Parameters and Data Types.

CTIINITIATED

Indicates whether a recording was initiated by a CTI event. Calls can also be initiated by API

An acronym for Application Program Interface. An API facilitates interaction between software components and specifies how they should interact. calls using NICE Uptivity On-Demand or by other applications. Possible values (Y/N).

DEVICEID

The physical number identifying a phone. This is usually the phone extension. In a free seating environment, this is the voice port or the DN of the phone. In other words, this is the fixed number identifying a device.

DEVICEALIAS

The logical number identifying a phone. In a free seating environment, this is usually the sign on number for the agent. This number is the variable number for a phone.

DNIS

An acronym for Dialed Number Indentification Service - A carrier service for 800/888 and 900 numbers that forwards the number dialed by the caller to the number that reaches the agent.

(Dialed Number Identification Service). Typically the number the caller dialed to reach the device that took the call. For outbound calls, this is the number dialed on the device (the number dialed by the agent). This can also be a code that the carrier assigns to the call to identify it as it comes in over the circuits.

DOMAIN

The Active Directory domain of a user’s Windows network account.

An email account address.

EMPLOYEEID

An optional employee ID that you can assign to an agent. This value is used for reporting only and is not used internally by Uptivity. For more information, see API Server Parameters and Data Types.

FILENAME

Path name of a call recording file.

FIRSTNAME

First name (or given name) of an agent.

GATE

An identifier for the call type as assigned by the PBX. This is also known as the skill set, vector, or application.

GROUP

The ACD

Acronym for Automatic Call Distributor - A device used to manage and distribute incoming calls to a specific group of terminals. group to which a device belongs.

GROUPID

QA Group ID number. Group IDs can be viewed from the Groups page (Administration > Groups). For more information, see QA Groups.

GROUPNAME

QA Group name.

Channel ID number in the Web Portal. For more information, see Voice Board Settings.

IDENT

Uptivity recording ID number.

ISRECORDING

Value that indicates if a device is recording.

ISTRUNK

Value that indicates if the recording device is a trunk.

KEEPDAYS

The number of days to store a record and associated files before purging.

KEYNAME

See CHATSTART in the API Server Commands topic.

KEYVALUE

See CHATSTART in the API Server Commands topic.

LASTNAME

Last name (surname or family name) of an agent.

LASTSTATECHANGE

Date and time that a device’s state changed (for example, from "Recording" to "Available").

LASTSTATECHANGEUNIXTIME

Date and time that a device’s state changed in the UNIX date/time format.

LOCATIONID

Unique identification key for a Location, stored in the database. For more information, see Locations.

MAXRECORDSILENCE

A time in seconds that the call may have silence before recording is ended. This option is only available on certain hardware types.

MAXRECORDTIME

A time in seconds specifying how long the call may last before recording is automatically ended. This limits the amount of time a recording will continue for a single call. Uses can be to automatically stop recording on a long call, or to conserve disk space in the event a stop message is not received.

PHONEID

User’s phone number, extension, device ID.

PRIORITY

A number from 0-100 denoting the priority of the call for recording purposes.

RECORDINGPATH

The system variable value specifying the default path for recordings.

RECORDINGSPACEINFO

A description of the amount of free disk space on the recording drive. For example: 22.35GB of 37.21GB.

RECORDINGTOTALDISKCAPACITY

The size of the disk specified on the recording path.

RECORDINGTOTALDISKFREE

The amount of free space on the disk specified on the recording path.

RECORDINGTOTALDISKFREEPCT

The percent of free disk space specified on the recording path.

REQUESTID

A number identifying a request. This number will be repeated in the result message as the request ID. This number must be a positive integer value and does not necessarily need to be unique. "2147483647" is the maximum REQUESTID that can be sent to the API. The API will send API_REQUESTID_INVALID as a return error if the value is higher.

SESSIONID

For CHATSTART, CHATUPDATE, and CHATSTOP, this value is provided by the client. For DEVICESTATUS and DEVICELIST, this value is based on the call and device.

STARTTIME

Time that recording started.

STATE

An integer value identifying the line state of a recording channel. Possible values are:

0 — On Hook
1 — Off Hook
2 — Recording
3 — Playback
4 — Waiting
5 — Error
6 — Resetting
7 — Recording Prep
8 — Finish Recording
9 — Dialing For Playback

STATIONNAME

STATIONNAME may be passed as the required item in place of DEVICEID in CALLSTART. If DEVICEID is not passed or is passed as a blank value, Uptivity will look up the DEVICEID based on the value from the COMPUTERNAME field.

STOPTIME

Time that recording stopped.

SYSTEMPROCESSORSPEED

A measured system processor speed. The reading in MHz.

SYSTEMPROCESSORTYPE

The description for the system processor that is stored in the system registry.

SYSTEMRAMTOTAL

Total amount of physical RAM in the system in megabytes.

SYSTEMRAMUSED

Total amount of physical RAM used in megabytes.

SYSTEMRAMFREE

Total amount of free physical RAM in megabytes.

SYSTEMRAMUSEDPCT

Percent of physical RAM used.

SYSTEMUPTIME

Uptime for the system in days, hours, minutes, and seconds.

SYS_USER

This value is used to associate a network user to an agent defined in the Uptivity system and should equal the network username (not the Uptivity username) of the agent. This association is used to grant them the proper access rights (such as phone IDs that they may record and download permissions).

TIMEOFFSET

Number of seconds to offset (that is, increase/decrease) the stop time of the blackout. This value can be a positive or negative integer.

UNIQUEFIELD

This can be any column from the Uptivity database’s Recording table, such as:

agent_id	ani	archive_action_id	audio_hash	audio_size
Calldirection	callid	channel	device_alias	device_id
dnis	duration	filename	filename_video	gate
globalid	Ident	keepdays	locked	listenedto
mediaLabel	overridden	priority	qa_forms	qa_group_id
qa_poss_score	qa_score	recording_time	recording_type	screen_capture
sgroup	user1	user2	user3	user4
user5	user6	user7	user8	user9
user10	user11	user12	user13	user14
user15	video_hash	video_size	wrap_duration

UNIQUEID

This is a value in the column specified by the UNIQUEFIELD parameter. Together, these parameters identify a recording record in the Recording table.

UPDATE_IF_NOT_RECORDING

When this parameter is present and set to Y, the update command will update the last call recorded for the device if the device is not currently being recorded when the update command is called. Possible values (Y/N).

USER1-15

Variables that you may use to add your own custom information to be stored with the call record. These values are stored as ASCII text.

(**) Updates to these fields using some special characters and symbols may not work correctly. Test all possible characters needed before using this function.

USERNAME

Username in Uptivity.

Data Type Values

Charts in this section specify how data is stored in the Uptivity database. REQUEST and RESPONSE XML messages to and from the API Server pass these values as strings. The API converts the items to the appropriate data type when writing values to the database.

Call Handling Data Types

Functions: CALLSTART, CALLSTOP, CALLUPDATE,RECORDSTART, RECORDSTOP

Parameter	Value Type
REQUESTID	integer (signed 32-bit)
DEVICEID	char(64)
CALLINSTANCE	TBD
DEVICEALIAS	char(15)
GROUP	char(20)
GATE	char(20)
ANI	char(20)
DNIS	char(20)
USER1-USER3	varchar(20)
USER4-USER8	varchar(255)
USER9-USER15	varchar(50)
CALLID	char(16)
PRIORITY	integer (signed 32-bit)
CALLDIRECTION	char(1) (‘I’,’O’,’?’)
MAXRECORDSILENCE	integer (signed 32-bit)
MAXRECORDTIME	integer (signed 32-bit)
AGENTINITIATED	char(1) (‘Y’,’N’)
CTIINITIATED	char(1) (’Y’,’N’)
STATIONNAME	char(50)
UPDATE_IF_NOT_RECORDING	char(1) (‘Y’,’N’)
ARCHIVEACTION	bigint(8)
SYS_USER	char(30)
CRM_USER	char(30)
KEEPDAYS	TBD

Status Data Types

Functions: DEVICELIST, DEVICESTATUS, DEVICERECORDINGSTATUS

Parameter	Value Type
REQUESTID	integer (signed 32-bit)
DEVICEID	char(64)
DEVICEALIAS	char(15)
SYS_USER	char(30)
CALLDISCRIMINATOR	char(64)
CRM_USER	char(30)
GROUP	char(20)
GATE	char(20)
ANI	char(20)
DNIS	char(20)
USER1-USER3	varchar(20)
USER4-USER8	varchar(255)
USER9-USER15	varchar(50)
CALLDIRECTION	char(1) (‘I’,’O’,’?’)
ISTRUNK	Boolean
STATION	char(128)
ISRECORDING	Boolean
FILENAME	char(255)
CALLID	char(30)

Function: SYSTEMSTATUS

Parameter	Value Type
REQUESTID	integer (signed 32-bit)
RECORDINGPATH	string
RECORDINGSPACEINFO	string
RECORDINGTOTALDISKCAPACITY	float
RECORDINGTOTALDISKFREE	float
RECORDINGTOTALDISKFREEPCT	float (%2f)
SYSTEMPROCESSORSPEED	string
SYSTEMPROCESSORTYPE	string
SYSTEMRAMTOTAL	integer (signed 64-bit)
SYSTEMRAMFREE	integer (signed 64-bit)
SYSTEMRAMUSEDPCT	integer (unsigned 32-bit)
SYSTEMUPTIME	String

Function: CHANNELS

Parameter	Value Type
REQUESTID	integer (signed 32-bit)
COUNT	Integer (signed 32-bit)
ID	integer (signed 32-bit)
STATE	String
LASTSTATECHANGE	String
LASTSTATECHANGEUNIXTIME	String

Function: STATIONS

Parameter	Value Type
REQUESTID	integer (signed 32-bit)
COUNT	integer (signed 32-bit)
STATIONNAME	char(50)
DEVICEID	char(64)

Function: FETCHTERMINOLOGY

Parameter	Value Type
REQUESTID	integer (signed 32-bit)
COUNT	integer (signed 32-bit)
NAME	varchar(255)
VALUE	varchar(255)

Function: CALLLIST

Parameter	Value Type
REQUESTID	integer (signed 32-bit)
DEVICEID	char(64)
CRM_USER	char(30)
SYS_USER	char(30)
DEVICEALIAS	char(15)
GROUP	char(20)
GATE	char(20)
ANI	char(20)
DNIS	char(20)
CALLCOUNT	NA
CALLDATESTART	bigint(8)
CALLDATEEND	bigint(8)
USER1- USER3	varchar(20)
USER4-USER8	varchar(255)
USER9- USER15	varchar(50)

Recording Control Data Types

Function: CHATSTART, CHATSTOP, CHATUPDATE

Parameter	Value Type
REQUESTID	integer (signed 32-bit)
SESSIONID	char(255)
AGENTID (USERID)	integer (signed 32-bit)
KEYNAME	string values USERNAME, EMPLOYEEID
KEYVALUE	char(255)
DEVICEALIAS	char(15)
GROUP	char(20)
GATE	char(20)
ANI	char(20)
DNIS	char(20)
USER1-USER3	varchar(20)
USER4-USER8	varchar(255)
USER9-USER15	varchar(50)
CALLDIRECTION	char(1) (‘I’,’O’,’?’)
CALLID	char(16)

Function: BLACKOUTSTART, BLACKOUTSTOP

Parameter	Value Type
REQUESTID	integer (signed 32-bit)
DEVICEID	varchar(64)
DEVICEALIAS	varchar(100)
CRM_USER	varchar(50)
SYS_USER	varchar(255)
CALLINSTANCE	TBD

Import Data Types

Function: IMPORTUSER, IMPORTAGENTPHONE

Parameter	Value Type
REQUESTID	integer (signed 32-bit)
ACTION	string values ADD, DELETE, MODIFY
AGENTID	integer (signed 32-bit)
FIRSTNAME	char(20)
LASTNAME	char(30)
SYS_USER	varchar(255)
DOMAIN	char(30)
EMAIL	char(255)
EMPLOYEEID	char(20)
ALLOWSELFRECORD	char(1) (‘Y’,’N’)
ALLOWSELFDOWNLOAD	char(1) (‘Y’,’N’)
ALLOWDUPLICATE	char(1) (‘Y’,’N’)
STATUS	char(1) (‘A’ - Active, ’I’ - Inactive)
SYS_DOMAIN	TBD
SITE_ID	TBD
MOBILE_ID	TBD
PHONEID	char(10)
DEVICEID	char(15)
STATIONNAME	char(50)
LOCATIONID	integer (signed 32-bit)

User, Group and Role Data Types

Function: ADDGROUP, MODIFYGROUPPERMISSION, MODIFYUSERGROUPPERMISSION

Parameter	Value Type
REQUESTID	integer (signed 32-bit)
ACTION	string values ADD, MODIFY
GROUPNAME	char(255)
GROUPID	integer (signed 32-bit)
DEVICEID	char(64)
USERNAME	char(16)
PHONEID	char(10)
FIRSTNAME	char(20)
LASTNAME	char(30)
AGENTID	integer (signed 32-bit)

Function: EMAIL

Parameter	Value Type
REQUESTID	integer (signed 32-bit)
UNIQUEFIELD	varchar(255)
UNIQUEID	varchar(255)
TOADDRESS	varchar(255)
TONAME	varchar(255)
FROMADDRESS	varchar(255)
FROMNAME	varchar(255)
MEDIA_FORMAT	varchar(3)
IDENT	varchar(255)

Function: AGENTWINDOW

Parameter	Value Type
REQUESTID	integer (signed 32-bit)
COMPUTERNAME	varchar(255)
USERNAME	varchar(255)
DOMAIN	varchar(255)
IPADDRESS	varchar(255)
STATUS	varchar(255)
APPLICATIONTITLE	varchar(255)
LASTUPDATE	varchar(255)