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 agentClosedThe 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).
ANIClosedAn 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 AdministrationSystem SettingsArchive 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 PBXClosedAn 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 APIClosedAn 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.
DNISClosedAn 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.
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 ACDClosedAcronym 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.
ID 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)

See Also