API Server Commands

Call Handling Functions

Call handling functions are used either to replace CTI integration or to supplement an existing CTI integration. These functions can be used to update the system with call information pertaining to the current statuses of the devices on your phone system.

The following messages follow the normal call flow path as messages from a CTI integration do. This means that the scheduler handles call recording decisions. Because of this, statistics can naturally also be gathered by the system.

In requests with multiple parameters, the order of the parameters in the XML does not matter as long as the values are contained in the appropriate corresponding sections.

Some parameters have specific requirements or limitations when being used. Keep the following notations in mind when choosing parameters:

* = At least one of these parameters is required for the request to be executed.

+ = Parameters can only be used if a device ID has already been associated with an agent.

** = Using angle brackets (< >), some special characters, and symbols may not work correctly. Test all possible characters needed before using this function.

CALLSTART
Description Allows a user to specify that a device has started a new phone call. This information is used to update live displays.

Required Parameters

  • REQUESTID (always required)
  • DEVICEID *
  • DEVICEALIAS * +
  • STATIONNAME *
  • SYS_USER * +
  • CRM_USER * +

STATIONNAME may be passed as the required item in place of DEVICEID. 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 database for the DEVICEID.

CALLINSTANCE is used to distinguish the calls on the same device at the same time. If a CALLINSTANCE is not provided on CALLSTART, it will default to a blank CALLINSTANCE.

Optional Parameters
  • CALLINSTANCE
  • GROUP
  • GATE
  • ANI
  • DNIS
  • USER1 – USER15
  • CALLID
  • PRIORITY
  • CALLDIRECTION
  • MAXRECORDSILENCE
  • MAXRECORDTIME
  • AGENTINITIATED
  • CTIINITIATED
  • ARCHIVEACTION (this requires an archive action created in Uptivity)
Possible Returns
  • API_ERROR_RECORDER_NOT_RUNNING — If the API could not send the command to any of the related CTI Cores
  • API _PARTIAL_CORE_RESPONSE — If the API was able to connect to some CTI Cores but not others the RESULTMSG will be "CALLSTART could not be sent to the following cores: #,#,#"
  • API_OK — If the API was able to connect to all CTI Cores the RESULTMSG will be "CALLSTART sent to all of the following cores: #,#,#"

When a CALLSTART is sent by DEVICEALIAS, SYS_USER, or CRM_USER, and a matching device is not found, this result is returned:

<RESULT>

<REQUESTTYPE>CALLSTART</REQUESTTYPE>

<REQUESTID>1</REQUESTID>

<RESULTTYPE>API_DEVICE_INVALID</RESULTTYPE>

<RESULTCODE>8</RESULTCODE>

<RESULTMSG>Could not find a device matching given prameters</RESULTMSG>

</RESULT>

Example(s):

<REQUEST>

<TYPE>CALLSTART</TYPE>

<REQUESTID>1</REQUESTID>

<DEVICEID>555</DEVICEID>

<DEVICEALIAS>3545</DEVICEALIAS>

<GROUP>12</GROUP>

<GATE>80</GATE>

<ANI>6145551212</ANI>

<DNIS>8889225526</DNIS>

<USER1>Gold Level</USER1>

<USER2>Customer 564582</USER2>

</REQUEST>

CALLSTOP
Description Allows a user to specify that a device has ended a call. This information is used to update System Status and Live Monitoring screens, as well as stop recording if the device is currently being recorded.
Required Parameters
  • REQUESTID (always required)

  • DEVICEID *

  • CALLINSTANCE

  • SYS_USER *+

  • CRM_USER *+

  • DEVICEALIAS *+

  • STATIONNAME *

DEVICEALIAS, CRM_USER, and SYS_USER may be passed as the required item in place of DEVICEID. If DEVICEID is not passed or is passed as a blank value, Uptivity will look up the DEVICEID based on the value provided. If the call instance is not provided, the call instance of the last call on this device is used.

CALLINSTANCE is used to distinguish which call the CALLSTOP is being issued to. If no CALLINSTANCE is provided on CALLSTOP, then the CALLINSTANCE of the last call on the device is used.

Optional Parameters
  • None
Possible Returns
  • API_ERROR_RECORDER_NOT_RUNNING — If the API could not send the command to any of the related CTI Cores
  • API _PARTIAL_CORE_RESPONSE — If the API was able to connect to some CTI Cores but not others the RESULTMSG will be "CALLSTOP could not be sent to the following cores: #,#,#"
  • API_OK — If the API was able to connect to all CTI Cores the RESULTMSG will be "CALLSTOP sent to all of the following cores: #,#,#"
Example(s):

<REQUEST>

<TYPE>CALLSTOP</TYPE>

<REQUESTID>2</REQUESTID>

<DEVICEID>555</DEVICEID>

</REQUEST>

CALLUPDATE
Description

Allows a user to update information on a device that is currently on a phone call. This information is used to update live displays and reporting. This information will not be used by the call recording schedule because it is assumed that the call is in progress at this point. Prior to this message, a CALLSTART message must be sent. If UPDATE_IF_NOT_RECORDING is set to Y and the device is not in a call, then it will update the last call that was recorded for the given device.

If DEVICEID is not present, it will be looked up by either CRM_USER or SYS_USER, whichever is present. If none are present, update will fail and return a RESULTTYPE of API_DEVICE_INVALID.

CALLINSTANCE is used to distinguish which call the CALLUPDATE is being issued to. If no CALLINSTANCE is provided on CALLUPDATE then the CALLINSTANCE of the last call on the device is used.

Required Parameters
  • REQUESTID (always required)
  • DEVICEID *
  • CRM_USER *+
  • SYS_USER *+
  • DEVICEALIAS *+
  • STATIONNAME *
  • USER1 – USER15 **
Optional Parameters
  • CALLINSTANCE
  • GROUP

  • GATE

  • ANI

  • DNIS

  • CALLDIRECTION

  • ARCHIVEACTION (this must an archive action created in Uptivity)

  • KEEPDAYS

  • UPDATE_IF_NOT_RECORDING

Possible Returns
  • API_ERROR_RECORDER_NOT_RUNNING — If the API could not send the command to any of the related CTI Cores
  • API _PARTIAL_CORE_RESPONSE — If the API was able to connect to some CTI Cores but not others the RESULTMSG will be "CALLSTART could not be sent to the following cores: #,#,#"
  • API_OK — If the API was able to connect to all CTI Cores the RESULTMSG will be "CALLSTART sent to all of the following cores: #,#,#"
  • API_RECORDID_INVALID — If Update_If_Not_Recording is set and there was not a previous call to update
  • API_DATABASE_QUERY_ERROR — If the API does not successfully update a recording in the recordings table
Example(s):

<REQUEST>

<TYPE>CALLUPDATE</TYPE>

<REQUESTID>1</REQUESTID>

<DEVICEID>555</DEVICEID>

<USER3>Follow up on order</USER3>

</REQUEST>

 

<RESULT>

<REQUESTTYPE>CALLUPDATE</REQUESTTYPE>

<REQUESTID>1</REQUESTID>

<RESULTTYPE>API_OK</RESULTTYPE>

<RESULTCODE>20</RESULTCODE>

<RESULTMSG>CALLUPDATE sent to all of the following cores: 1</RESULTMSG>

</RESULT>

 

<REQUEST>

<TYPE>CALLUPDATE</TYPE>

<REQUESTID>3</REQUESTID>

<DEVICEID>555</DEVICEID>

<USER3>Follow up on order</USER3>

<UPDATE_IF_NOT_RECORDING>Y</UPDATE_IF_NOT_RECORDING>

</REQUEST>

 

<RESULT>

<REQUESTTYPE>CALLUPDATE</REQUESTTYPE>

<REQUESTID>3</REQUESTID>

<RESULTTYPE>API_OK</RESULTTYPE>

<RESULTCODE>20</RESULTCODE>

<RESULTMSG>Updated recording in database</RESULTMSG>

</RESULT>

CALLUPDATE – Post-Recording
Description Allows a user to update information about a call that has finished recording. This information is used to update the recording database. This information will not be used by the scheduling or archive systems because it is assumed that the call is completed at this point. By passing a RecordID parameter, it is assumed the call update is for a call post-recording.
Required Parameters
  • REQUESTID
  • RECORDID
Optional Parameters
  • DEVICEID

  • DEVICEALIAS

  • GROUP

  • GATE

  • ANI

  • DNIS

  • USER1 – USER15 **

  • CALLDIRECTION

Possible Returns
  • API_OK — If successful
  • API_REQUESTID_INVALID — If the REQUESTID is invalid
  • API_DATABASE_QUERY_ERROR — If the API does not successfully update a recording in the recordings table
Example(s):

<REQUEST>

<TYPE>CALLUPDATE</TYPE>

<REQUESTID>1</REQUESTID>

<RECORDID>554853</RECORDID>

<USER4>Sales Call</USER4>

</REQUEST>

RECORDSTART
Description Allows a user to start an additional, partial recording for a call that is already being recorded.
Required Parameters
  • REQUESTID (always required)

  • DEVICEID *

  • DEVICEALIAS * +
  • STATIONNAME *

  • SYS_USER * +

  • CRM_USER * +

Optional Parameters
  • CALLINSTANCE

  • GROUP

  • GATE

  • ANI

  • DNIS

  • CALLID

  • PRIORITY

  • CALLDIRECTION

  • MAXRECORDSILENCE

  • MAXRECORDTIME

  • AGENTINITIATED

  • CTIINITIATED

  • ARCHIVEACTION (this must an archive action created in Uptivity)

  • USER1-USER15 **

Possible Returns
  • API_ERROR_RECORDER_NOT_RUNNING — If the API could not send the command to any of the related CTI Cores
  • API _PARTIAL_CORE_RESPONSE — If the API was able to connect to some CTI Cores but not others, the RESULTMSG will be "RECORDSTART could not be sent to the following cores: #,#,#"
  • API_OK — If the API was able to connect to all CTI Cores the RESULTMSG will be "RECORDSTART sent to all of the following cores: #,#,#"

When a callstart is sent by DEVICEALIAS, SYS_USER, or CRM_USER, and no matching device is found, this result is returned

<RESULT>

<REQUESTTYPE>RECORDSTART</REQUESTTYPE>

<REQUESTID>1</REQUESTID>

<RESULTTYPE>API_DEVICE_INVALID</RESULTTYPE>

<RESULTCODE>8</RESULTCODE>

<RESULTMSG>Could not find a device matching given parameters</RESULTMSG>

</RESULT>

Example(s):

<REQUEST>

<TYPE>RECORDSTART</TYPE>

<REQUESTID>1</REQUESTID>

<DEVICEID>555</DEVICEID>

<DEVICEALIAS>3545</DEVICEALIAS>

<GROUP>12</GROUP>

<GATE>80</GATE>

<ANI>6145551212</ANI>

<DNIS>8889225526</DNIS>

<USER1>Gold Level</USER1>

<USER2>Customer 564582</USER2>

</REQUEST>

 

<RESULT>

<REQUESTTYPE>RECORDSTART</REQUESTTYPE>

<REQUESTID>2060</REQUESTID>

<RESULTTYPE>API_OK</RESULTTYPE>

<RESULTCODE>20</RESULTCODE>

<RESULTMSG>RECORDSTART sent to all of the following cores: 1</RESULTMSG>

</RESULT>

RECORDSTOP
Description Used with RECORDSTART. Allows a user to specify that a phone call on a device has ended. This information is used to update System Status and Live Monitoring screens, as well as stop recording if the device is currently being recorded.
Required Parameters
  • REQUESTID (always required)

  • DEVICEID *

  • SYS_USER *+

  • CRM_USER *+

  • DEVICEALIAS *+

  • STATIONNAME *

Optional Parameters
  • CALLINSTANCE

  • USER1-USER15**

Possible Returns
  • API_ERROR_RECORDER_NOT_RUNNING — If the API could not send the command to any of the related CTI Cores
  • API _PARTIAL_CORE_RESPONSE — If the API was able to connect to some CTI Cores but not others the RESULTMSG will be "RECORDSTOP could not be sent to the following cores: #,#,#"
  • API_OK — If the API was able to connect to all CTI Cores the RESULTMSG will be "RECORDSTOP sent to all of the following cores: #,#,#"
Example(s):

<REQUEST>

<TYPE>CALLSTOP</TYPE>

<REQUESTID>2</REQUESTID>

<DEVICEID>555</DEVICEID>

<USER1>test</USER1>

<USER3>1</USER3>

</REQUEST>

 

<RESULT>

<REQUESTTYPE>RECORDSTOP</REQUESTTYPE>

<REQUESTID>2060</REQUESTID>

<RESULTTYPE>API_OK</RESULTTYPE>

<RESULTCODE>20</RESULTCODE>

<RESULTMSG>RECORDSTOP sent to all of the following cores: 1</RESULTMSG>

</RESULT>

Status Functions

Status functions allow you to receive current information from the system. This information can be used to track system, channel, or phone states and to write custom monitors for the system.

The following messages are informational only and do not affect recording.

DEVICELIST
Description Queries the system for a current list of phones/devices, and the current information associated with the devices. The current status of any device that Uptivity is aware of is kept in memory on the system. This function returns only one instance on a device. For all instances, use DEVICERECORDINGSTATUS.
Required Parameters
  • REQUESTID

  • DEVICELIST
Optional Parameters

None

Possible Returns

RESULT section plus a DEVICE section containing:

  • DEVICEID
  • DEVICEALIAS
  • SYS_USER
  • CRM_USER
  • GROUP
  • GATE
  • ANI
  • DNIS
  • USER1 – USER15
  • CALLID
  • CALLDIRECTION
  • STATIONNAME
  • ISTRUNK
  • STARTTIME
  • STOPTIME
  • COREIDENT
  • RECORDING section:
    • ISRECORDING
    • ISRECORDINGVIDEO
    • FILENAME
    • SESSIONID
    • CALLINSTANCE
Example(s):

<RESULT>

<REQUESTTYPE>DEVICELIST</REQUESTTYPE>

<REQUESTID>1</REQUESTID>

<RESULTTYPE>API_OK</RESULTTYPE>

<RESULTCODE>20</RESULTCODE>

<RESULTMSG>API_OK</RESULTMSG>

<DEVICES>

<COUNT>1</COUNT>

<DEVICE>

<DEVICEID>1111</DEVICEID>

<DEVICEALIAS>DESK1</DEVICEALIAS>

<SYS_USER>gkerber</SYS_USER>

<CRM_USER>CCGKERBER</CRM_USER>

<GROUP>MANAGER</GROUP>

<GATE>prize</GATE>

<ANI></ANI>

<DNIS></DNIS>

<USER1>E</USER1>

<USER2>winners</USER2>

<USER3></USER3>

<USER4></USER4>

<USER5></USER5>

<USER6></USER6>

<USER7></USER7>

<USER8></USER8>

<USER9></USER9>

<USER10></USER10>

<USER11></USER11>

<USER12></USER12>

<USER13></USER13>

<USER14></USER14>

<USER15></USER15>

<CALLDIRECTION>I</CALLDIRECTION>

<ISTRUNK></ISTRUNK>

<STATION></STATION>

<STARTTIME>2/1/2011 11:49:32 AM</STARTTIME>

<STOPTIME></STOPTIME>

<COREIDENT>2</COREIDENT>

<RECORDING>

<ISRECORDING>Y</ISRECORDING>

<ISRECORDINGVIDEO>Y</ISRECORDINGVIDEO>

<FILENAME>C:\Recordings\20110131\DESK1\DESK1-17-03-14.wav</FILENAME>

<CALLID></CALLID>

<SESSIONID></SESSIONID>

<CALLINSTANCE>2001</CALLINSTANCE>

</RECORDING>

</DEVICE>

</DEVICES>

</RESULT>

DEVICESTATUS
Description Queries the system for current information pertaining to a specific device or devices. The system prioritizes the call instances based on which one is active or was most recently active. If the device is not currently on a call, the last call it was on will be returned. This function returns ONLY the highest priority (most recently active) instance for a device. For all instances, use DEVICERECORDINGSTATUS.
Required Parameters
  • REQUESTID (always required)

In addition, you must include only one of the following:

  • DEVICEID

  • DEVICEALIAS

  • CRM_USER

  • SYS_USER

Optional Parameters
  • CALLID
Possible Returns

RESULT section plus a DEVICE section containing:

  • DEVICEID
  • DEVICEALIAS
  • SYS_USER
  • CRM_USER
  • GROUP
  • GATE
  • ANI
  • DNIS
  • USER1 – USER15
  • CALLDIRECTION
  • ISTRUNK
  • STATION
  • STARTTIME
  • STOPTIME
  • COREIDENT
  • RECORDING section:
    • ISRECORDING
    • ISRECORDINGVIDEO
    • FILENAME
    • CALLID
    • SESSIONID
    • CALLINSTANCE
Example(s):

<REQUEST>

<TYPE>DEVICESTATUS</TYPE>

<DEVICEALIAS>DESK1</DEVICEALIAS>

<REQUESTID>24</REQUESTID>

</REQUEST>

 

<RESULT>

<REQUESTTYPE>DEVICESTATUS</REQUESTTYPE>

<REQUESTID>24</REQUESTID>

<RESULTTYPE>API_OK</RESULTTYPE>

<RESULTCODE>20</RESULTCODE>

<RESULTMSG>Found the following matching devices</RESULTMSG>

<DEVICES>

<COUNT>1</COUNT>

<DEVICE>

<DEVICEID>1111</DEVICEID>

<DEVICEALIAS>DESK1</DEVICEALIAS>

<SYS_USER>gkerber</SYS_USER>

<CRM_USER>CCGKERBER</CRM_USER>

<GROUP>MANAGER</GROUP>

<GATE>prize</GATE>

<ANI></ANI>

<DNIS></DNIS>

<USER1>E</USER1>

<USER2>winners</USER2>

<USER3></USER3>

<USER4></USER4>

<USER5></USER5>

<USER6></USER6>

<USER7></USER7>

<USER8></USER8>

<USER9></USER9>

<USER10></USER10>

<USER11></USER11>

<USER12></USER12>

<USER13></USER13>

<USER14></USER14>

<USER15></USER15>

<CALLDIRECTION>I</CALLDIRECTION>

<ISTRUNK></ISTRUNK>

<STATION></STATION>

<STARTTIME>2/1/2011 11:49:32 AM</STARTTIME>

<STOPTIME></STOPTIME>

<COREIDENT>2</COREIDENT>

<RECORDING>

<ISRECORDING>Y</ISRECORDING>

<ISRECORDINGVIDEO>Y</ISRECORDINGVIDEO>

<FILENAME>C:\Recordings\20110131\DESK1\DESK1-17-03-14.wav</FILENAME>

<CALLID></CALLID>

<SESSIONID></SESSIONID>

<CALLINSTANCE>2001</CALLINSTANCE>

</RECORDING>

</DEVICE>

</DEVICES>

</RESULT>

DEVICERECORDINGSTATUS
Description Queries the system for a list of all instances of a device and displays status (that is, recording or recording pause).
Required Parameters
  • REQUESTID (always required)

In addition, you must include only one of the following:

  • DEVICEID

  • DEVICEALIAS

  • CRM_USER

  • SYS_USER

Optional Parameters

None

Possible Returns

RESULT section plus a DEVICE section containing:

  • DEVICEID
  • DEVICEALIAS
  • SYS_USER
  • CRM_USER
  • COREIDENT
  • RECORDING section:
    • GROUP
    • GATE
    • ANI
    • DNIS
    • USER1 – USER15
    • CALLDIRECTION
    • ISTRUNK
    • STATION
    • STARTTIME
    • STOPTIME
    • ISRECORDING
    • ISRECORDINGVIDEO
    • FILENAME
    • CALLID
    • SESSIONID
    • CALLINSTANCE
Example(s):

<REQUEST>

<TYPE>DEVICERECORDINGSTATUS</TYPE>

<DEVICEALIAS>DESK1</DEVICEALIAS>

<REQUESTID>24</REQUESTID>

</REQUEST>

 

<RESULT>

<REQUESTTYPE>DEVICERECORDINGSTATUS</REQUESTTYPE>

<REQUESTID>2</REQUESTID>

<RESULTTYPE>API_OK</RESULTTYPE>

<RESULTCODE>20</RESULTCODE>

<RESULTMSG>Following active call instances found for specified deviceID, devicealias, crm_user or sys_user</RESULTMSG>

<DEVICE>

<DEVICEID>7008</DEVICEID>

<DEVICEALIAS></DEVICEALIAS>

<SYS_USER>jane.doe</SYS_USER>

<CRM_USER></CRM_USER>

<COREIDENT>8</COREIDENT>

<RECORDING>

<GROUP></GROUP>

<GATE></GATE>

<ANI>7460</ANI>

<DNIS>7008</DNIS>

<USER1></USER1>

<USER2></USER2>

<USER3></USER3>

<USER4></USER4>

<USER5></USER5>

<USER6>30</USER6>

<USER7>1</USER7>

<USER8>00001000371342197048</USER8>

<USER9></USER9>

<USER10></USER10>

<USER11></USER11>

<USER12></USER12>

<USER13></USER13>

<USER14></USER14>

<USER15></USER15>

<CALLDIRECTION>I</CALLDIRECTION>

<ISTRUNK></ISTRUNK>

<STATION></STATION>

<STARTTIME>7/13/2012 12:30:43 PM</STARTTIME>

<STOPTIME></STOPTIME>

<ISRECORDING>Y</ISRECORDING>

<ISRECORDINGVIDEO>N</ISRECORDINGVIDEO>

<FILENAME>C:\Recordings\20120713\7008\7008-12-30-43.cca</FILENAME>

<CALLID></CALLID>

<SESSIONID></SESSIONID>

<CALLINSTANCE>37</CALLINSTANCE>

<STATUS>recordpaused</STATUS>

</RECORDING>

</DEVICE>

<RECORDING>

<GROUP></GROUP>

<GATE></GATE>

<ANI>7008</ANI>

<DNIS>7007</DNIS>

<USER1></USER1>

<USER2></USER2>

<USER3></USER3>

<USER4></USER4>

<USER5></USER5>

<USER6></USER6>

<USER7></USER7>

<USER8>00001000381342197107</USER8>

<USER9></USER9>

<USER10></USER10>

<USER11></USER11>

<USER12></USER12>

<USER13></USER13>

<USER14></USER14>

<USER15></USER15>

<CALLDIRECTION>O</CALLDIRECTION>

<ISTRUNK></ISTRUNK>

<STATION></STATION>

<STARTTIME>7/13/2012 12:31:54 PM</STARTTIME>

<STOPTIME></STOPTIME>

<ISRECORDING>Y</ISRECORDING>

<ISRECORDINGVIDEO>N</ISRECORDINGVIDEO>

<FILENAME>C:\Recordings\20120713\7008\7008-12-31-54.cca</FILENAME>

<CALLID></CALLID>

<SESSIONID></SESSIONID>

<CALLINSTANCE>38</CALLINSTANCE>

<STATUS>recording</STATUS>

</RECORDING>

</DEVICE>

</RESULT>

SYSTEMSTATUS
Description Queries the system for a system status. Information returned contains data pertaining to the health of the system, disk space, and so forth.
Required Parameters
  • REQUESTID
Optional Parameters

None

Possible Returns

RESULT section plus additional information tags:

  • RECORDINGPATH
  • RECORDINGSPACEINFO
  • RECORDINGTOTALDISKCAPACITY
  • RECORDINGTOTALDISKFREE
  • RECORDINGTOTALDISKFREEPCT
  • SYSTEMUPTIME
  • PROCESSOR#
    • SYSTEMPROCESSORSPEED
    • SYSTEMPROCESSORTYPE
  • SYSTEMRAMTOTAL
  • SYSTEMRAMFREE
  • SYSTEMRAMUSED
  • SYSTEMRAMUSEDPCT
Example(s):

<REQUEST>

<TYPE>SYSTEMSTATUS</TYPE>

<REQUESTID>255</REQUESTID>

</REQUEST>

 

<RESULT>

<REQUESTTYPE>SYSTEMSTATUS</REQUESTTYPE>

<REQUESTID>255</REQUESTID>

<RESULTTYPE>API_OK</RESULTTYPE>

<RESULTCODE>20</RESULTCODE>

<RESULTMSG>API_OK</RESULTMSG>

<RECORDINGPATH>C:\Recordings\</RECORDINGPATH>

<RECORDINGSPACEINFO>223.66GB of 465.64GB</RECORDINGSPACEINFO>

<RECORDINGTOTALDISKCAPACITY>476819</RECORDINGTOTALDISKCAPACITY>

<RECORDINGTOTALDISKFREE>229032</RECORDINGTOTALDISKFREE>

<RECORDINGTOTALDISKFREEPCT>48.03</RECORDINGTOTALDISKFREEPCT>

<SYSTEMUPTIME>0 days, 18 hours, 24 minutes, 37 seconds.</SYSTEMUPTIME>

<PROCESSOR0>

<SYSTEMPROCESSORSPEED>2394MHz</SYSTEMPROCESSORSPEED>

<SYSTEMPROCESSORTYPE>x86 Family 6 Model 15 Stepping 11</SYSTEMPROCESSORTYPE>

</PROCESSOR0>

<PROCESSOR1>

<SYSTEMPROCESSORSPEED>2394MHz</SYSTEMPROCESSORSPEED>

<SYSTEMPROCESSORTYPE>x86 Family 6 Model 15 Stepping 11</SYSTEMPROCESSORTYPE>

</PROCESSOR1>

<PROCESSOR2>

<SYSTEMPROCESSORSPEED>2394MHz</SYSTEMPROCESSORSPEED>

<SYSTEMPROCESSORTYPE>x86 Family 6 Model 15 Stepping 11</SYSTEMPROCESSORTYPE>

</PROCESSOR2>

<PROCESSOR3>

<SYSTEMPROCESSORSPEED>2394MHz</SYSTEMPROCESSORSPEED>

<SYSTEMPROCESSORTYPE>x86 Family 6 Model 15 Stepping 11</SYSTEMPROCESSORTYPE>

</PROCESSOR3>

<SYSTEMRAMTOTAL>3325</SYSTEMRAMTOTAL>

<SYSTEMRAMFREE>1702</SYSTEMRAMFREE>

<SYSTEMRAMUSED>1623</SYSTEMRAMUSED>

<SYSTEMRAMUSEDPCT>48</SYSTEMRAMUSEDPCT>

</RESULT>

CHANNELS
Description Queries the system for status of recorded channels.
Required Parameters
  • REQUESTID
Optional Parameters

None

Possible Returns
  • API_DATABASE_QUERY_ERROR — If the API does not successfully connect to the database

A successful call returns a RESULT section with a COUNT of the number of channels, plus a CHANNEL section for each channel on the system containing:

  • ID — This is the Channel ID from the recording database. The number of ID sections is the same as the COUNT.
  • STATE
  • LASTSTATECHANGE
  • LASTSTATECHANGEUNIXTIME

Example(s):

<REQUEST>

<TYPE>CHANNELS</TYPE>

<REQUESTID>255</REQUESTID>

</REQUEST>

 

<RESULT>

<REQUESTTYPE>CHANNELS</REQUESTTYPE>

<REQUESTID>26</REQUESTID>

<RESULTTYPE>API_OK</RESULTTYPE>

<RESULTCODE>20</RESULTCODE>

<RESULTMSG>API_OK</RESULTMSG>

<COUNT>4</COUNT>

<CHANNELS>

<CHANNEL>

<ID>1</ID>

<STATE>PreparingToRecord</STATE>

<PLAYBACKEXTENSION></PLAYBACKEXTENSION>

<RECORDINGDEVICEALIAS></RECORDINGDEVICEALIAS>

<RECORDINGDEVICE>7002</RECORDINGDEVICE>

<LASTSTATECHANGE>1/31/2011 5:50:33 PM</LASTSTATECHANGE>

<LASTSTATECHANGEUNIXTIME>1296496234</LASTSTATECHANGEUNIXTIME>

</CHANNEL>

<CHANNEL>

<ID>2</ID>

<STATE>Idle</STATE>

<PLAYBACKEXTENSION></PLAYBACKEXTENSION>

<RECORDINGDEVICEALIAS></RECORDINGDEVICEALIAS>

<RECORDINGDEVICE>7003</RECORDINGDEVICE>

<LASTSTATECHANGE>1/31/2011 6:15:52 PM</LASTSTATECHANGE>

<LASTSTATECHANGEUNIXTIME>1296497752</LASTSTATECHANGEUNIXTIME>

</CHANNEL>

<CHANNEL>

<ID>3</ID>

<STATE>Idle</STATE>

<PLAYBACKEXTENSION></PLAYBACKEXTENSION>

<RECORDINGDEVICEALIAS></RECORDINGDEVICEALIAS>

<RECORDINGDEVICE>7055</RECORDINGDEVICE>

<LASTSTATECHANGE>1/31/2011 6:11:40 PM</LASTSTATECHANGE>

<LASTSTATECHANGEUNIXTIME>1296497501</LASTSTATECHANGEUNIXTIME>

</CHANNEL>

<CHANNEL>

<ID>4</ID>

<STATE>Idle</STATE>

<PLAYBACKEXTENSION></PLAYBACKEXTENSION>

<RECORDINGDEVICEALIAS></RECORDINGDEVICEALIAS>

<RECORDINGDEVICE>7444</RECORDINGDEVICE>

<LASTSTATECHANGE>1/31/2011 6:11:40 PM</LASTSTATECHANGE>

<LASTSTATECHANGEUNIXTIME>1296497501</LASTSTATECHANGEUNIXTIME>

</CHANNEL>

</CHANNELS>

</RESULT>

STATIONS
Description Queries the system for a list of programmed stations.
Required Parameters
  • REQUESTID
Optional Parameters

None

Possible Returns
  • API_DATABASE_QUERY_ERROR — If the API does not successfully connect to the database

A successful API call returns a RESULT section including a COUNT of number of stations, plus a STATIONS section for each station on the system containing:

  • STATIONNAME
  • DEVICEID
Example(s):

<REQUEST>

<TYPE>STATIONS</TYPE>

<REQUESTID>29</REQUESTID>

</REQUEST>

 

<RESULT>

<REQUESTTYPE>STATIONS</REQUESTTYPE>

<REQUESTID>29</REQUESTID>

<RESULTTYPE>API_OK</RESULTTYPE>

<RESULTCODE>20</RESULTCODE>

<RESULTMSG>API_OK</RESULTMSG>

<COUNT>2</COUNT>

<STATIONS>

<STATION>

<STATIONNAME>JamesBond</STATIONNAME>

<DEVICEID>7007</DEVICEID>

</STATION>

</STATIONS>

</RESULT>

FETCHTERMINOLOGY
Description Uptivity can be customized with terminology used in your operating environment (for example, you may refer to an "agent" as a "CSR"). This command queries the system for a list of terminology settings.
Required Parameters
  • REQUESTID
Optional Parameters

None

Possible Returns

A RESULT section including a COUNT of the number of TERMINOLOGY sections, plus TERMINOLOGY sections for each terminology variable specified in the system with:

  • NAME
  • VALUE
Example(s):

<REQUEST>

<TYPE>FETCHTERMINOLOGY</TYPE>

<REQUESTID>34</REQUESTID>

</REQUEST>

 

<RESULT>

<REQUESTTYPE>FETCHTERMINOLOGY</REQUESTTYPE>

<REQUESTID>34</REQUESTID>

<COUNT>10</COUNT>

<SETTINGS>

<TERMINOLOGY>

<NAME>agent</NAME>

<VALUE>Agent</VALUE>

</TERMINOLOGY>

<TERMINOLOGY>

<NAME>ani</NAME>

<VALUE>CallerID ANI</VALUE>

</TERMINOLOGY>

<TERMINOLOGY>

<NAME>callcopygroup</NAME>

<VALUE>CallCopy group</VALUE>

</TERMINOLOGY>

<TERMINOLOGY>

<NAME>devicealias</NAME>

<VALUE>Agent Number</VALUE>

</TERMINOLOGY>

<TERMINOLOGY>

<NAME>deviceid</NAME>

<VALUE>Voice Port</VALUE>

</TERMINOLOGY>

<TERMINOLOGY>

<NAME>dnis</NAME>

<VALUE>Number Called DNIS</VALUE>

</TERMINOLOGY>

<TERMINOLOGY>

<NAME>gate</NAME>

<VALUE>ACD Gate</VALUE>

</TERMINOLOGY>

<TERMINOLOGY>

<NAME>group</NAME>

<VALUE>Group</VALUE>

<TERMINOLOGY>

<NAME>user1</NAME>

<VALUE>Account Number</VALUE>

</TERMINOLOGY>

<TERMINOLOGY>

<NAME>user2</NAME>

<VALUE>CSN</VALUE>

</TERMINOLOGY>

</SETTINGS>

</RESULT>

CALLLIST
Description

Queries the system for a list of call recordings matching criteria.

Filters are combined as a Boolean AND operation.

Depending on which parameters are passed, the number of different parameters passed, and the number of results that match passed parameters, database performance may be impacted. Uptivity's recording capability is designed to function normally during database outages, but proper consideration must be taken when designing call list queries to prevent excessive use of database resources.

If both CALLCOUNT and CALLDATESTART/END are queried at the same time, the expected behavior is that CALLCOUNT will limit the query to showing the top N calls within the selected date range.

Required Parameters
  • REQUESTID
Optional Parameters
  • DEVICEID
  • CRM_USER
  • SYS_USER
  • DEVICEALIAS
  • GROUP
  • GATE
  • ANI
  • DNIS
  • USER1 - USER15 **
  • CALLCOUNT (number of calls that will be returned)
  • CALLDATESTART (beginning date for filter, in UNIX time)
  • CALLDATEEND (end date for filter, in UNIX time)
  • PLAYBACKLINK (requires enabling feature; for more information, see API Server Settings)

    With the PLAYBACKLINK parameter, XML encoding converts the & character to &amp; in Silverlight player links. Before using the playback link, the &amp; needs converted back to & to work properly. HTML5 playback links are not affected by this behavior.

Possible Returns

RESULT section including all information for all recording records matching the query criteria, listed in descending order by date/time recorded.

Example(s):

<REQUEST>

<TYPE>CALLLIST</TYPE>

<REQUESTID>1</REQUESTID>

<DEVICEID>1111</DEVICEID>

<USER3>12345</USER3>

<CALLCOUNT>5</CALLCOUNT>

<CALLDATESTART>1312156800</CALLDATESTART>

<CALLDATEEND>1312934400</CALLDATEEND>

</REQUEST>

 

<RESULT>

<TYPE>CALLLIST</TYPE>

<REQUESTID>1</REQUESTID>

<SEARCHRESULT>

<CALLNUMBER>1</CALLNUMBER>

<DEVICEID>1111</DEVICEID>

<DEVICEALIAS>1234</DEVICEALIAS>

<ANI></ANI>

<DNIS></DNIS>

<CALLDIRECTION>I</CALLDIRECTION>

<GROUP></GROUP>

<GATE></GATE>

<USER1></USER1>

<USER2></USER2>

<USER3>12345</USER3>

<USER4></USER4>

<USER5></USER5>

<USER6></USER6>

<USER7></USER7>

<USER8></USER8>

<USER9></USER9>

<USER10></USER10>

<USER11></USER11>

<USER12></USER12>

<USER13></USER13>

<USER14></USER14>

<USER15></USER15>

<RECORDID>13101</RECORDID>

<RECORDINGTIME>1312921123</RECORDINGTIME>

<DURATION>60</DURATION>

<AGENTFIRSTNAME>John</AGENTFIRSTNAME>

<AGENTLASTNAME>Smith</AGENTLASTNAME>

<CRM_USER></CRM_USER>

<SYS_USER></SYS_USER>

<PLAYBACKLINK>HTTP://10.10.10.10:80/MediaPlayer/ExternalCallListPlayer/13101/false</PLAYBACKLINK>

</SEARCHRESULT>

<SEARCHRESULT>

<CALLNUMBER>2</CALLNUMBER>

<DEVICEID>1111</DEVICEID>

<DEVICEALIAS>1234</DEVICEALIAS>

...

</SEARCHRESULT>

<SEARCHRESULT>

<CALLNUMBER>3</CALLNUMBER>

<DEVICEID>1111</DEVICEID>

<DEVICEALIAS>1234</DEVICEALIAS>

...

</SEARCHRESULT>

<SEARCHRESULT>

<CALLNUMBER>4</CALLNUMBER>

<DEVICEID>1111</DEVICEID>

<DEVICEALIAS>1234</DEVICEALIAS>

...

</SEARCHRESULT>

<SEARCHRESULT>

<CALLNUMBER>5</CALLNUMBER>

<DEVICEID>1111</DEVICEID>

<DEVICEALIAS>1234</DEVICEALIAS>

...

</SEARCHRESULT>

</RESULT>

Recording Control Functions

Recording control functions allow you to write software that controls when the system should record. The system allows you to start and stop recording at will.

Using these functions, you can create custom triggers in your software to start and stop recording. Potential applications include allowing agents to record harassing callers or recording the part of a call containing credit card verification.

These functions will not cause problems if the device is already being recorded, or is not being recorded. In other words, you do not need to first check the status of a device before sending this message.

CHATSTART
Description Used to initiate a desktop-screen-capture-only recording session. The recorder assumes there is no audio with this call. This is commonly used with web-based chat applications. Separate instances of screen capture on the same system (for example, for separate chat windows/sessions) can be started and stopped by matching the SESSIONID with the CHATSTART and CHATSTOP commands in the requests sent. Performing more than three concurrent screen captures on a single system may result in reduced system performance.
Required Parameters
  • REQUESTID

  • SESSIONID

Optional Parameters
  • AGENTID

If AGENTID is not provided, Uptivity can look up the agent using KEYNAME and KEYVALUE

  • KEYNAME — USERNAME, SYS_USER, EMPLOYEEID, CRM_USER, DEVICEALIAS (Phone ID)

  • KEYVALUE — The username or employee ID as dictated in KEYNAME

Although AGENTID is the parameter in this function, the field used to identify the agent is USERID

Possible Returns
  • API_SESSIONID_UNSPECIFIED — If the API does not successfully connect to the database
  • API_AGENT_NOT_FOUND — Returned if Uptivity cannot locate an agent based on the information provided; detail description will be in the RESULTMSG
  • API_ERROR_RECORDER_NOT_RUNNING — If the API could not send the command to any of the related Cores
  • API_OK — If the API was able to connect to a Core
Example(s):

<REQUEST>

<REQUESTID>37</REQUESTID>

<TYPE>CHATSTART</TYPE>

<SESSIONID>82738</SESSIONID>

<KEYNAME>USERNAME</KEYNAME>

<KEYVALUE>JDOE</KEYVALUE>

</REQUEST>

 

<RESULT>

<REQUESTTYPE>CHATSTART</REQUESTTYPE>

<REQUESTID>37</REQUESTID>

<RESULTTYPE>API_OK</RESULTTYPE>

<RESULTCODE>20</RESULTCODE>

<RESULTMSG>CHATSTART sent to all of the following cores: 1</RESULTMSG>

</RESULT>

CHATSTOP
Description Used to stop a desktop-screen-recording-only recording session. This information is used to update live displays, as well as to stop recording if the device is currently being recorded.
Required Parameters
  • REQUESTID

  • SESSIONID

Optional Parameters

None

Possible Returns
  • API_SESSIONID_UNSPECIFIED — If the API does not successfully connect to the database
  • API_ERROR_RECORDER_NOT_RUNNING — If the API could not send the command to any of the related Cores
  • API_OK — If the API was able to connect to the Core
Example(s):

<REQUEST>

<REQUESTID>52</REQUESTID>

<TYPE>CHATSTOP</TYPE>

<SESSIONID>82738</SESSIONID>

</REQUEST>

 

<RESULT>

<REQUESTTYPE>CHATSTOP</REQUESTTYPE>

<REQUESTID>46</REQUESTID>

<RESULTTYPE>API_OK</RESULTTYPE>

<RESULTCODE>20</RESULTCODE>

<RESULTMSG>CHATSTOP sent to all of the following cores: 1</RESULTMSG>

</RESULT>

CHATUPDATE
Description Used to update a desktop-screen-recording-only recording session. This information is used to update live displays and reporting, but will not be used by the scheduling system because it is assumed that the recording is in progress at this point. Prior to this message, a CHATSTART message must be sent.
Required Parameters
  • REQUESTID

  • SESSIONID

Optional Parameters
  • DEVICEALIAS

  • GROUP

  • GATE

  • ANI

  • DNIS

  • USER1-USER15 **

  • CALLDIRECTION

  • CALLID

Possible Returns
  • API_SESSIONID_UNSPECIFIED — If the API does not successfully connect to the database
  • API_ERROR_RECORDER_NOT_RUNNING — If the API could not send the command to any of the related Cores
  • API_OK — If the API was able to connect to Core
Example(s):

<REQUEST>

<REQUESTID>64</REQUESTID>

<TYPE>CHATUPDATE</TYPE>

<SESSIONID>82738</SESSIONID>

<GROUP>53</GROUP>

</REQUEST>

 

<RESULT>

<REQUESTTYPE>CHATUPDATE</REQUESTTYPE>

<REQUESTID>64</REQUESTID>

<RESULTTYPE>API_OK</RESULTTYPE>

<RESULTCODE>20</RESULTCODE>

<RESULTMSG>CHATUPDATE sent to all of the following cores: 1</RESULTMSG>

</RESULT>

BLACKOUTSTART/AGENTBLACKOUTSTART
Description

Used to start a blackout period for a recording. Only specify one of the following: DEVICEID, DEVICEALIAS, CRM_USER, or SYS_USER. The blackout begins based on when the message is received plus any TIMEOFFSET.

While BLACKOUT is based on call instance, AGENTBLACKOUT will blackout all call and screen data for a specific time range for the specified agent. AGENTBLACKOUT is preferred over BLACKOUT, and AGENTBLACKOUT is enabled by default. Either standard or real-time blackouts will occur, depending on your system configuration. For more information, see the Blackouts Overview topic, or contact your system administrator or Uptivity Support.

Required Parameters
  • REQUESTID

  • In addition, you must include only one of the following:

  • DEVICEID
  • DEVICEALIAS
  • CRM_USER
  • SYS_USER
Optional Parameters
  • TIMEOFFSET
  • CALLINSTANCE (this parameter is only used for BLACKOUT, not AGENTBLACKOUT)
Possible Returns
  • API_AGENT_NOT_FOUND — Request needs to find information for either the device or the agent, if neither is found, this error appears
  • API_DEVICE_INVALID — Could not find a valid device from the given parameters
  • API_ERROR_RECORDER_NOT_RUNNING — If the API could not send the command to any of the related Cores
  • API_OK — If the API was able to connect to some Cores but not others, the RESULTMSG will be "BLACKOUTSTART could not be sent to the following cores: #,#,#"
  • API_REQUESTID_INVALID — REQUESTID specified is not valid
Example(s):

<REQUEST>

<REQUESTID>124</REQUESTID>

<TYPE>BLACKOUTSTART</TYPE>

<SYS_USER>JSMITH</SYS_USER>

<TIMEOFFSET>-5</TIMEOFFSET>

</REQUEST>

 

<RESULT>

<REQUESTTYPE>BLACKOUTSTART</REQUESTTYPE>

<REQUESTID>124</REQUESTID>

<RESULTTYPE>API_OK</RESULTTYPE>

<RESULTCODE>20</RESULTCODE>

<RESULTMSG>BLACKOUTSTART sent to all of the following cores: 1</RESULTMSG>

</RESULT>

BLACKOUTSTOP/AGENTBLACKOUTSTOP
Description

Used to stop a blackout period for a recording. Only specify one of the following: DEVICEID, DEVICEALIAS, CRM_USER, or SYS_USER. The blackout stops based on when the message is received plus any TIMEOFFSET.

While BLACKOUT is based on call instance, AGENTBLACKOUT will blackout all call and screen data for a specific time range for the specified agent. AGENTBLACKOUT is preferred over BLACKOUT, and AGENTBLACKOUT is enabled by default. Either standard or real-time blackouts will occur, depending on your system configuration. For more information, see the Blackouts Overview topic, or contact your system administrator or Uptivity Support.

When the time offset value causes a BLACKOUTSTOP to be issued before the BLACKOUTSTART, the start and stop times are the same. For example, if a BLACKOUTSTOP is sent with a time offset of -60 and the blackout started only 30 seconds ago, the BLACKOUTSTOP time will be the same as the BLACKOUTSTART time.

CALLINSTANCE is used to distinguish which call the blackouts are issued to. If no CALLINSTANCE is provided on BLACKOUTSTART or BLACKOUTSTOP, then the CALLINSTANCE of the last call on the device is used.

Required Parameters
  • REQUESTID (required)

  • In addition, you must include only one of the following:

  • DEVICEID

  • DEVICEALIAS

  • CRM_USER

  • SYS_USER

Optional Parameters
  • TIMEOFFSET

  • CALLINSTANCE (this parameter is only used for BLACKOUT, not AGENTBLACKOUT)

Possible Returns
  • API_AGENT_NOT_FOUND — Request needs to find information for either the device or the agent; if neither is found, this error appears
  • API_DEVICE_INVALID — Could not find a valid device from the given parameters
  • API_ERROR_RECORDER_NOT_RUNNING — If the API could not send the command to any of the related Cores
  • API_OK — If the API was able to connect to some Cores but not others the RESULTMSG will be "BLACKOUTSTART could not be sent to the following cores: #,#,#"
  • API_REQUESTID_INVALID — Request id specified is not valid
Example(s):

<REQUEST>

<REQUESTID>125</REQUESTID>

<TYPE>BLACKOUTSTOP</TYPE>

<SYS_USER>JSMITH</SYS_USER>

</REQUEST>

Import Functions

Import functions allow you to write integration links between your systems and the NICE Uptivity system. Potential applications include writing your own front-end interface to edit certain information contained within Uptivity, or writing automated scripts that update information in the server.

IMPORTUSER
Description

This function allows you to import users and add, modify, and delete information pertaining to a user. Once a user is added, you may use IMPORTAGENTPHONE to associate phone IDs to the user. This command requires a password to import user account information. USERNAME is the Uptivity username, while CRM_USER is the corresponding username associated with the user in an integrated system.

The field USERID is ignored when the action is ADD.

Deleting a user will simply change the status flag of the user to deleted and free all phone ID associations (if any) with that user. The actual record will not be removed. This ensures that past records will still identify the correct user in case a phone ID is reused for a new user.

MODIFY should only be used to add additional information to the user, or to change the name of the user as long as it is still the same employee.

An error will be returned if the USERID does not exist, or if you try to add a new user with the same first and last name as an existing user. Even though an error is returned when you try to add a user with the same first and last name as an existing user, values are not changed. Thus, you can write an automated script that continuously calls ADD and ignore errors.

LIST can be used to get a list of all users currently in Uptivity. No additional parameters are needed. The following fields are returned: USERID, USERNAME, EMPLOYEE_ID, FIRST_NAME, LAST_NAME, AGENT, STATUS, ADD_TIME, MOD_TIME, SYS_USER, SYS_DOMAIN, EMAIL, CRM_USER, SITE_ID, and PHONES.

The value for AGENT can be true (if the Agent checkbox is selected in the user's profile) or false (if the Agent checkbox is cleared).

The value for STATUS can be A (if the user is active in the system) or I (if the user is inactive in the system).

Required Parameters
  • REQUESTID

  • ACTION (Add, Delete, Modify, List)

  • USERID

  • EMPLOYEEID

  • FIRSTNAME

  • LASTNAME

  • STATUS (This parameter determines whether the USER is flagged as an AGENT in Uptivity. Possible values are A – Active (flagged as an AGENT) or I – Inactive (not flagged as an AGENT).

  • ADD_TIME (Date/time offset)

  • MOD_TIME (Date/time offset)

  • SYS_USER

  • DOMAIN

  • EMAIL

  • CRM_USER

  • PASSWORD

  • SITEID

  • USERNAME

Optional Parameters

None

Possible Returns
  • Standard Result
  • USERID

Possible error returns are:

  • API_DATABASE_QUERY_ERROR — Represents a range of possible query problems; check the API logs for details
  • API_ERROR_INVALID_ACTION — Allowed actions are ADD, MODIFY, DELETE, LIST; if the requested action is not one of these, this error is returned
  • API_INVALID_MESSAGE_FORMAT — This message appears if parameters are missing or the request is not formatted correctly
  • API_USER_ALREADY_EXIST — Indicates that a user with the same username already exists
  • API_USER_NOT_FOUND — When modifying or deleting an agent, this may appear if the agent is not found; if it appears as the result of a query error, check the API logs for details
Example(s):

<REQUEST>

<TYPE>IMPORTUSER</TYPE>

<REQUESTID>5</REQUESTID>

<ACTION>ADD</ACTION>

<USER_ID>2</USER_ID>

<USERNAME>Sally Smith</USERNAME>

<EMPLOYEE_ID>5</EMPLOYEE_ID>

<FIRST_NAME>Sally</FIRST_NAME>

<LAST_NAME>Smith</LAST_NAME>

<STATUS>A</STATUS>

<ADD_TIME></ADD_TIME>

<MOD_TIME></MOD_TIME>

<SYS_USER>smith.1</SYS_USER>

<DOMAIN>Uptivity</DOMAIN>

<EMAIL>ssmith@uptivity.com</EMAIL>

<CRM_USER>sallys</CRM_USER>

<SITEID>1</SITEID>

<PHONES>1123,3343,3234</PHONES>

</REQUEST>

List Example

<REQUEST>

<TYPE>IMPORTUSER</TYPE>

<REQUESTID>5</REQUESTID>

<ACTION>LIST</ACTION>

</REQUEST>

 

<RESULT>

<REQUESTTYPE>IMPORTUSER</REQUESTTYPE>

<REQUESTID>5</REQUESTID>

<RESULTTYPE>API_OK</RESULTTYPE>

<RESULTCODE>20</RESULTCODE>

<RESULTMSG>API_OK</RESULTMSG>

<USERS>

<COUNT>1</COUNT>

<USER>

<USER_ID>2</USER_ID>

<USERNAME>Sally Smith</USERNAME>

<EMPLOYEEID>5</EMPLOYEEID>

<FIRSTNAME>Sally</FIRSTNAME>

<LASTNAME>Smith</LASTNAME>

<AGENT>TRUE</AGENT>

<STATUS>A</STATUS>

<ADD_TIME>10/30/2006 4:05:38 PM -05:00</ADD_TIME>

<MOD_TIME>3/27/2008 3:34:43 PM -05:00</MOD_TIME>

<SYS_USER>smith.1</SYS_USER>

<SYS_DOMAIN>Uptivity</SYS_DOMAIN>

<EMAIL>ssmith@uptivity.com</EMAIL>

<CRM_USER>sally</CRM_USER>

<SITE_ID>1</SITE_ID>

<PHONES>1123,3343,3234</PHONES>

</USER>

</USERS>

</RESULT>

IMPORTAGENTPHONE
Description

Allows you to control the association of a phone device to an agent.

You must pass either the AGENTID or the FIRSTNAME and LASTNAME of the agent. The system will first try to use the AGENTID. Passing all three parameters will not cause a problem; however, in this case FIRSTNAME and LASTNAME will be ignored.

Deleting a PHONEID has no effect on the agent record itself.

Deleting a PHONEID does not remove the call records for that PHONEID.

An error will be returned if the AGENTID does not exist, or if you try to add a new phone ID that is already assigned to another agent.

Although AGENTID is the parameter in this function, the field used to identify the agent is USERID.

Required Parameters
  • REQUESTID

  • ACTION (Add, Delete)

  • PHONEID

  • AGENTID

  • FIRSTNAME

  • LASTNAME

Optional Parameters

None

Possible Returns

• Standard Result

• AGENTID

Possible error returns are:

API_AGENT_NOT_FOUND — Request needs to find information for either the device or the agent; if neither is found, this error appears

Example(s):

<REQUEST>

<TYPE>IMPORTAGENTPHONE</TYPE>

<REQUESTID>2</REQUESTID>

<ACTION>ADD</ACTION>

<PHONEID>1234</PHONEID>

<AGENTID>0</AGENTID>

<FIRSTNAME>John</FIRSTNAME>

<LASTNAME>Doe</LASTNAME>

</REQUEST>

IMPORTWORKSTATION
Description

Allows you to add or delete/add station-to-device mappings.

Before the new information is added, a delete will be done for entries containing either the DEVICEID or STATIONNAME to guarantee that the new entry is unique.

The result will contain the STATIONNAME that was sent from the request; however the DEVICEID that is returned is the value that is actually stored in the database. If an error occurs adding the new entry, the result DEVICEID may be an old value. This design allows for easier troubleshooting.

Required Parameters
  • REQUESTID

  • DEVICEID

  • STATIONNAME

  • LOCATIONID — The unique Location ID from the database; for more information, see Locations List.

Optional Parameters

None

Possible Returns
  • Standard Result
  • DEVICEID
  • STATIONNAME

Possible error returns are:

  • API_DATABASE_QUERY_ERROR — Represents a range of possible query problems; check the API logs for details
  • API_INVALID_MESSAGE_FORMAT — This message appears if parameters are missing or the request is not formatted correctly
Example(s):

<REQUEST>

<TYPE>IMPORTWORKSTATION</TYPE>

<REQUESTID>2</REQUESTID>

<DEVICEID>1234</DEVICEID>

<STATIONNAME>COMPUTER1</STATIONNAME>

<LOCATIONID>1</LOCATIONID>

</REQUEST>

Export Functions

EXPORT
Description

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.

Required Parameters

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

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

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

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.
COMBINEDEXPORT
Description 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.
Required Parameters COMBINEDEXPORT uses these values:
  • IDENT — These are comma-separated call record IDs.
  • MEDIA_FORMAT — File format of the exported audio file.
Optional Parameters None
Possible Returns 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.
Example(s)

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.
MULTIEXPORT
Description MULTIEXPORT is unique to the WebAPI. This function type combines multiple audio files into a ZIP file (post-recording) and exports that file.
Required Parameters MULTIEXPORT only uses these values:
  • IDENT — These are comma-separated call record IDs.
  • MEDIA_FORMAT — File format of the exported audio file.
Optional Parameters None
Possible Returns

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.
Example(s)

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.

User, Group, and Role Functions

ADDGROUP
Description

Allows you to add a QA Group. Uptivity will attempt to add the new group. The new group's GROUPNAME and the GROUPID are returned as the result. If a group with the same name already exists, the function will still return as normal without modifying any data.

Required Parameters
  • REQUESTID

  • GROUPNAME

Optional Parameters

None

Possible Returns
  • Standard Result
  • GROUPID
  • GROUPNAME

Possible error returns are:

  • API_INVALID_MESSAGE_FORMAT — This message appears if parameters are missing or the request is not formatted correctly
Example(s):

<REQUEST>

<TYPE>ADDGROUP</TYPE>

<REQUESTID>2</REQUESTID>

<GROUPNAME>Sales & Marketing</GROUPNAME>

</REQUEST>

 

<RESULT>

<REQUESTTYPE>ADDGROUP</REQUESTTYPE>

<REQUESTID>2</REQUESTID>

<RESULTTYPE>API_OK</RESULTTYPE>

<RESULTCODE>20</RESULTCODE>

<RESULTMSG>group: Sales & Marketing has been added</RESULTMSG>

<GROUPID>11</GROUPID>

<GROUPNAME>Sales & Marketing</GROUPNAME>

</RESULT>

MODIFYGROUPPERMISSION
Description

Allows you to add or remove agents and their device assignments to/from QA Groups.

You must supply either ADD or DELETE as the ACTION type.

You must supply either GROUPNAME or GROUPID, but you do not have to supply both.

You must supply either FIRSTNAME and LASTNAME, or AGENTID, but you do not have to supply both.

The system will first look to see if you supplied the textual representation of the group name or the agent name and lookup the corresponding IDs for you. In either case the ID is then queried to verify that the correct group and agent entries are found.

The DEVICEID can be a PHONEID that is assigned to the agent.

Although AGENTID is the parameter in this function, the field used to identify the agent is USERID.

The result will include all data including the GROUPID and AGENTID if you did not pass them to the function.

Required Parameters
  • REQUESTID

  • ACTION (add or delete)

  • PHONEID OR DEVICEID

and

  • GROUPNAME or GROUPID

and

  • FIRSTNAME and LASTNAME or AGENTID

Optional Parameters

None

Possible Returns
  • Standard Result
  • Parameters Sent

Possible error returns are:

  • API_AGENT_NOT_FOUND — Request needs to find information for either the device or the agent; if neither is found, this error appears
  • API_DATABASE_QUERY_ERROR — Represents a range of possible query problems; check the API logs for details
Example(s):

<REQUEST>

<TYPE>MODIFYGROUPPERMISSION</TYPE>

<REQUESTID>2</REQUESTID>

<ACTION>ADD</ACTION>

<GROUPNAME>Sales & Marketing</GROUPNAME>

<FIRSTNAME>John</FIRSTNAME>

<LASTNAME>Doe</LASTNAME>

<DEVICEID>1234</DEVICEID>

</REQUEST>

MODIFYROLE
Description

Allows you to add an Uptivity Role.

You must supply either ADD, MODIFY, or DELETE as the ACTION type.

You must supply REQUESTID.

Uptivity will attempt to add the new role. ROLENAME and RESULTCODE is returned as the result. If a role with the same name already exists, the function will return as such without modifying any data.

Required Parameters
  • REQUESTID

  • ACTION (add/modify/delete)

  • ROLENAME

Optional Parameters
  • DESCRIPTION
Possible Returns
  • Standard Result
  • Parameters Sent

Possible error returns are:

  • API_DATABASE_QUERY_ERROR — Represents a range of possible query problems; check the API logs for details
  • API_ERROR_INVALID_ACTION — Allowed actions are ADD, MODIFY, DELETE; if the requested action is not one of these, this error will be displayed
  • API_INVALID_MESSAGE_FORMAT — This message appears if parameters are missing or the request is not formatted correctly
  • API_ROLE_ALREADY_EXISTS — The role the request is attempting to create already exists
  • API_ROLE_NOT_FOUND — The requested role does not exist or could not be located
Example(s):

<REQUEST>

<REQUESTTYPE>MODIFYROLE</REQUESTTYPE>

<REQUESTID>1</REQUESTID>

<ACTION>ADD</ACTION>

<ROLENAME>DefaultRole</ROLENAME>

<DESCRIPTION>Adding Default Role</DESCRIPTION>

 

</REQUEST>

<RESULT>

<REQUESTTYPE>MODIFYROLE</REQUESTTYPE>

<REQUESTID>45</REQUESTID>

<RESULTTYPE>API_OK</RESULTTYPE>

<RESULTCODE>20</RESULTCODE>

<RESULTMSG>Role Added</RESULTMSG>

</RESULT>

MODIFYROLEGROUPPERMISSION
Description

Used to assign a QA Group to a Role.

You must supply either ADD or DELETE as the ACTION type.

You must supply either ROLEID or ROLENAME, but you do not have to supply both.

Required Parameters
  • REQUESTID

  • ROLEID or ROLENAME

  • GROUPNAME

  • ACTION (add/delete)

Optional Parameters

None

Possible Returns
  • Standard Result
  • Parameters Sent

Possible error returns are:

  • API_DATABASE_QUERY_ERROR — Represents a range of possible query problems; check the API logs for details
  • API_ERROR_INVALID_ACTION — Allowed actions are ADD, MODIFY, DELETE; if the requested action is not one of these, this error will be displayed
  • API_INVALID_MESSAGE_FORMAT — This message appears if parameters are missing or the request is not formatted correctly
Example(s):

<REQUEST>

<REQUESTTYPE> MODIFYROLEGROUPPERMISSION </REQUESTTYPE>

<REQUESTID>1</REQUESTID>

<ACTION>ADD</ACTION>

<ROLENAME>DefaultRole</ROLENAME>

<GROUPNAME>CALLCOPYTESTGROUP</GROUPNAME>

</REQUEST>

 

<RESULT>

<REQUESTTYPE>MODIFYROLEGROUPPERMISSION</REQUESTTYPE>

<REQUESTID>1</REQUESTID>

<RESULTTYPE>API_OK</RESULTTYPE>

<RESULTCODE>20</RESULTCODE>

<RESULTMSG>Group Group01 does not exist or it is not active</RESULTMSG>

</RESULT>

MODIFYUSERROLE
Description

Used to assign Roles to Users. You can use any of these to associate user info: USERID, LASTNAME, FIRSTNAME, SYSTEMUSERNAME, or USERNAME.

You must supply either ROLEID or ROLENAME, but you do not have to supply both.

Required Parameters
  • REQUESTID

  • ROLEID or ROLENAME

  • USERID

  • LASTNAME

  • FIRSTNAME

  • SYSTEMUSERNAME

  • USERNAME

  • ACTION (ADD/MODIFY/DELETE)

Optional Parameters

None

Possible Returns
  • Standard Result
  • Parameters Sent

Possible error returns are:

  • API_DATABASE_QUERY_ERROR — Represents a range of possible query problems; check API logs for details
  • API_ERROR_INVALID_ACTION — Allowed actions are ADD, MODIFY, DELETE; if the requested action is not one of these, this error will be displayed
  • API_INVALID_MESSAGE_FORMAT — This message appears if parameters are missing or the request is not formatted correctly
  • API_ROLE_NOT_FOUND — The requested role does not exist or could not be located
  • API_USER_NOT_FOUND — When modifying or deleting an agent, this message indicates that the agent could not be found; if it appears as the result of a query error, check the API logs for details
Example(s):

<REQUEST>

<REQUESTTYPE> MODIFYUSERROLE </REQUESTTYPE>

<REQUESTID>1</REQUESTID>

<ACTION>ADD</ACTION>

<ROLENAME>DefaultRole</ROLENAME>

<USERNAME>TestUser</USERNAME>

</REQUEST>

 

<RESULT>

<REQUESTTYPE>MODIFYUSERROLE</REQUESTTYPE>

<REQUESTID>1</REQUESTID>

<RESULTTYPE>API_OK</RESULTTYPE>

<RESULTCODE>20</RESULTCODE>

<RESULTMSG>User 10 is assigned role Test</RESULTMSG>

</RESULT>

MODIFYROLEPERMISSION
Description

Used to modify permissions assigned to a Role. The PERMISSION NAME used in the API expression differs from the way the permission is listed in the Web Portal (see table). For details regarding permissions, see Roles and Permissions Overview.

You must supply either ROLEID or ROLENAME, but you do not have to supply both. If ROLENAME is used, the system will look up the associated ROLEID.

Required Parameters
  • REQUESTID

  • ROLEID or ROLENAME

  • PERMISSIONNAME (see table in Description)

  • ACTION (add/delete)

Optional Parameters

None

Possible Returns
  • Standard Result
  • Parameters Sent

Possible error returns are:

  • API_DATABASE_QUERY_ERROR — Represents a range of possible query problems; check API logs for details
  • API_ERROR_INVALID_ACTION — Allowed actions are ADD or DELETE; if the requested action is not one of these, this error will be displayed
  • API_INVALID_MESSAGE_FORMAT — This message appears if parameters are missing or the request is not formatted correctly
  • API_ROLE_NOT_FOUND — The requested role does not exist or could not be located
Example(s):

<REQUEST>

<REQUESTTYPE> MODIFYROLEPERMISSION </REQUESTTYPE>

<REQUESTID>1</REQUESTID>

<ACTION>ADD</ACTION>

<ROLENAME>DefaultRole</ROLENAME>

<PERMISSIONNAME>HOMEPAGEWIDGETS</PERMISSIONNAME>

</REQUEST>

 

<RESULT>

<REQUESTTYPE>MODIFYROLEPERMISSION</REQUESTTYPE>

<REQUESTID>1</REQUESTID>

<RESULTTYPE>API_OK</RESULTTYPE>

<RESULTCODE>20</RESULTCODE>

<RESULTMSG>Permission Added</RESULTMSG>

</RESULT>

EMAIL
Description Prompts Uptivity to export the audio recording to the email address provided.
Required Parameters
  • REQUESTID

  • IDENT (recording ID; can be a comma-separated list of multiple IDENTs)

  • TOADDRESS

  • MEDIA_FORMAT (MP3, WAV, VOX, or CAV)

  • You must supply values for all parameters.

Optional Parameters

None

Possible Returns
  • Standard Result
  • Email with media file attached (if multiple IDENTs were provided, the attachment will be a .zip file containing the requested media files)

Possible error returns are:

  • API_EMAIL_NOT_VALID — The email address in the request is incorrect or could not be found
  • API_ERROR_CLIENT_NOT_FOUND — The email server is not configured or cannot be found
  • API_FILE_NOT_FOUND — The specific file to be exported and emailed cannot be found
  • API_INVALID_MESSAGE_FORMAT — Appears if parameters are missing or the request is not formatted correctly
Example(s):

<REQUEST>

<TYPE>EMAIL</TYPE>

<REQUESTID>14</REQUESTID>

<IDENT>488373</IDENT>

<TOADDRESS>jdoe@uptivity.com</TOADDRESS>

<MEDIA_FORMAT>wav</MEDIA_FORMAT>

</REQUEST>

 

<RESULT>

<REQUESTTYPE>EMAIL</REQUESTTYPE>

<REQUESTID>14</REQUESTID>

<RESULTTYPE>API_OK</RESULTTYPE>

<RESULTCODE>20</RESULTCODE>

<RESULTMSG>API_OK</RESULTMSG>

</RESULT>

COMBINEDEMAIL
Description Prompts Uptivity to export one or more recording files as a single file to the email address provided.
Required Parameters
  • REQUESTID

  • TOADDRESS

  • TONAME

  • FROMADDRESS

  • FROMNAME

  • IDENT (Recording ID; multiple IDs can be separated by a comma)

  • UNIQUEID

Optional Parameters

None

Possible Returns
  • Standard Result

Possible error returns are:

  • API_EMAIL_NOT_VALID — The email address in the request is incorrect or could not be found
  • API_ERROR_CLIENT_NOT_FOUND — The email server is not configured or cannot be found
  • API_FILE_NOT_FOUND — A specific file to be exported and emailed cannot be found
  • API_INVALID_MESSAGE_FORMAT — Appears if parameters are missing or the request is not formatted correctly
Example(s):

<REQUEST>

<TYPE>COMBINEDEMAIL</TYPE>

<REQUESTID>1</REQUESTID>

<TOADDRESS>jane.doe@uptivity.com</TOADDRESS>

<TONAME>jane</TONAME>

<FROMADDRESS>jane.doe@uptivity.com</FROMADDRESS>

<FROMNAME>jane</FROMNAME>

<IDENT>1509</IDENT>

<UNIQUEID>IDENT</UNIQUEID>

</REQUEST>

 

<RESULT>

<REQUESTTYPE>COMBINEDEMAIL</REQUESTTYPE>

<REQUESTID>1</REQUESTID>

<RESULTTYPE>API_OK</RESULTTYPE>

<RESULTCODE>20</RESULTCODE>

<RESULTMSG>API_OK</RESULTMSG>

</RESULT>

AGENTWINDOW
Description Provides latest information on the agent's window as captured by NICE Uptivity Screen Recording.
Required Parameters
  • REQUESTID

  • COMPUTERNAME or

  • USERNAME

Optional Parameters

None

Possible Returns
  • Standard Result with screen information
    • Domain

    • IPADDRESS

    • STATUS

    • APPLICATIONTITLE

    • LASTUPDATE

Possible error returns are:

  • API_AGENT_NOT_FOUND — Request needs to find information for either the device or the agent; if neither is found, this error appears
  • API_DATABASE_QUERY_ERROR — Represents a range of possible query problems; check the API logs for details
Example(s):

<REQUEST>

<TYPE>AGENTWINDOW</TYPE>

<REQUESTID>7</REQUESTID>

<COMPUTERNAME>ceddy</COMPUTERNAME>

<USERNAME>ceddy</USERNAME>

</REQUEST>

 

<RESULT>

<REQUESTTYPE>AGENTWINDOW</REQUESTTYPE>

<REQUESTID>7</REQUESTID>

<RESULTTYPE>API_OK</RESULTTYPE>

<RESULTCODE>20</RESULTCODE>

<RESULTMSG>API_OK</RESULTMSG>

<DOMAIN>uptivity.com</DOMAIN>

<IPADDRESS>10.100.5.91</IPADDRESS>

<STATUS>AVAILABLE</STATUS>

<APPLICATIONTITLE>Internet Explorer</APPLICATIONTITLE>

<LASTUPDATE>Feb 2 2011 4:53PM</LASTUPDATE>

</RESULT>

See Also