Search Replay A Pi 421i1o

Avaya Recorder Release 15.1 Search and Replay API Guide

Issue 4 Nov, 2015

Introduction Verint Store 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 must define which calls you may view. This is configured in the istration console of the recorder in the s section. Each may replay calls based on their replay rights. API s 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) who‟s recordings that 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 ed 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 name and on every request. The name and 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 name and with each request. The realm used by the recorder is SearchAPI.

Creating an API You must create the name to be used by the client using the normal method of adding s through the istration web application. This creates a with an empty . When the client connects for the first time, the that it supplies is ed and must be supplied on subsequent requests. If you ever need to change the , reset the ‟s through the istration screens and the new will be ed the first time that the client connects. Note: You must provide the API with rights to play calls, like any other .

The SEARCH command The search API re-uses the Search and Replay web application‟s “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 recorder‟s 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 . 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¶ 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