Adutante H5 / VSLogger API de servicio H5 HTML
Versión 1 (publicado con VSLogger ver 4.6.1.4, Feb 2015)
1. Información General
Punto de entrada
- <recorderhost>/api/v1
- <vsloggerhost>/api/v1
Recursos de recolección
- recordings
- channel-states
Recursos Individuales
Métodos HTTP utilizados
Principal
- GET (SELECT): Recupera un recurso específico del servidor o una lista de recursos.
- POST (CREATE): Cree un nuevo recurso en el servidor.
- DELETE (DELETE): elimina un recurso del servidor.
Supporting
- OPTIONS – Recuperar información sobre lo que el consumidor puede hacer con el recurso.
Uso Versadial API
| Method | Scope | Semantics |
|---|
| GET |
collection |
Recuperar todos los recursos de una colección |
| GET |
individual resource |
Recuperar un solo recurso |
| POST |
collection, individual resource |
Crear un nuevo recurso en una colección, Actualizar un recurso, Crear consulta |
| DELETE |
individual resource |
Eliminar un recurso |
| OPTIONS |
any |
Devolver los métodos HTTP disponibles y otras opciones |
Representación de Respuesta
Mayoría de las respuestas, devueltas como objeto JSON. La excepción son las descargas binarias, p. Aplicación / wav
| Tipo | Tipo de contenido |
|---|
|
JSON
|
application/json
application/json
|
|
Wave file
|
|
Resultado JSON object Convention (Fail / Success)
Si no se produce ninguna excepción, el resultado siempre debe ser objeto JSON
{status:xxx, data:object, errmessage: text message }
status:
0 - éxito, objeto de datos contiene objeto de respuesta de operación, comando específico
-1 - error genérico, con mensaje opcional
-2 - problema de sesión (por ejemplo, tiempo de espera, falta etc)
-3 -permitir error ("Acción no permitida!)
-4 -HASH error (con mensaje de error opcional, si HASH de seguridad habilitado)
data: object - llamada a la API específica y descrita en el método API individual
2. Parámetro / paso del contenido
Uno o más estilos de parámetros son compatibles con un punto final específico.
Query:
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));
Convención de nomenclatura de URL
- <recorderhost>/api/v1?res=resourcename - version 1 of API
- <recorderhost>/api/v2?res=resourcename - version 2 of API
SECURITY HASH nombre de la característica y la convención
El hash de seguridad API y API debe estar habilitado en el servidor VSLogger.
Después de los parámetros establecidos en el servidor (herramienta CLI, consulte la administración de VSLogger)
API_ENABLED: True/false
HASHTYPE : NONE , SHA-1 or SHA-256
SALT: security string
Si HASHTYPE no es equeal a NONE, las solicitudes de cliente deben pasar los siguientes parámetros con URL Query
Ss - cadena aleatoria generada por el cliente en min. 10 char, por ejemplo currentime en molinos. Como entero, representado como cadena
Hh - HASH (ss + SALT + recurso), valor de hash correspondiente, como cadena hexadecimal
e.g. <recorderhost>/api/v1?res=channel-state&ss=1427319442972&hh=1f236849455ad2347...
3. API
3.1 channel-state and channel-states
El estado del canal es una colección de valores asociados con el objeto de canal en un momento específico. La mayoría de los valores de estado del canal tienen sentido sólo durante la llamada.
El cambio de algunos de los valores de estado dará como resultado acciones realizadas en la grabadora. p.ej. Record = true, inicia la grabación en un canal específico, etc.
Todos los valores de estado del canal admitidos y legibles
- 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)
Estados utilizados como selector de objetos de canal
Estados cambiables a través de solicitudes API
- 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.
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
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
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 )
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>
Result data: file downloaded with Content-Type : application/wav
4. Sample code
4.1 FORM Parameter passing (C#)
..... for example to mute channel 5using System.Net;using System.Web;.. var request = (HttpWebRequest)WebRequest.Create(uri); string postData = "channel=5&mute=true";// optionally set note field at the same timepostData += "¬e= + 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()....