API Server Parameters and Data Types

Parameter Definitions

ALLOWSELFRECORD
Permission given to an agent 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
(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. For information on archive action IDs, see Archive Action List.
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.
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 CTI Cores List.
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 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
(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.
EMAIL
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 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 Page.
GROUPNAME
QA Group name.
ID
Channel ID number in the Web Portal. For more information, see Voice Board Settings.
IDENT
Uptivity recording ID number. For more information, see Call List.
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 List.
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
STATION
Windows workstation. See also STATIONNAME.
STATIONNAME
This field can simultaneously serve two purposes.
  • 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.
  • You may also pass the STATIONNAME to override the station mapping that is stored in the recording database for the DEVICEID. This allows you to define your station mappings externally without having to store them in the local Uptivity system database.
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_idaniarchive_action_idaudio_hashaudio_size
Calldirectioncallidchanneldevice_aliasdevice_id
dnisdurationfilenamefilename_videogate
globalidIdentkeepdayslockedlistenedto
mediaLabeloverriddenpriorityqa_formsqa_group_id
qa_poss_scoreqa_scorerecording_timerecording_typescreen_capture
sgroupuser1user2user3user4
user5user6user7user8user9
user10user11user12user13user14
user15video_hashvideo_sizewrap_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, IMPORTWORKSTATION

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, COMBINEDEMAIL

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)

See Also