Avaya Contact Recorder

Release 15.1
Search and Replay API Guide

Issue 4
Nov, 2015
Introduction
Verint ContactStore for Communication Manager Version 7.8 Service
Pack 1 and later versions provide an Application Programming Interface
(API) that you can use to access recordings. You can use the API to:
locate recordings and their associated context information
(sometimes called tagging data or metadata)
fetch the audio file associated with the recordings
delete recordings

The API operates over an HTTP or HTTPS interface. Each request is

independent (the server holds no session state). The response to the
request contains the results. Search requests return an XML document.
Audio requests return a WAV file. Delete requests return a
success/failure code. If the request is not understood or badly formatted
the server returns an HTTP status code other than 200.

Concepts
Recording segments
The recorder may segment the recording of a particular call into multiple
recording segments. It does this in particular when a call is put on hold or
transferred. You should therefore expect to possibly receive multiple
results from a search query, which may all be fragments of the same call.

Each recording segment is given a serial number known as the inum.

The inum is returned in the search results and is used as the key to
replay requests.

Replay Rights
Before you can search for and replay recordings the system administrator
must define which calls you may view.

This is configured in the administration console of the recorder in the

Users section. Each user may replay calls based on their replay rights.
API users are no different and must be given rights to replay some or all
calls. Each recording segment is given one or more owners. The owner of
a recording is normally the agent or station where the recording was
made. A replay right consists of a range of owners (frequently, therefore,
a range of stations) whos recordings that user may listen to.
Connecting to the API
Sending Commands
You should connect to the recorder using HTTP with URL:
http://recordername:8080/searchapi
(or use port 8443 and https)
You can connect using either GET or POST. You should configure your
HTTP client to automatically follow redirects.

Parameters
The parameters passed as part of the request (either following the ? in
the URL of a GET or in the header of a POST) control the API.

The cmd parameter is required and must be one of:

search
replay
delete

The other parameters vary according to the command type. The following
sections describe the parameters and responses for each of the three
commands.

Client Authentication
The API uses HTTP Basic Authentication to authenticate clients. You
must provide a username and password on every request. The username
and password must be concatenated with a colon, base 64 encoded and
provided in the Authorization header. If the Authorization header is
missing, cannot be understood or the credentials are bad the API returns
HTTP status 401.

Most HTTP clients have a feature to proactively send Basic

Authentication username and password with each request. The realm
used by the recorder is SearchAPI.

Creating an API user

You must create the username to be used by the client using the normal
method of adding users through the Administration web application. This
creates a user with an empty password. When the client connects for the
first time, the password that it supplies is remembered and must be
supplied on subsequent requests. If you ever need to change the
password, reset the users password through the Administration screens
and the new password will be remembered the first time that the client
connects.
Note: You must provide the API user with rights to play calls, like any
other user.
The SEARCH command
The search API re-uses the Search and Replay web applications layout
mechanism. A layout is format that defines the filters shown in the left
pane of the search and replay screen and the columns shown in the
results pane. There is one standard layout provided with the recorder.
(There are instructions in the PIA for adding additional layouts or
modifying the standard one using the Layout Builder)

When searching for recordings you must provide values that will be used
for all of the search filter fields. The names of the parameters are driven
by names of the parameters in the layout.

The results are provided as an XML document. The fields of the XML are
again driven by the layout. The names of the fields are the same as the
columns defined in the layout.

Search Parameters
The SEARCH command requires many parameters, most of which are
driven by the layout.

layout [optional]
Specifies the layout to use (defaults to cscm)

operator_filtername
For each filter you must provide the type of where clause operator that
will be used in the SQL search of the database. The possible values are:
0 do not include in the where clause
1 EQUALS tests for equality
2 LESS tests if the database value is less than the value supplied.
3 GREATER
4 LESS or EQUAL
5 GREATER or EQUAL
6 STARTS tests if the database value starts with the value supplied
7 ENDS
8 CONTAINS tests if the supplied value occurs in the database value
9 BETWEEN tests for database values between two supplied values.

paramN_filtername
For each filter you must provide up to 4 value parameters.
Most filters require just one the value to be tested against.
Date filters require four start and end for time and date

Simple example
Finding recordings longer than 60 seconds
operator_duration=3
param1_duration=60
 Date/Time example
operator_startedat=9 <- must always be 9 (between)
param1_startedat=08/08/08
param2_startedat=10:00:00
param3_startedat=08/08/08
param4_startedat=11:00:00

Date Formats
By default dates should be supplied in British (d/m/y) format, and times in
24 hour (military) format.
These defaults can be overridden by providing two additional parameters:
dateformat=MM/dd/yy
timeformat=hh:mm:ss a
These changes would change to North American, m/d/y, 12 hour format.

Debugging
When the recorders log file is running in DEBUG level the search
parameters are printed to the logfile, which can be very helpful in looking
for errors.

Results
The XML document returned contains one entry for each row in the
database meeting the filter criteria specified and the replay rights of the
API user. Each entry contains a field for every column of the layout.
However, if any value is NULL, that field is omitted.

Dates are in ISO 8601 format.

Durations in seconds
UCIDs are formatted in human readable fashion
The REPLAY command
The REPLAY command requires the inum parameter, which is the
recording reference which the command should act on.

The response to a REPLAY command is a mu-law WAV formatted

stream.

New in ACR 12.1

The replay command can retrieve whole sessions as well as individual

recordings. The inum parameter is renamed to id and represents either
a recording reference (inum) or session id. If it represents a session id it
must have a suffix denoting the particular party within the session,
separated by an underscore (_).

When replaying individual recordings, specify format=raw to fetch the

recording in its original format (not converted to mu-law).

The DELETE command

The DELETE command requires the inum parameter, which is the
recording reference which the command should act on.

After deleting a recording, you will receive a 404 error if you try to replay
it.
Examples

Example Search Request

http://devarch:8080/searchapi?command=search&layout=datesearchapi&par
am1_startedat=31%2F10%2F07&param2_startedat=00%3A00%3A00&param3_start
edat=31%2F10%2F08&param4_startedat=23%3A59%3A59&operator_startedat=9

http://devarch:8080/searchapi?command=search&layout=searchapi&param1_
startedat=31%2F10%2F08&param2_startedat=00%3A00%3A00&param3_startedat
=31%2F10%2F08&param4_startedat=23%3A59%3A59&operator_startedat=9&para
m1_partynames=1152&operator_partynames=8&param1_partyagentnames=&oper
ator_partyagentnames=0&param1_duration=&operator_duration=0&param1_vd
n=&operator_vdn=0&param1_callid=&operator_callid=0

Example Replay Request

http://devarch:8080/searchapi?command=replay&inum=800005000000015

From 12.1

http://devarch:8080/searchapi?command=replay&id=800005000000015
http://devarch:8080/searchapi?command=replay&id=xxxxxxxxxx_2

Example Delete Request

http://devarch:8080/searchapi?command=delete&inum=800005000000015