REST API Commands
Note:
Use GET as the HTTP method unless otherwise directed in the command description.API Command | Description |
---|---|
audioRecording/<command> | Retrieve recording metadata or
audio, control
ISR recording, or update
certain metadata. These commands require an authentication token. The
<command> argument can be one of the following values:
Note: The download and redirect commands are supported for single-segment recordings only. |
audioRecording/segment/<command> | Retrieve recording segment
metadata or audio, or update certain metadata. The command argument can be one
of the following values:
|
login | Authenticate a user/client to receive a token. |
eventNotify | Notify the FACE of the specified event, possibly causing Policy Actions to fire. |
StartScreenCapture | Begin ObserveIT Screen Recording. |
StopScreenCapture | End ObserveIT Screen Recording. |
version | Return the version number of the FACE software. |
URL-Encoding Special Characters
Special characters should be URL encoded (also known as percent-encoded) in URL parameters. For example, the plus (+) and at (@) signs are commonly used as SIP URI parameters (%2B and %3A, respectively).
Note:
Special characters should only be encoded within parameter values; you must leave them unencoded when they have meaning as part of the URL, for example, ampersand (&) when it is used to separate URL parameters.
Logging In to FACE
<scheme>://<host>:<port>/Face/login
If the user's credentials are correct but the password has expired, FACE returns an error message and does not create or return a token. Similarly, FACE returns a generic error message if the credentials are invalid or if a user has been locked out due to too many failed login attempts.
If the credentials are accurate, a new token is generated, added to the data structure, and returned. The expiration time is calculated based on the user's "expirationSeconds" value; if the user has not provided an "expirationSeconds" parameter, or that value is larger than the ISR's default maximum, the ISR's default maximum (1 day) is used.
The "userId" parameter limits which recordings the user may access and/or control, based on the user's account. A new user type, the "API User" must be created, and only that user type is allowed to use the FACE API. For more information, see "Creating an API User in this guide".
audioRecording Commands
This section describes FACE recording access and control.
Note:
Oracle recommends sending FACE requests in a controlled manner so that RSS and FACE connections are not fully utilized.
download
Note:
This command requires an authentication token.<scheme>://<host>:<port>/Face/audioRecording/download
redirect
<scheme>://<host>:<port>/Face/audioRecording/redirect
details
<scheme>://<host>:<port>/Face/audioRecording/details
start | pause | resume | stop
<scheme>://<host>:<port>/Face/audioRecording/<command>
When the body of the request is empty, it causes the action only. When the body of the request contains content, it causes the action as well as updates the recording in the
ISR.
split
<scheme>://<host>:<port>/Face/audioRecording/split
delete
<scheme>://<host>:<port>/Face/audioRecording/delete
Note:
Depending on your Archiver configuration, the length of time it may take for the file and metadata to be removed from the system can vary.Input Parameters
The following section describes all the HTTP POST request parameters, URL request parameters, and miscellaneous parameters.
HTTP POST Request Parameters
The following parameters can be included in the request body in an HTTP POST request:
- filename
- agentId
- agentTerminal
- sensitive (flag)
- setNeverExpire (flag)
- any defined Custom Data Field names (For more information, see "Viewing and Editing the Custom Data Master List" in the Oracle Communications Interactive Session Recorder Administrator Guide.)
URL Request Parameters
The URL request parameters are used to select the recording on which to act. Only recordings for which the user has permission to access are included in the results.
Note:
All requests must include a token parameter in the URL with a value equal to the token generated by the login command.The following are options for selection criteria:
General:
- isrUcid
- ingressCallId
- egressCallId
- thirdpartyId (for example, ObserveIT screen capture ID)
- ani/from
- dnis/to
- filename
- start
- earliestStart (only recordings starting at this time or later are matched, can be used with latestStart to refine the time range)
- latestStart (only recordings starting at this time or earlier are matched, can be used with earliestStart to refine the time range)
- end
- earliestEnd (only recordings ending at this time or later are matched)
- latestEnd (only recordings ending at this time or earlier are matched)
- aor
- any SIPREC extension data defined as "searchable" (metadata_types table)
- inProgress
Recording control only:
- channelNumber
- rssId
- recordingId/tmpRecordingId
- any defined Custom Data Field names (for more information, see "Viewing and Editing the Custom Data Master List" in the Oracle Communications Interactive Session Recorder Administrator Guide.)
- audioOnly: if 'true', only recordings with no supplemental files are matched.
- mustHaveVideo: if 'true', only recordings that have associated video files are matched; user, account, and route must allow video access.
- format (used to request special formatting, currently the only valid value is template).
- formatName (used to specify the name of the format item (for example, Template name)
- version (used to specify a
version for a formatName, if special formatting is requested and version is not
provided, the highest numbered version is used).
Note:
A special formatting reference example is available in "Common FACE Commands".
Note:
Parameter values are case-sensitive.The following miscellaneous parameters may also be included in some cases:
- maxListLength: Limits the maximum number of items returned that match the supplied Selection Criteria. Valid values are integers between 1 and 1000.
- fillWithSilence: By default,
silence is not inserted into the recording to indicate the pause. Set this
parameter to true to fill the paused section of audio with padded silence. If
omitted or set to false, the paused section of audio is truncated.
Note:
This parameter is only applicable for the pause command. - codecProfile: Overrides the
Codec Profile during ad hoc recording (for more information, see Managing
Recording Format Profiles in the Oracle Communications Interactive Session
Recorder Administrator Guide).
The following are valid values:
- 1 (Default)
- 2 (Smallest)
- 3 (Small)
- 4 (Best Quality)
- 5 (Firefox Compatible)
Note:
This parameter is only applicable for the start command.Return Data
All recording metadata, including custom data, SIPREC metadata and extension data, and supplemental file details are incorporated into the response when recording details are requested and a single entry is matched, unless special formatting is requested (see "Special Return Data Formatting"). This same data is included as part of the return for all audioRecording commands (with minor exceptions, such as retrieving the audio).
Selection criteria insufficient to determine recording. There were more matches than maxListLength, please refine your search if the entry you require is not in this list."
If the number of matches is less than maxListLength, the status message is:
"Selection criteria insufficient to determine recording. Returning all matches.
Currently, both XML and JSON response formats are supported. By default, XML is returned, but the "Accept" header of the request can be set to specify which option the client prefers (application/json or aplication/xml).
Note:
These examples are not meant to reflect all possibilities and the data returned may differ in your system.Single Match XML Example
<result>
<code>0</code>
<message>ACK</message>
<recording>
<recordingId>11905071</recordingId>
<ani>sipp_sd_siprec</ani>
<dnis>rss_sd_siprec</dnis>
<account>1</account>
<duration>120075</duration>
<startTime>2018-08-29 19:00:54.923</startTime>
<rss>2</rss>
<route>1</route>
<agentId/>
<sensitive>0</sensitive>
<deleteFlag>false</deleteFlag>
<isrUcid>x-isr-ucid-1-28605@10.10.248.209</isrUcid>
<ingressCallId>1-28605@10.10.248.209</ingressCallId>
<customDataSets>
<customData>
<customDataId>7</customDataId>
<name>CustomDataField1</name>
<value>uniqueCustomDataValue01730</value>
</customData>
</customDataSets>
<segments>
<segment>
<segmentId>1214965</segmentId>
<recordingId>11905071</recordingId>
<sequence>1</sequence>
<filename>rss_sd_siprec-1-28605@10.10.248.209.seg0.wav</filename>
<directory>/2018-08-29/19/00</directory>
<fileStatus>0</fileStatus>
<location>4</location>
<accountId>1</accountId>
<routeId>1</routeId>
<start>2018-08-29 19:00:54.923</start>
<end>2018-08-29 19:02:54.998</end>
<checksumMismatch>false</checksumMismatch>
<pauseLength>0</pauseLength>
<pausedWithSilence>false</pausedWithSilence>
<securedMedia>0</securedMedia>
<hasVideo>false</hasVideo>
<archived>1</archived>
<archivalRemarks>Recording was archived by archiver ID 2 process ID ap-isrdev-dh1-5.us.oracle.com16587116331 at Wed Aug 29 15:03:11 EDT 2018</archivalRemarks>
<archivalFailCount>0</archivalFailCount>
<archiverMode>Primary</archiverMode>
<archiverAction>0</archiverAction>
<conversionStatus>0</conversionStatus>
<customDataSets>
<customData>
<customDataId>9</customDataId>
<name>CustomDataField1</name>
<value>uniqueSegmentCustomDataFieldValue01810</value>
</customData>
</customDataSets>
<dtmfDigits/>
<siprecDataSets>
<siprecData>
<session>
<startTime>2017-10-25 14:44:39.0</startTime>
<siprecCallId>1-28605@10.10.248.209</siprecCallId>
<siprecSessionId>sIbybsXtQ7pivcNTRvEN4A==DH</siprecSessionId>
<extensionDataSets>
<extensionData>
<name>apkt:callerOrig</name>
<values>
<value>true</value>
</values>
</extensionData>
<extensionData>
<name>apkt:ucid</name>
<values>
<value>x-isr-ucid-1-28605@10.10.248.209</value>
</values>
</extensionData>
</extensionDataSets>
</session>
<participants>
<participant>
<siprecParticipantId>fhpR4z4qSy5x4H7aEzbsPg==DH</siprecParticipantId>
<aor>sip:sipp_sd_siprec@10.138.217.108:5060</aor>
<name>sipp_sd_siprec</name>
<startTime>2017-10-25 14:44:39.0</startTime>
<extensionDataSets>
<extensionData>
<name>apkt:callingParty</name>
<values>
<value>true</value>
</values>
</extensionData>
</extensionDataSets>
</participant>
<participant>
<siprecParticipantId>PdDRRcWbSzl0nE7mP5W9Vg==DH</siprecParticipantId>
<aor>sip:rss_sd_siprec@10.138.217.108:5060</aor>
<name>rss_sd_siprec</name>
<startTime>2017-10-25 14:44:39.0</startTime>
<extensionDataSets>
<extensionData>
<name>apkt:callingParty</name>
<values>
<value>false</value>
</values>
</extensionData>
</extensionDataSets>
</participant>
</participants>
<streams>
<stream>
<mode/>
<participantId>13139573</participantId>
<siprecStreamId>4MNYDBh8R8JK+ULKGHBapw==DH</siprecStreamId>
<startTime>2017-10-25 14:44:40.0</startTime>
<label>65537</label>
<extensionDataSets/>
</stream>
<stream>
<mode/>
<participantId>13139575</participantId>
<siprecStreamId>vPwZND2gStZcASJPa40xhQ==DH</siprecStreamId>
<startTime>2017-10-25 14:44:40.0</startTime>
<label>65536</label>
<extensionDataSets/>
</stream>
</streams>
</siprecData>
</siprecDataSets>
</segment>
</segments>
</recording>
</result>
Single Match JSON Example
{"result”:
{"code":0,
"message":"ACK”,
"recording”:
{"recordingId":11905071,
"ani":"sipp_sd_siprec”,
"dnis":"rss_sd_siprec”,
"account":"1”,
"duration":120075,
"startTime":"2018-08-29 19:00:54.923”,
"rss":2,
"route":1,
"agentId":”",
"sensitive":0,
"deleteFlag":false,
"isrUcid":"x-isr-ucid-1-28605@10.10.248.209”,
"ingressCallId":"1-28605@10.10.248.209”,
"customDataSets”:[
{"customData”:
{"customDataId":3,
"name":"CustomDataField1”,
"value":"uniqueCustomDataValue01730"}}],
"segments”:[
{"segmentId":1214965,
"recordingId":11905071,
"sequence":1,
"filename":"rss_sd_siprec-1-28605@10.10.248.209.seg0.wav”,
"directory":"/2018-08-29/19/00”,
"fileStatus":0,
"locationId":4,
"accountId":1,
"routeId":1,
"start":"2018-08-29 19:00:54.923”,
"end":"2018-08-29 19:02:54.998”,
"checksumMismatch":false,
"pauseLength":0,
"pausedWithSilence":false,
"securedMedia":0,
"hasVideo":false,
"archived":1,
"archivalRemarks":"Recording was archived by archiver ID 2 process ID ap-isrdev-dh1-5.us.oracle.com16587116331 at Wed Aug 29 15:03:11 EDT 2018”,
"archivalFailCount":0,
"archiverMode":"Primary”,
"archiverAction":0,
"conversionStatus":0,
"customDataSets”:[
{"customData”:
{"customDataId":3,
"name":"CustomDataField1”,
"value":"uniqueSegmentCustomDataFieldValue01810"}}],
"dtmfDigits":[],
"siprecDataSets”:[
{"siprecData”:
{"session":{"startTime":"2017-10-25 14:44:39.0”,
"siprecCallId":"1-28605@10.10.248.209”,
"siprecSessionId":"sIbybsXtQ7pivcNTRvEN4A==DH”,
"extensionDataSets”:[
{"extensionData”:
{"name":"apkt:callerOrig”,
"values”:[
{"value":"true"}]}},
{"extensionData”:
{"name":"apkt:ucid”,
"values”:[
{"value":"x-isr-ucid-1-28605@10.10.248.209"}]}}]},
"participants”:[
{"participant”:
{"siprecParticipantId":"fhpR4z4qSy5x4H7aEzbsPg==DH”,
"aor":"sip:sipp_sd_siprec@10.138.217.108:5060”,
"name":"sipp_sd_siprec”,
"startTime":"2017-10-25 14:44:39.0”,
"extensionDataSets”:[
{"extensionData”:
{"name":"apkt:callingParty”,
"values”:[
{"value":"true"}]}}]}},
{"participant”:
{"siprecParticipantId":"PdDRRcWbSzl0nE7mP5W9Vg==DH”,
"aor":"sip:rss_sd_siprec@10.138.217.108:5060”,
"name":"rss_sd_siprec”,
"startTime":"2017-10-25 14:44:39.0”,
"extensionDataSets”:[
{"extensionData”:
{"name":"apkt:callingParty”,
"values”:[
{"value":"false"}]}}]}}],
"streams”:[
{"stream”:
{"mode":”",
"participantId":"13139573”,
"siprecStreamId":"4MNYDBh8R8JK+ULKGHBapw==DH”,
"startTime":"2017-10-25 14:44:40.0”,
"label":"65537”,
"extensionDataSets":[]}},
{"stream”:
{"mode":”",
"participantId":"13139575”,
"siprecStreamId":"vPwZND2gStZcASJPa40xhQ==DH”,
"startTime":"2017-10-25 14:44:40.0”,
"label":"65536”,
"extensionDataSets":[]}}]}}],
"segment":{}}]}}}
Multiple Match XML Example
1) Audio Recordings with details.
curl -k -X POST "https://10.10.10.10:8443/Face/audioRecording/details?token=9a37ac05-3cd6-4e81-b224-97cfbb85f912"
<?xml version="1.0" encoding="UTF-16"?>
<result>
<code>-1</code>
<message>Selection criteria insufficient to determine recording. Returning all matches.</message>
<matches>
<match>
<recordingId>15</recordingId>
<isrUcid>x-isr-ucid-1-28520@1.2.3.4</isrUcid>
<ingressCallId>1-28520@1.2.3.4</ingressCallId>
<from>7777</from>
<to>5555</to>
<start>2021-01-18 06:37:27</start>
</match>
<match>
<recordingId>16</recordingId>
<isrUcid>x-isr-ucid-2-28520@1.2.3.4</isrUcid>
<ingressCallId>2-28520@1.2.3.4</ingressCallId>
<from>7777</from>
<to>5555</to>
<start>2021-01-18 06:37:37</start>
</match>
</matches>
</result>
2) Audio Recordings with segment details.
curl -k -X POST "https://10.10.10.10:8443/Face/audioRecording/segment/details?token=9a37ac05-3cd6-4e81-b224-97cfbb85f912"
<?xml version="1.0" encoding="UTF-16"?>
<result>
<code>-1</code>
<message>Selection criteria insufficient to determine recording. Returning all matches.</message>
<matches>
<match>
<segmentId>21</segmentId>
<recordingId>15</recordingId>
<filename>5555-1-28520@1.2.3.4.seg0.rpdd</filename>
<start>2021-01-18 06:37:27</start>
<end>2021-01-18 06:37:37</end>
<hasVideo>false</hasVideo>
</match>
<match>
<segmentId>22</segmentId>
<recordingId>16</recordingId>
<filename>5555-2-28520@1.2.3.4.seg0.rpdd</filename>
<start>2021-01-18 06:37:37</start>
<end>2021-01-18 06:37:47</end>
<hasVideo>false</hasVideo>
</match>
</matches>
</result>
Special Return Data Formatting
URL Parameter | Description |
---|---|
format | The type of special formatting requested; currently only template is supported. |
formatName | The name of the specific format/template (for example, Verint) |
version | The version of the specified formatName to use to format the response. If special formatting is requested but version is not specified, the highest numbered version of that formatName is used by default. |
Note:
For more information on creating Templates, see "Managing Templates" in the Interactive Session Recorder Administrator Guide.file/download
Required Input Parameters
Parameter | Description |
---|---|
token | Authentication and authorization token. |
filename | The name of the file to download (currently only supplemental and video files can be downloaded using this method). |
supplementalFileId | The supplemental file ID of the file to download (this can be found in associated recording's audioRecording/details). |
Optional Parameter
Parameter | Description |
---|---|
type | Specifies the type of supplemental file to download to help narrow the search. Do not this information unless you know the type with certainty (currently video is the only option supported). |
eventNotify
Currently FACE supports AudioRecordingStarted and AudioRecordingEnded Events, although custom event types can be configured. See FACE Policy System for more information.
Note:
The Optional Input Parameters listed below are used in the currently supported Events. Other Events may require different parameters.Required Input Parameters
Parameter | Value | Description |
---|---|---|
event | <event type> | The type of event |
Optional Input Parameters
Parameter | Value | Description |
---|---|---|
calledAors | <AORS List> | The list of Addresses of Record (AOR) for the called parties of the session |
ucid | <ISR UCID> | The ISR UCID identifying the session |
Note:
For more information about using ISR UCIDs, see "Determining the ISR UCID".The following is an example of using the eventNotify REST API command.
https://1.2.3.4:8443/Face/eventNotify?event=AudioRecordingStarted&ucid=fbd5715afe5aca679d1c9230dce37e73@1.2.3.5&calledAors=sip:agentX@1.2.3.4.11,sip:agentY@1.2.3.4.13
Response:
<response>
<Code>0</Code>
<message>success</message>
</response>
StartScreenCapture
Required Input Parameters
Parameter | Description |
---|---|
IsrId | UCID of the session |
AgentId or ScreenIP | The registered DNIS or ANI of the Agent Screen to capture or the IP address of the agent screen to capture. |
Note:
For more information about using ISR UCIDs, see "Determining the ISR UCID".The following is an example of using the StartScreenCapture REST API command.
https://1.2.3.4:8443/Face/StartScreenCapture?IsrId= fbd5715afe5aca679d1c9230dce37e73@1.2.3.5&AgentId=6789
Response:
<response>
<Code>0</Code>
<message>ACK</message>
</response>
StopScreenCapture
Required Input Parameters
Parameter | Description |
---|---|
AgentId or ScreenIP | The registered DNIS or ANI of the Agent Screen to capture or the IP address of the agent screen to stop capturing. |
The following is an example of using the StopScreenCapture REST API command.
https://1.2.3.4:8443/Face/StopScreenCapture?AgentId=6789
Response:
<response>
<Code>0</Code>
<message>ACK</message>
</response>
version
Required Input Parameters
None
The following is an example of using the version REST API command.
https://1.2.3.4:8443/Face/version
Response:
<result>
<version>5.2.0M0P0 build <build #></version>
</result>
Return Codes
Return Code | Message |
---|---|
0 | ACK |
0 | %command% command returned successfully (where %command% equals one of the supported commands) |
0 | This file has been renamed by the recorder, please use the following new filename for future commands: %filename% |
-1 | NACK |
-1 | %miscellaneous error message% |
-1 | Selection criteria insufficient to
determine recording. Returning all matches.
Note: It must be clearly explained that client applications may intentionally offer insufficient parameters with the expectation of a list of related recordings in the response, in which case the "-1" status code likely will be ignored. The "Common FACE Commands" section presents multiple examples of this type of implementation. |
1 | Feature Not Licensed |
2 | Host Not Authorized |
3 | Parameter Missing |
4 | Missing Command - command parameter is required |
5 | Invalid Command |
6 | Missing Parameter - ANI parameter is required |
7 | Missing Parameter - DNIS parameter is required |
8 | Missing Parameter - channelId parameter is required |
9 | Missing Parameter - fileId parameter is required |
10 | Error establishing database connection |
11 | Error retrieving filename for ANI %ANI% DNIS %DNIS% at timestamp of %timeStamp% |
11 | Error retrieving file info for ANI %ANI% DNIS %DNIS% at timestamp of %timeStamp% |
11 | Error retrieving file for ANI %ANI% DNIS %DNIS% at timestamp of %timeStamp% |
11 | Error retrieving file with supplied criteria |
12 | Recording has already started on this channel. |
12 | Recording is not paused, cannot unpause recording. |
12 | Recording is started by another session or not started, cannot pause recording. |
12 | Recording has already been paused, cannot pause recording. |
12 | Recording is started by another session or not started, cannot unpause recording. |
13 | Recording is started by another session or not started, cannot end recording. |
14 | Invalid Parameter for RecordEnd - fileId not found from recording index. |
15 | Error Indexing for RecordEnd - %SQLException% |
16 | Error Generating Token |
17 | Couldn't find route information |
17 | Route is not RecordAndSave application type |
17 | Couldn't find route information for ANI %ANI% DNIS %DNIS% or route is not RecordAndSave application type |
18 | ANI and DNIS are required for command SaveRecording |
19 | No recording found with supplied criteria |
20 | RSS could not successfully perform the operation |
21 | Cannot change name of file while recording is in progress |
22 | Cannot rename a file that is set to be deleted |
23 | Could not convert file to playable format |
24 | Timed out waiting for file conversion |
25 | Conversion already initiated by another user, please try again later |
26 | No session or file was found matching the provided UCID |
27 | Missing Parameter - %parameter% is required |