VSLogger HTML API| Call Recording Reference

Adutante H5/VSLogger H5 HTML API service.

Version 1 ( released with VSLogger ver. 4.6.1.4, Feb 2015)

1. General Info

Entry Point

<recorderhost>/api/v1
<vsloggerhost>/api/v1

Collection Resources

recordings
channel-states

Individual Resources

recording
channel-state

HTTP Methods used

Main

GET (SELECT): Retrieve a specific Resource from the Server or a listing of Resources.
POST (CREATE): Create a new Resource on the Server.
DELETE (DELETE): Remove a Resource from the Server.

Supporting

OPTIONS – Retrieve information about what the Consumer is allowed to do with the Resource.

Versadial API Usage

Method	Scope	Semantics
GET	collection	Retrieve all resources in a collection
GET	individual resource	Retrieve a single resource
POST	collection, individual resource	Create a new resource in a collection, Update a resource, Create query
DELETE	individual resource	Delete a resource
OPTIONS	any	Return available HTTP methods and other options

Response Representation

Majority of the responses, returned as JSON object. Exception is binary downloads e.g. application/wav

Type	Content-Type
JSON	application/json application/json
Wave file	application/wav

Result JSON object Convention (Fail / Success )

if no exception occurs, result always should be JSON object

{status:xxx, data:object, errmessage: text message }

status:

0 - success, data object contains operation response object, command specific

-1 - fail generic, with optional message

-2 - session problem (e.g. timeout , missing etc)

-3 -permission error ("Action not permitted!)

-4 -HASH error (with optional error message , if SECURITY HASH inabled)

data:object API call is specific and described in individual API method

2. Parameter/Content Passing

One or more parameter styles are supported by specific endpoint.

Query:

query?cmd=value1&param2=value2…

Form:

<form action="rest/myservice" method="post" enctype="application/x-www-form-urlencoded">

<p>

Name : <input type="text" name="name" />

</p>

<p>

Age : <input type="text" name="age" />

</p>

<input type="submit" value="Add User" />

</form>

JSON:

xhr.open("POST",URL);//post/get and your URL

xhr.setRequestHeader("content-type", "application/json");
var param={
      "user":{"email":"someone@email.com",
                  "password":"secure"
                }
          };
xhr.send(JSON.stringify(param));

URL naming convention

<recorderhost>/api/v1?res=resourcename - version 1 of API
<recorderhost>/api/v2?res=resourcename - version 2 of API

SECURITY HASH naming feature and convention

API and API security hash should be enabled on VSLogger server.

Following parameters set on server (CLI tool, see VSLogger administration)

API_ENABLED: True/false

HASHTYPE : NONE , SHA-1 or SHA-256

SALT: security string

If HASHTYPE not equeal to NONE, client requests should pass following parameters with URL Query

ss - client generated random string at min. 10 char, eg currentime in mills. As integer, represented as string

hh - HASH (ss+SALT+ resource) , corresponding hash value, as hex string

e.g. <recorderhost>/api/v1?res=channel-state&ss=1427319442972&hh=1f236849455ad2347...

3. API

3.1 channel-state and channel-states

Channel state is a collection of values associated with channel object at specific time. Most of the channel state values make sense only during call.

Changing some of the state values will result in actions performed on the recorder. e.g. record = true, starts recording on specific channel etc.

All supported and readable channel state values

channel - channel number (1-256)
start_tm - start time UTC ( milliseconds)
direction - call direction (0- out, 1- in, 2 -unknown)
caller_id - caller Id
dialed -dialed number
note - note
extension - phone extension
ch_name - channel description
agent_id - agent id (Call center)
client_id - client id (Call center)
session_id - call session id
source - source (0 - phone, )
flag - flag ( 0-10) 0 - none
campaign_id - campaign id (Call center)
enable - enabled (true/false)
record - recording (true/false)
mute - muted (true/false)
onoff - streaming/active (true/false)

States used as channel object selector

channel

States changeable via API requests

mute -true/false
record -true/false
enable -true/false
dialed - Dialed number. Applicable only, if call is in progress
caller_id - Caller ID . Applicable only, if call is in progress
note - note. Applicable only, if call is in progress
session_id - call session id. Applicable only, if call is in progress
extension - phone extension
flag - Flag (0-10)
direction - Call Direction (0- out, 1- in, 2 -unknown)

 
3.1.1 GET all channel states command 
 
GET    <recorderhost>/api/v1?res=channel-states&optional security hash params
 
Result   data: [{mute:false,record:false,enable:false....},{}, ..  ]  
array of objects for all channels [1..N]
 
3.1.2 GET channel state command 
 
GET    <recorderhost>/api/v1?res=channel-state&channel=N&optional security hash params
 
Result   data: {mute:false,record:false,enable:false....}  
Single object for requested channel N.

3.1.3 MUTE Commands (state resource)

Sample Channel state change e.g. Mute.

POST <recorderhost>/api/v1?res=channel-state&optional security hash params

Extra parameters passed as Form

channel = channel number
mute= true/false

one or more extra parameters.

note = " Partially muted".

Result data:""

3.1.4 RECORD  Commands (state resource)
 
Sample Channel state change e.g. Record.

POST    <recorderhost>/api/v1?res=channel-state&optional security hash params
 
Extra parameters passed as Form
channel=  channel number 
record= true/false
one or more  extra parameters.
dialed = "11111111".  
Result   data:""

3.1.5 ENABLE  Commands (state resource)
 
Sample Channel state change e.g. Record.

POST    <recorderhost>/api/v1?res=channel-state&optional security hash params
 
Extra parameters passed as Form
channel=  channel num, 
enable= true/false
 
Result   data:""
 
3.2  recording and  recordings

Recording object attributes, (Note: vslogger and adutante recording attributes may differ)

Adutante recording fields: refer to application/adutante/entitydef/entitymodel_recorders.xml , entity-name "recRecord"

VSLogger Recording DB record fields

record_id (string) - serves as File name at the same time YYYYMMDDHHMMSS_CCC_0 (CCC - channel number as 003 etc, last .0 is stream label)
archive_id (string) - archive id ("MAIN" for main dB, "NET" - for netshare) or Archive ID ( corresponds to dataset in requests )
record_type (string) - VSL, WAV
session_id (string) - call session id (for example sip CALLID tag)
channel - (int) 1..256 () channel number
ch_name - (string) channel description
start_tm (int) - UTC // mills
end_tm (int) - UTC //mills
duration (int) - call duration mills.
modified (int) - 0 not modified, 1 - modified ( audio modified)
closed (int) - 0 - not closed ( in call or application hanged and did not close recording) 1 -closed
flag (int)- 0-10 ... any defined flags
direction (int) call direction (0 - out, 1 -in, 2 -unknown )
agent_id (string) got from seating or NULL
agent_name(string) - agent name
client_id (string) - client id or NULL
client_name (string) - client name
campaign_id (string) - campaign id
extension (string) - phone extension
dialed (string) - dialed number
caller_id (string) - caller id
note (text) - note

dynamically generated fields(Not stored in DB) . Available since ver.4.9.6.X

rec_ss (int) - sequence parameter used for access link/download recording URL generation
rec_hh (text) - hash parameter used for access link/download recording URL generation

 
3.2.1 Find recordings  ( search and paginated retrieve. HTML POST used to simplify parameter passing)
 
POST    <recorderhost>/api/v1?res=recordings&optional security hash params
 
All parameters are optional, except draw . 
Parameters:   

draw= 1..N integer generated by client. e.g. request number. Will be returned with response to simplify client handling of async requests. (required)

dataset= MAIN or NET (optional,  default is MAIN)
channels= [0,1,10,11,14]  (optional,  default is all channels. NOTE: if channels parameter provided with empty array, empty result will be returned). 
from= time range start, UTC time, in mills , as string (optional. default from beginning of time )
to = time range end, UTC time, in mills , as string  (optional. default to current time )
page=  0..N, page to return   (optional. default- 0, initial page )
pagesize = 50 (  default 100, min 10)
 
andparams    =   [{fld:"note",val:"test", op:"equals" or "contains" },{fld:"sessionid", val:"4efa7d29eb9f47c8aa615f3b74de22d5", op:"equals" or "contains"}] (optional extra parameters applied with AND )  
orparams =  [{fld:"note",val:"test", op:"equals" or "contains" },{fld:"sessionid", val:"4efa7d29eb9f47c8aa615f3b74de22d5", op:"equals" or "contains"}] (optional extra parameters applied with OR ) 
hrefexp = 7,  record access expiration in days (1..30,   default 7 )  Available since ver.4.9.6.X

fld=["note","sessionid","callerid","dialed","extension","recordid"]

Result data: {draw:100 ,totalcount:10030, page:N, pagesize:N, records: [{field:val...},{field:val..}, .. ] }

3.2.2 Download recording   ( download recording file. Recording will be converted to WAV automatically)
 
 
GET    <recorderhost>/api/v1?res=recording&href=archive_id.record_id.record_type&optional security hash params 
 
href: <archive_id>.<record_id>.<record_type>.<rec_ss>.<rec_hh>
 
Result   data:  file downloaded with Content-Type : application/wav
 
Note : <rec_ss>.<rec_hh>, required since ver. since ver.4.9.6.X  . Received via 3.2.1 Find recordings 
 
 
 
3.2.3 Access recording by link   (open web page with embedded HTML Player) Available since ver.4.9.6.X
 
GET    <recorderhost>/api/link?playlist=archive_id.record_id.record_type&ss=rec_ss&hh=rec_hh 
 
3.2.4  Update recording DB record fields   Available since ver.5.0.1.X
 
POST   <recorderhost>/api/v1?res=recording&id=archive_id.record_id.record_type&optional security hash params 
 
Parameters:

dialed       - Dialed number 
caller_id   - Caller ID 
note         -  note.
session_id - call session id. 
extension  - phone extension
flag          -  Flag (0-10)
direction   - Call Direction (0- out, 1- in, 2 -unknown)
device_id - Device ID

 

3.3  channel-cmd ( simplistic way to send channel commands: "recstart","recstop","mute","unmute","enable","disable","update")
Available only from rev. 4.9.5.0 and newer.
 
 
GET    <recorderhost>/api/v1?res=channel-cmd&channel=<1-999>&cmd=<command>&<optional security hash parameters>
 
channel - channel  number (1-999) - required
cmd  -  operation command 
 
Supported  operation commands:
 
"recstart" - start recording
"recstop" - stop recording
"mute" - mute recording
"unmute"- unmute recording
"enable" - enable channel
"disable" - disable channel
"update" - update fields
 
Call recording Fields.
 
If present in command line(URL) as an attribute , corresponding call recording fields will be updated by provided values.
dialed       - Dialed number. Applicable only, if call is in progress 
caller_id   - Caller ID . Applicable only, if call is in progress 
note         -  note.  Applicable only,  if call is in progress 
session_id - call session id. Applicable only,  if call is in progress 
extension  - phone extension
flag          - Flag (0-10)
direction   - Call Direction (0- out, 1- in, 2 -unknown)
device_id  - Device ID
 3.4  call-state  and call-states Available only from rev. 5.1.0.0 and newer.
 
call-state is an object and collection of values associated with a LIVE call .  call-state values make sense only during the call.
Changing some of the values will result in actions performed on the recorder. e.g. record = true, starts recording on specific call etc.
call_state  object defined by call_id - parameter available during live call for specific hw channels only. Only SIPREC  and VOIP hardware  support this  feature 
 
Currently Supported locators.
Other call-id Sources can be added on demand (contact Versadial sales)
 


call_id Source/ Vendor
HW
Locator

SIPREC Metadata/ Oracle SBC
SIPREC (RFC protocol only)
<apkt:header label="Call-ID">
<value>0gQAAC8WAAA....</value></apkt:header>


SIP header 
VOIP
Call-ID: 3848276298220188511@atlanta.example.com

 
 
All supported and readable  call values 
call_id         - call-id 
channel         - channel number (1-256) 
start_tm        - start time UTC ( milliseconds)    
direction        - call direction   (0- out, 1- in, 2 -unknown)
caller_id        - caller Id     
dialed            -dialed number 
note              - note
extension      - phone extension 
ch_name       - channel description
agent_id        - agent id (Call center) 
client_id        - client id  (Call center)
session_id     - call session id
source          - source (0 - phone,  ) 
flag               - flag ( 0-10)  0 - none
campaign_id   - campaign id (Call center)  
 
 
record           - recording (true/false) 
mute             - muted (true/false)  
States used as channel object selector 

call_id
hw   siprec/voip

States changeable via API requests
mute                 -true/false
record               -true/false
dialed       - Dialed number. Applicable only, if call is in progress 
caller_id   - Caller ID . Applicable only, if call is in progress 
note         -  note.  Applicable only,  if call is in progress 
session_id - call session id. Applicable only,  if call is in progress 
extension  - phone extension
flag          - Flag (0-10)
direction   - Call Direction (0- out, 1- in, 2 -unknown)
device_id   -device id
 
3.4.1 GET all calls command    NOT SUPPORTED
GET    <recorderhost>/api/v1?res=calls&optional security hash params
Result   data: [{mute:false,record:false,...},{}, ..  ]  
array of objects for all calls [1..N]
 
3.4.2 GET call command 
GET    <recorderhost>/api/v1?res=call&call_id=....&hw=siprec&optional security hash params
Result   data: {mute:false,record:false,....}  
Single object for requested call_id N. 
 
 
3.4.3 MUTE  Commands (call-state resource)
 
Sample Channel state change e.g. Mute.

POST    <recorderhost>/api/v1?res=call-state&optional security hash params
 
Required parameters passed as Form
call_id =  call-id 
hw = siprec/voip
mute= true/false
one or more  extra parameters e.g.
note =  " Partially muted".  
 
Result   data:""
 
3.4.4 RECORD  Commands (call-state resource)
 
Sample Call state change e.g. Record.

POST    <recorderhost>/api/v1?res=call-state&optional security hash params
 
Required parameters passed as Form
call_id=  call-id 
hw = siprec/voip
record= true/false
one or more  extra parameters e.g.
dialed = "11111111".  
Result   data:""
 
4.   Sample code4.1  FORM  Parameter passing  (C#)
.....  for example to mute channel 5
using System.Net;
using System.Web;
..

 var request = (HttpWebRequest)WebRequest.Create(uri);
 string postData =   "channel=5&mute=true";
// optionally set note field at the same time
postData  += "&note=  +  Uri.EscapeDataString("Note value can be Non ASCII");

 var data = Encoding.ASCII.GetBytes(postData);
 request.Method = "POST";
 request.ContentType = "application/x-www-form-urlencoded; charset=UTF-8";
 request.ContentLength = data.Length;

 using (var stream = request.GetRequestStream())
 {
 stream.Write(data, 0, data.Length);
 }

 var response = (HttpWebResponse)request.GetResponse();
 result = new StreamReader(response.GetResponseStream()).ReadToEnd();
 
4.2  FORM  Parameter passing  (VB)
.....  for example to mute channel 5

  Dim request As WebRequest = WebRequest.Create(uri)
 ' Set the Method property of the request to POST.
 request.Method = "POST"
 Dim postData As String = ""
' Create urlencoded form parameters 

' for example to mute channel 5 
' postData = "channel=5&mute=true";

 ' Create POST data and convert it to a byte array.
 Dim byteArray As Byte() = Encoding.ASCII.GetBytes(postData)
 ' Set the ContentType property of the WebRequest.
 request.ContentType = "application/x-www-form-urlencoded; charset=UTF-8"
 ' Set the ContentLength property of the WebRequest.
 request.ContentLength = byteArray.Length
 ' Get the request stream.
 Dim dataStream As Stream = request.GetRequestStream()
 ' Write the data to the request stream.
 dataStream.Write(byteArray, 0, byteArray.Length)
 ' Close the Stream object.
 dataStream.Close()

 ' Get the response.
 Dim response As WebResponse = request.GetResponse()
 ' Display the status.
 ' MessageBox.Show(CType(response, HttpWebResponse).StatusDescription)
 ' Get the stream containing content returned by the server.
 dataStream = response.GetResponseStream()
 ' Open the stream using a StreamReader for easy access.
 Dim reader As New StreamReader(dataStream)
 ' Read the content.
 Dim responseFromServer As String = reader.ReadToEnd()
 ' Return the content.
 result = responseFromServer
 ' Clean up the streams.
 reader.Close()
 dataStream.Close()
 response.Close()
....

Adutante H5/VSLogger H5 HTML API service.

1. General Info

Collection Resources

Response Representation

2. Parameter/Content Passing

URL naming convention

SECURITY HASH naming feature and convention

3. API

3.1 channel-state and channel-states

3.2 recording and recordings

3.3 channel-cmd ( simplistic way to send channel commands: "recstart","recstop","mute","unmute","enable","disable","update")

3.4 call-state and call-states

4. Sample code

4.1 FORM Parameter passing (C#)

4.2 FORM Parameter passing (VB)