GUIDA INTEGRAZIONE VOIspeed

Introduzione

La piattaforma telefonica VOIspeed dispone di strumenti di integrazione potenti e flessibili che permettono la realizzazione di molte funzionalità per coprire infinite esigenze applicative.

Nel corso di questa guida descriveremo, dapprima, alcuni concetti base dell’architettura della piattaforma VOIspeed e del suo funzionamento; l’introduzione sarà necessaria a comprendere appieno gli strumenti di sviluppo disponibili.

Proseguiremo, poi, con l’analisi dei vari strumenti di integrazione disponibili e come vanno configurano per essere subito operativi. Contestualmente a questa sezione scriveremo le nostre prime applicazioni “ciao mondo”, una per ogni tipo di integrazione.

Architettura VOIspeed

Entità di sistema

Le ENTITA’ DI SISTEMA sono gli elementi costitutivi della piattaforma
VOIspeed che interagiscono tra loro dando luogo a chiamate e altre forme
di interconnessione (Fig. 1.1).

Figura 1.1

Le entità di sistema derivano da una superclasse che ne definisce l’interfaccia di utilizzo. Esse sono divise in categorie, ciascuna delle quali definisce un comportamento tipico per la categoria stessa attivabile tramite l’interfaccia comune (Fig. 1.2).

Figura 1.2

Ciascuna entità è definita da un identificativo (ID), univoco all’interno della sua categoria, e dalla categoria stessa (TYPE).

La tabella 1 elenca tutti i tipi di entità e relativi valori.

Le entità di sistema si dividono in entità atomiche ed entità
composte.

Le entità composte, oltre ad implementare il comportamento definito dalla loro categoria di appartenenza, contengono al loro interno altre entità atomiche o composte a loro volta.
L’esempio per eccellenza di entità composta è il gruppo di squillo che al suo interno racchiude N utenti.
Gli utenti stessi sono delle entità composte poiché al loro interno comprendono gli M terminali (DEVICE) ad essi associati (vedi figura 1.3).

Figura 1.3

Configurazione
Tutte le entità di sistema possono essere aggiunte, modificate ed eliminate dal configuratore WEB. In particolare:

Ciascuna entità di sistema può essere configurata secondo quanto
previsto dalla sua categoria di appartenenza.

La configurazione di un gruppo di squillo, ad esempio, riguarda quanti e quali utenti dovranno squillare all’arrivo di una chiamata per il gruppo stesso, per quanto tempo, in che ordine e quali azioni dovranno essere eseguite in caso di fallimento.
La configurazione di un IVR permette di stabilire l’albero dei nodi da attraversare, con quale input si passa da un nodo all’altro, quale messaggio deve essere mandato in play su ciascun nodo e quali azioni devono essere eseguite dai nodi stessi.
In generale, la configurazione delle entità conferisce loro un comportamento “statico” quando esse sono coinvolte all’interno di una chiamata. Tale comportamento rimane immutato fino al prossimo cambiamento di configurazione.

Regole di instradamento

All’arrivo di una chiamata, le regole di instradamento determinano quali entità di sistema svolgeranno il ruolo di chiamante e il chiamato per la chiamata stessa. Tale instradamento dipende dal numero chiamato, dall’ora di arrivo della chiamata e dal numero chiamante.

Gli strumenti di integrazione, nei limiti del possibile, permettono di ottenere dei flussi di chiamata dinamici, altrimenti non ottenibili con la sola configurazione delle entità e delle regole di instradamento.

Commutazione

La commutazione è il controllore di una chiamata audio video in
esecuzione sul PBX, in cui siano coinvolte due entità di sistema le
quali svolgono i ruoli di chiamante e chiamato (Fig. 1.4).

La commutazione riceve eventi dall’entità chiamante, li processa ed eventualmente invia comandi all’entità chiamata e viceversa.

Figura 1.4

Ogni entità di sistema gestisce N chiamate, ognuna delle quali fa capo al proprio controllore di chiamata (commutazione).
La figura 1.5 mostra l’entità B che ha in corso due chiamate:

la chiamata B1 con l’entità A controllata dalla commutazione 1
la chiamata B2 con l’entità C controllata dalla commutazione 2

Figura 1.5

Le chiamate A1, B1, B2, e C1 sono dette “entity calls” e sono identificate a loro volta da un “entity_call_id” univoco e generato al momento della creazione delle chiamate stesse.

Se paragoniamo una qualsiasi chiamata ad un’opera teatrale

Le entità di sistema sono gli attori che recitano lo spartito assegnato loro attraverso la configurazione.
Il controllore di chiamata, ossia la commutazione, è il regista che coordina la sceneggiatura utilizzando eventi e comandi dell’ interfaccia comune delle due entità coinvolte.
La sceneggiatura è l’esecuzione di una macchina a stati finiti dove la transizione da uno stato all’ altro è determinata dagli eventi chiamata ricevuti dalle entità coinvolte e dalle segnalazioni inviate alle stesse.
La proprietà “status" della commutazione rappresenta lo stato in cui si trova la commutazione stessa e assume valori in conformità al seguente diagramma di stato (Fig 1.6).

Figura 1.6

Strumenti di integrazione

In questo capitolo elencheremo quali sono gli strumenti di integrazione della piattaforma VOIspeed e come configurarli per poterli utilizzare nelle vostre applicazioni.

VOIspeed fornisce tre livelli di strumenti per l’integrazione (Fig. 2.1):

interfaccia livello utente
interfaccia livello esteso o di sistema
interfaccia livello IVR

Figura 2.1

Protocollo http\https

Ciascun livello di integrazione comunica con il mondo esterno
attraverso una interfaccia servizi ed eventi via protocollo
http\https.

Ciascun livello di integrazione è centrato sull’attività telefonica di un settore specifico della piattaforma VOIspeed.
Il livello utente, ad esempio, è focalizzato sull’attività degli interni del sistema.
Il livello IVR, invece, è sintonizzato sull’attività di uno o più risponditori automatici.
L’interfaccia estesa, infine, notifica eventi e mette a disposizione servizi relativi a tutte le entità della piattaforma VOIspeed da un punto di vista più generale (esteso).
Ciascun tipo di interfaccia è stata pensata per determinati scenari di integrazione che in seguito descriveremo in dettaglio.

Configurazione interfacce utente ed estesa
In questo paragrafo vedremo quali sono le configurazioni necessarie ad abilitare l’integrazione a livello utente e\o livello esteso.

Dal menù Configurazione selezionare la voce Azienda
Nella sezione Integrazione fate click sul pulsante Aggiungi integrazione
Nella finestra popup di Figura 2.2:
- Inserite il Nome dell’integrazione e Abilitatela.
- Nel menù a tendina Modulo di integrazione scegliere Generico.
- Nella sezione Eventi SSN selezionate gli eventi estesi di vostro interesse.
- Nella sezione Eventi utente selezionate gli eventi utente di vostro interesse.
- Nella sezione Utenti selezionare tutti gli interni per i quali desiderate ricevere notifica.
- Se, oltre che ricevere eventi, desiderate utilizzare i servizi del PBX, selezionate l’opzione Comandi abilitati. NOTA BENE abilitando i comandi, il sistema genererà una “token password” per vostro conto che dovrete inserire in tutte le richieste di servizio e che permetterà al sistema di riconoscere e autenticare velocemente la vostra applicazione.
- Fare click nel tasto OK e la vostra applicazione verrà salvata e sarà visibile nell’elenco delle integrazioni.
- Alla fine della riga corrispondente alla vostra applicazione trovate una serie di icone
  - Icona configura. Facendo click su questa icona si apre una finestra popup in cui dovrete inserire il vostro URL per le notifiche, ossia l’URL HTTP che il PBX invocherà per notificarvi gli eventi che avete configurato nei punti precedenti. All’URL da voi indicato verranno aggiunti i parametri che recheranno le informazioni associate all’evento stesso.
  - Icona mostra dettagli. Facendo click su questa icona verranno mostrati i dettagli della vostra applicazione; ne citiamo due importanti:
    - Il token password da inserire in tutte le richieste di servizio inviati dalla vostra applicazione
    - l’URL integrazione ossia l’url a cui dovete inviare le vostre richieste di servzio
  - Icona modifica. Facendo click su questa icona si apre l’interfaccia di configurazione del vostro modulo di integrazione in cui potete modificare eventi e utenti di vostro interesse e tutte le altre informazioni relative al modulo stesso.
  - Icona elimina. Facendo click su questa icona vi viene chiesto di confermare l’eliminazione del vostro modulo.

figura_2_2

Figura 2.2

Hello world
Ora che abbiamo configurato la nostra prima integrazione, proviamo che tutto funzioni e scriviamo la nostra prima applicazione “Hello world”.
In realtà il nostro “Hello world” non richiederà nessuna scrittura di codice; infatti utilizzando il nostro browser, invieremo il servizio call_request per creare una chiamata tra l’interno 35 e il numero esterno 187.

Nota Bene. Prima di iniziare assicuriamoci che nel vostro PBX esista un interno “35”, che questo interno abbia almeno un terminale SIP associato e che ci sia almeno un gateway e\o carrier voip che ci permetta di effettuare chiamate su rete pubblica.

Andate in Configurazione\Azienda\Integrazioni ed editate la vostra integrazione precedentemente creata
Per ora deselezionate tutti gli eventi SSN
Selezionate tutti gli eventi utente
Selezionate tra gli interni il “35”
Abilitate i comandi e prendete nota del token password associato alla vostra applicazione
Salvate le modifiche
Aprite la visualizzazione dettagli del vostro modulo di integrazione e prendete nota dell’ url di integrazione; supponiamo che esso sia seri1.cluana.com/PBX/seri_endpoint.php
Aprite il vostro browser e componete la seguente URL

http://seri1.cluana.com/PBX/seri_endpoint.php?service=call_request&token=vostro_token&ext=35&number=187

Se tutti i prerequisiti sono soddisfatti ed avete eseguito alla lettera quanto descritto, dovreste assistere alla nascita della chiamata tra l’interno 35 e il numero 187.
Complimenti! Avete impartito il vostro primo comando chiamata al PBX attraverso il modulo di integrazione che voi stessi avete creato e configurato.

Nei capitoli successivi analizzeremo tutti i servizi utente ed estesi descrivendone per ciascuno i relativi parametri, tuttavia ci soffermiamo fin d’ora a descriverne alcuni, prendendo per esempio proprio quello appena lanciato.

seri1.cluana.com/PBX/seri_endpoint.php è l’interfaccia per i servizi inegrati cui dovete sempre rivolgervi (SERI).
il parametro service specifica il servizio richiesto
il parametro token è la vostra password di accesso ai servizi integrati

Analizziamo ora cosa viene mostrato dal vostro browser al termine dell’esecuzione del comando

<?xml version="1.0" encoding="UTF-8" ?>
<result>
<outcome>0</outcome>
<request_id>15652770917203</request_id>
</result>

Risposta

Tutte le richieste di servizio generano una risposta XML incapsulata nel tag result all’interno del quale trovate il tag outcome il cui valore indica il successo o il fallimento del comando.

<outcome>0</outcome> indica che il comando è stato inviato con successo, ossia è stato preso in consegna dal PBX.
Il tag <request_id>15652770917203</request_id> contiene l’identificativo della richiesta.

In caso di fallimento del comando la risposta ottenuta sarà di questo tipo:

<?xml version="1.0" encoding="UTF-8" ?>
<result>
<outcome>1</outcome>
<error>connection not found</error></result>

Il tag <outcome>1</outcome> indica il fallimento.
Il tag <error> contiene la causa del fallimento.

Logger di eventi
Ora implementeremo un semplicissimo “Logger” di eventi su file in modo tale da verificare quanti e quali eventi arrivano relativamente ad una chiamata utente.
Prima di scrivere codice per il nostro applicativo, dobbiamo indicare alla piattaforma VOIspeed dove vogliamo ricevere gli eventi. Per fare questo è sufficiente fare click sull’icona Configura del vostro modulo di integrazione ed inserire l’URL per le notifiche (es http://mio_server/logger.php).

Eseguita la configurazione, create il file “logger.php”, copiateci il seguente codice, salvatelo e nel vostro server web.

<?php
	$params=$_SERVER['QUERY_STRING'];
	$file_handle = fopen('logger.txt','a');
	fwrite($file_handle,date(DATE_RSS).' '.$params."\r\n");
	fclose($file_handle);
?>

Abbiamo semplicemente scritto nel file la data_ora di arrivo dell’evento e la querystring dell’evento stesso.

A questo punto, tornate al vostro browser e lanciate di nuovo il comando call_request dell’applicazione Hello World; come in precedenza, dovreste vedere nascere una chiamata dal terminale SIP dell’interno “35” verso il numero 187, ascoltate l’audio dal terminale per qualche secondo e poi chiudete la chiamata dal terminale stesso.

Andate ora nel vostro server WEB e aprite il file “logger.txt” e se tutto è andato liscio, dovreste trovare tre eventi tutti relativi all’interno “35”:

event_type=2&event=9&event_name=outgoing_call&ext=35

event_type=2&event=14&event_name=call_answered&ext=35

event_type=2&event=16&event_name=call_disconnect_out&ext=35

Negli eventi registrati ci sono altri parametri che illustreremo in seguito, ma ora ci focalizzeremo su quelli mostrati sopra.

event_type indica se si tratta di un evento utente o esteso
- 1 = evento esteso (SSN)
- 2= evento utente
event codice dell’evento evento
event_name è il nome dell’evento
ext indica l’interno cui l’evento si riferisce

L’evento 9 “outgoing_call” indica che l’utente “35” ha chiamato il numero 187, presente nel parametro “number” non visualizzato.

L’evento 14 “call_answered” indica che la chiamata al 187 è stata accettata dal 187 stesso.

L’evento 16 “call_disconnect_out” indica che l’interno “35” ha terminato la chiamata.

Ricapitolando

Avete impartito un comando call_request con il quale avete creato una chiamata tra l’interno “35” e il numero “187”
Avete ricevuto eventi relativi alla chiamata che vi informavano sullo stato della stessa.

Integrazione utente

In questa sezione ci focalizzeremo sul livello utente che, come abbiamo già visto nel precedente capitolo, dispone di servizi ed eventi che elencheremo ed analizzeremo uno ad uno.
Capiremo quali servizi usare per fare una chiamata, metterla in attesa e riattivarla, inoltrarla e terminarla. Inoltre capiremo come recuperare le informazioni della chiamata dagli eventi utente, per poi utilizzarli come parametri di servizi chiamata.

Le richieste a servizio, come abbiamo visto nel piccolo esempio “Hello world”, sono delle “GET HTTP” che ottengono come risposta un XML contenente il tag “outcome”.

<?xml version="1.0" encoding="UTF-8" ?>
<result>
    <outcome>1</outcome>
    <error> error description </error>
</result>

Il tag <outcome> 1 </outcome> indica che la richiesta a servizio è stata rifiutata e il tag <error> contiene il motivo del fallimento.

<?xml version="1.0" encoding="UTF-8" ?>
<result>
    <outcome>0</outcome>
    <request_id> 56732980 </request_id>
</result>

Il tag <outcome> 0 </outcome, tuttavia, non significa che il comando è stato eseguito con successo, bensì che il sistema ha ricevuto la richiesta che verrà eseguita in un secondo momento.

L’esecuzione dei servizi richiesti è asincrona, ossia la richiesta viene esaminata e in caso di validazione viene restituito un request_id.
Al momento dell’effettiva esecuzione della richiesta, in caso di fallimento, verrà notificato al mittente, l’evento “comando fallito” contenente il parametro request_id, il cui valore è quello restituito al momento della richiesta.

Servizi utente

Servizio	Descrizione
call_request	esegue una chiamata
call_action	esegue una azione su di una chiamata
set_user_mode	imposta la modalità utente
get_user_call_report	richiede il report delle chiamate utente

Il parametro service deve essere inserito in tutte le richieste a servizio
per l’identificazione del servizio da erogare

Inoltre

Il parametro token deve essere inserito in tutte le richieste a servizio per l’identificazione ed autenticazione del mittente

Service “call_request”

Descrizione
Consente di effettuare una chiamata da un utente, specificato dal parametro “ext”, verso un numero, specificato dal parametro “number”. E’ altresì possibile specificare con quale terminale effettuare la chiamata e un identificativo esterno che poi verrà inserito in tutte le notifiche riguardanti la chiamata stessa.

Parametri:

service=call_request [obbligatorio]
token [obbligatorio] password di identificazione
ext [obbligatorio] indica l’interno che intende effettuare la chiamata
number [obbligatorio] indica il numero da chiamare
extid [opzionale] identificativo esterno
device [opzionale - default=sip] indica con quale terminale dell’utente effettuare la chiamata. I possibili valori sono:
- sip: specifica che si vuole usare il primo terminale SIP correntemente registrato
- mobile: indica che si vuole usare il telefono cellulare dell’interno
- id terminale: in alternativa alle precedenti opzioni, si può specificare un identificativo terminale se lo si conosce

Result

<result> 
    <outcome>0 = Ok \ 1 = KO </outcome>  
    <request_id> service request id </request_id> 
</result>

Esempi

URL?service=call_request&token=mio_token&ext=35&number=187&device=mobile

Service “call_action”

Descrizione
Consente di effettuare una azione su di una chiamata esistente, a patto che se ne conosca l’identificativo.
L’integratore può venire a conoscenza dell’identificativo chiamata intercettando le notifiche eventi chiamata utente.

Parametri:

service=call_action [obbligatorio]
token [obbligatorio] password di identificazione
ext [obbligatorio] indica l’interno che esegue l’azione
call_id[obbligatorio] è l’ “entity_call_id” ossia l’id della chiamata utente su cui eseguire l’azione
action [obbligatorio] indica quale azione deve essere eseguita sulla chiamata. I possibili valori sono:
- disconnect: termina la chiamata
- hold - mette in attesa la chiamata
- retrieve: riattiva la chiamata in attesa
- accept: accetta la chiamata entrante per l’utente
- rec_start: attiva la registrazione della chiamata
- rec_stop: termina la registrazione della chiamata
- switch : cambio terminale durante una chiamata
- divert: trasferimento della chiamata senza supervisione
- transfer : trasferimento della chiamata con supervisione
number - [obbligatorio per action=divert] indica il numero cui inoltrare la chiamata
note- [opzionale per action=divert] note dell’utente che inoltra la chiamata
device - [obbligatorio per action=switch] specifica il terminale
recipient_call_id - [obbligatorio per action=transfer] id della chiamata cui si intende trasferire la chiamata corrente (call_id).

Result

<result> 
    <outcome>0 = Ok \ 1 = KO </outcome>  
    <request_id> id richiesta servizio </request_id> 
</result>

Esempio divert

 URL?service=call_action&token=567897655&ext=35&call_id=3250&action=divert&number=39&note=mia_nota

Esempio disconnect

URL?service=call_action&token=567897655&ext=35&call_id=3250&action=disconnect

Service “set_user_mode”

Descrizione
Consente di impostare la modalità utente normale, non disturbare, assente e deviazione.

Parametri:

service=set_user_mode [obbligatorio]
token [obbligatorio] password di identificazione
ext [obbligatorio] interno per il quale si vuole impostare la modalità
mode[obbligatorio] modalità da impostare
- 0 = disponibile
- 1 = non disturbare
- 2 = assente

Result

<result> 
    <outcome>0 = Ok \ 1 = KO </outcome>  
    <request_id> service request id </request_id> 
</result>

Esempio set_user_mode

Imposta la modalità a non disturbare

URL?service=call_action&token=567897655&ext=35&mode=2

Service “get_user_call_report”

Descrizione
Recupera lo storico delle chiamate relative ad un utente del sistema, che
rispondano ad una serie di requisiti specificati dai parametri inseriti nella richiesta.
Lo storico verrà restituito in formato XML e ciascuna chiamata sarà inserita in un tag <call>..</call>.

Parametri:

service=get_user_call_report [obbligatorio]
token [obbligatorio] password di identificazione
ext [obbligatorio] interno per il quale si recupera lo storico chiamate
date_from[opzionale] limite inferiore per la data dello storico chiamate
- se omesso: tutte le chiamate senza limite inferiore di data
- formato: Y-m-d 00:00:00
date_to[opzionale] limite superiore per la data dello storico chiamate
- se omesso: tutte le chiamate senza limite superiore di data
- formato: Y-m-d 00:00:00
limit[opzionale] numero massimo di chiamate restituite
offset[opzionale] numero chiamata da cui partire per una nuova ricerca
callid[opzionale] id della chiamata -
- se omesso vengono recuperate tutte le chiamate
direction[opzionale] direzione della chiamata
- se omesso tutte le direzioni chiamata
- in: chiamate ricevute dall’utente
- out: chiamate effettuate dall’utente
number numero dell’interlocutore dell’utente
outcome esito della chiamata (Tabella 8 )

Result esito negativo

<result> 
    <outcome1</outcome>  
    <error> failure reason </error> 
</result>

Result esito positivo

<result>
	<outcome>0 </outcome>
    <call>
	    <id> autoincrement 
	    <callid> Id commutazione
	    <start_time> ora inizio chiamata
	    <answer_time> ora risposta chiamata
	    <duration> durata in secondi
        <outcome> esito (Appendici\Tabella 8)
	    ..
	    <direction> direzione della chiamata
	    <my_number> interno dell'utente
	    <remote_number> numero interlocutore
	    <local_id> entity_call_id
	    <group_name>nome gruppo di appartenenza
	    ...
	    <company>azienda contatto per “my_number”
	    <surname>cognome contatto per “my_number”
	    <name>nome contatto per “my_number”
	    <remote_company>azienda contatto per “remote_number”
	    <remote_surname>cognome contatto per “remote_number”
	    <remote_name> nome contatto per “remote_number” 
     <rec_file> nome del file risultante dalla registrazione della chiamata (se non è valorizzato, indica che la chiamata non è stata registrata)
    <call>
</result>

Eventi utente

Nel capitolo Strumenti di integrazione abbiamo visto come configurare un modulo di integrazione, nel quale avete specificato:

gli eventi utente di vostro interesse
gli utenti che volete monitorare
il vostro URL per le notifiche

Se avete configurato tutto correttamente, al verificarsi degli eventi che avete selezionato relativi agli utenti di vostro interesse, riceverete delle “notifiche” presso l’URL che avete indicato.

Tutti gli eventi utente conterranno sempre i seguenti parametri:

eventtype: il valore 2 indica che si tratta di un evento utente
event: codice evento (vedi tabella eventi)
event_name: nome evento (vedi tabella eventi)
token: il token associato al vostro modulo integrazione
domain: il nome del dominio VOIspeed cui l’evento si riferisce
license_id: licenza dell’installazione VOIspeed
ext: l’interno cui l’evento si riferisce

Evento	Codice	Descrizione
cmd_failed	1	Comando fallito
incoming_call	8	Chiamata in arrivo all’utente
outgoing_call	9	Chiamata fatta dall’utente
new_voicemail	10	Nuovo messaggio vocale per l’utente
lost_call	12	Nuova chiamata persa per l’utente
call_answered	14	Chiamata in conversazione
call_rejected	15	Chiamata rifiutata
call_disconnect_out	16	Chiamata terminata dall’utente
call_disconnect_in	17	Terminazione chiamata ricevuta
call_transfer	18	Chiamata trasferita

Nota bene
l’evento “call_transfer” (codice 18) non è stato ancora implementato.

Evento “cmd_failed”

Codice: 1

Descrizione
Supponiamo che abbiate effettuato una richiesta di servizio relativa ad un certo utente e che l’interfaccia servizi utente l’abbia validata e vi abbia restituito il “request_id”.
Qualora, durante l’esecuzione della richiesta, insorgesse un qualsiasi problema che renda impossibile l’erogazione del servizio dello stesso, viene notificato l’evento “cmd_failed”.

Parametri

request_id: id della richiesta fallita
command: nome comando fallito
command_id: codice comando fallito
call_id: id della chiamata utente cui era riferita la richiesta servizio
number: numero da chiamare (solo per il servizio “call_request”)

Evento “incoming_call”

Codice: 8

Descrizione
Questo evento notifica l’arrivo di una chiamata per l’interno “ext” da parte del numero “number”.

Parametri

ext: interno che sta ricevendo la chiamata
datetime: data e ora di arrivo della chiamata
usercallid: id della chiamata utente (da usare nel servizio “call_action”)
callid: id della commutazione
number: numero da cui arriva la chiamata
group: eventuale gruppo cui appartiene l’interno “ext”
name: nome del contatto associato a “number”
surname: cognome del contatto associato a “number”
company: azienda del contatto associato a “number”
external_contact_id: id del contatto della vostra rubrica

Evento “outgoing_call”

Codice: 9

Descrizione
Questo evento notifica che l’interno “ext” sta chiamando il numero “number”.
Parametri

ext: interno che sta effettuando la chiamata
datetime: data e ora di inizio chiamata
usercallid: id della chiamata utente (da usare nel servizio “call_action”)
callid: id della commutazione
number: numero chiamato
name: nome del contatto associato a “number”
surname: cognome del contatto associato a “number”
company: azienda del contatto associato a “number”
extid: id chiamata esterno, inserito da voi nel servizio “call_request”
external_contact_id: id del contatto della vostra rubrica

Evento “new_voicemail”

Codice: 10

Descrizione
Questo evento viene notificato quando c’è un nuovo messaggio vocale nella casella vocale di un utente.

Parametri

file: nome del file relativo al nuovo messaggio vocale
start_time: data ora di inizio del messaggio
end_time: data ora di fine del messaggio
number: numero della persona che ha lasciato il messaggio
name: nome della persona che ha lasciato il messaggio
surname: cognome della persona che ha lasciato il messaggio
company: azienda e/o reparto della persona che ha lasciato il messaggio

Evento “lost_call”

Codice: 12

Descrizione
Questo evento viene notificato quando c’è una nuova chiamata persa (non risposta) per un utente.

Parametri

ext: interno che ha una nuova chiamata persa
number: numero chiamante
name: nome del contatto associato al numero chiamante
surname: cognome del contatto associato al numero chiamante
company: azienda del contatto associato al numero chiamante
callid: id della commutazione
usercallid: id della chiamata utente (entity_call_id)

Evento “call_answered”

Codice: 14

Descrizione
Questo evento notifica che la chiamata tra l’interno “ext” e il numero “number” è stata accettata da uno dei due a seconda della direzione della chiamata. In generale, questo evento indica che la chiamata è transitata nel suo “stato attiva”, ossia l’interno “ext” e il numero “number” stanno parlando. Se vi interessa sapere chi ha fatto cosa allora dovreste tenere traccia della chiamata e salvarvi la direzione della stessa, attraverso gli eventi incoming_call e outgoing_call descritti precedentemente.

Parametri

ext: interno cui si riferisce l’evento
datetime: data e ora della risposta
usercallid: id della chiamata utente (da usare nel servizio “call_action”)
callid: id della commutazione
number: interlocutore dell’interno “ext” nella chiamata
name: nome del contatto associato a “number”
surname: cognome del contatto associato a “number”
company: azienda del contatto associato a “number”
external_contact_id: id del contatto della vostra rubrica

Evento “call_rejected”

Codice: 15

Descrizione
Questo evento notifica che la chiamata tra l’interno “ext” e il numero “number” è stata rifiutata dal “chiamato” chiunque dei due esso sia. In generale, questo evento indica che la chiamata tra l’interno “ext” e il numero “number” è “terminata” senza che i due abbiano parlato. Se vi interessa sapere chi era il chiamante e il chimato e di conseguenza chi ha rifiutato allora dovreste tenere traccia della chiamata e salvarvi la direzione della stessa, attraverso gli eventi incoming_call e outgoing_call descritti precedentemente.

Parametri

ext: interno cui si riferisce l’evento
datetime: data e ora della risposta
usercallid: id della chiamata utente (da usare nel servizio “call_action”)
callid: id della commutazione
number: interlocutore dell’interno “ext” nella chiamata
name: nome del contatto associato a “number”
surname: cognome del contatto associato a “number”
company: azienda del contatto associato a “number”
external_contact_id: id del contatto della vostra rubrica

Evento “call_disconnect_out”

Codice: 16

Descrizione
Questo evento notifica che l’interno “ext” ha chiuso la chiamata con il numero “number” dopo averci parlato.

Parametri

ext: interno che ha chiuso la chiamata
datetime: data e ora della disconnessione
usercallid: id della chiamata utente
callid: id della commutazione
number: interlocutore dell’interno “ext” nella chiamata
name: nome del contatto associato a “number”
surname: cognome del contatto associato a “number”
company: azienda del contatto associato a “number”
external_contact_id: id del contatto della vostra rubrica

Evento “call_disconnect_in”

Codice: 17

Descrizione
Questo evento notifica che l’interno “ext” ha subito la chiusura la chiamata dal numero “number” dopo averci parlato.

Parametri

ext: interno che ha ricevuto la chiusura della chiamata
datetime: data e ora della disconnessione
usercallid: id della chiamata utente
callid: id della commutazione
number: il numero che ha chiuso la chiamata con l’interno “ext”
name: nome del contatto associato a “number”
surname: cognome del contatto associato a “number”
company: azienda del contatto associato a “number”
external_contact_id: id del contatto della vostra rubrica

Integrazione Estesa

In questa sezione analizzeremo l’interfaccia di sviluppo “estesa” la quale, come l’interfaccia utente, dispone di servizi ed eventi che elencheremo ed analizzeremo uno ad uno.
Se l’interfaccia di integrazione utente mette al centro della sua attività l’entità utente, l’interfaccia estesa va oltre il concetto di utente e coinvolge trasversalmente tutte le entità di sistema.

L’interfaccia di integrazione estesa infatti permette operazioni generiche come:

Ottenere la lista delle entità di sistema
Gestire la rubrica aziendale
Ottenere il report delle chiamate
Ottenere la lista delle chiamate in corso

inoltre mette a disposizioni comandi per la gestione estesa delle chiamate:

creare una chiamata tra due entità di sistema (call_request_ext)
mettere in comunicazione una entità coinvolta in una chiamata con una seconda entità coinvolta in un’altra chiamata, disconnettendo i rispettivi interlocutori (call_transfer_ext)
sostituire una entità coinvolta in una chiamata con un’altra entità (call_divert_ext)
attivare la registrazione di una chiamata in corso (call_recording_ext)
abbattere una chiamata esistente (call_terminate)

Servizi estesi

Servizio	Descrizione
get_entities	lista entità
get_call_report	report delle chiamate
get_current_calls	lista delle chiamate correnti
add_phonebook	aggiunge un contatto alla rubrica
update_phonebook	aggiorna un contatto alla rubrica
delete_phonebook	elimina un contatto alla rubrica
get_phonebook	lista contatti della rubrica
call_request_ext	crea una chiamata tra due entità
call_transfer_ext	inoltro con supervisione esteso
call_divert_ext	deviazione chiamata estesa
call_recording_ext	attiva registrazione chiamata
call_terminate	abbatte la chiamata

Il parametro service deve essere inserito in tutte le richieste a servizio
per l’identificazione del servizio da erogare

Inoltre

Il parametro token deve essere inserito in tutte le richieste a servizio per l’identificazione ed autenticazione del mittente

Service “get_entities”

Descrizione

Restituisce una lista di entità specificate dai parametri entity_type e entity_id.
La lista restituita è in formato XML e i tag presenti sono funzione del tipo di entità richiesta.

Parametri:

service=get_entities (obbligatorio)
token: (obbligatorio) password di identificazione
entity_type: (obbligatorio) specifica il tipo di entità richiesta (Tabella 1)
entity_sub_type: (opzionale) ha senso solo se entity_type = gateway e specifica il tipo di gateway richiesto (Tabella 3)
entity_id: (opzionale) se omesso verrà restituita la lista delle entita “entity_type”
owner_id: (opzionale) identificativo del proprietario dell’entità richiesta
- se entity_type=7 (terminale) indica l’ID dell’utente per il quale si sta richiedendo la lista dei terminali
- se entity_type=8 (casella vocale aziendale) indica l’ID dell’utente responsabile della casella vocale

Result per entity_type=0 - Utente

Restituisce N tag ‘user’ all’interno del tag contenitore ‘users’, e ciascun tag utente contiene i campi informativi dell’entità utente:

 <result> 
    <outcome>0</outcome>  
        <user>
    	    <id> id utente </id> 
    	    <name> nome</name>
    	    <surname> cognome</surname> 
    	    <extension> interno </extension>
    	    <email> indirizzo email </email>
    	    <chat_status>(Appendici\Tabella 2)</chat_status>
    	    <av_status>(Appendici\Tabella 2)</av_status>
    	    <numoffice> numero ufficio </numoffice>
    	    <numhome> numero abitazione </numhome>
    	    <nummobile> numero mobile </nummobile>
    	    <numfax> numero fax </numfax>
    	    <phrase> descrizione stato utente </phrase>
    </user>
 </result>

in audio video call with

in chat with

Entity_A

Entity_B

Entity_C

Entity_D

Entity_X

Conference

Entity_Y

Entity_Z

Figura 1.1

Entity

Device

User

Group

Gateway

IVR

Figura 1.2

Ciascuna entità è definita da un identificativo (ID), univoco all’interno della sua categoria, e dalla categoria stessa (TYPE).

La tabella 1 elenca tutti i tipi di entità e relativi valori.

Le entità di sistema si dividono in entità atomiche ed entità
composte.

Group

User_1

User_N

Device_1.1

Device_1.M

Device_N.1

Device_N.K

Figura 1.3

Configurazione
Tutte le entità di sistema possono essere aggiunte, modificate ed eliminate dal configuratore WEB. In particolare:

Ciascuna entità di sistema può essere configurata secondo quanto
previsto dalla sua categoria di appartenenza.

La configurazione di un gruppo di squillo, ad esempio, riguarda quanti e quali utenti dovranno squillare all’arrivo di una chiamata per il gruppo stesso, per quanto tempo, in che ordine e quali azioni dovranno essere eseguite in caso di fallimento.
La configurazione di un IVR, permette di stabilire l’albero dei nodi da attraversare, con quale input si passa da un nodo all’altro, quale messaggio deve essere mandato in play su ciascun nodo e quali azioni devono essere eseguite dai nodi stessi.
In generale, la configurazione delle entità conferisce loro un comportamento “statico” quando esse sono coinvolte all’interno di una chiamata. Tale comportamento rimane immutato fino al prossimo cambiamento di configurazione.

Regole di instradamento

All’arrivo di una chiamata, le regole di instradamento determinano quali entità di sistema svolgeranno il ruolo di chiamante e il chiamato per la chiamata stessa. Tale instradamento dipende dal numero chiamato, dall’ora di arrivo della chiamata e dal numero chiamante.

Commutazione

La commutazione è il controllore di una chiamata audio video in
esecuzione sul PBX, in cui siano coinvolte due entità di sistema le
quali svolgono i ruoli di chiamante e chiamato (Fig. 1.4).

La commutazione riceve eventi dall’entità chiamante, li processa ed eventualmente invia comandi all’entità chiamata e viceversa.

receive events

send commands

receive events

send commands

Calling

Commutation

Called

Figura 1.4

Ogni entità di sistema gestisce N chiamate, ognuna delle quali fa capo al proprio controllore di chiamata (commutazione).
La figura 1.5 mostra l’entità B che ha in corso due chiamate:

la chiamata B1 con l’entità A controllata dalla commutazione 1
la chiamata B2 con l’entità C controllata dalla commutazione 2

Commutation_1

Entity_A

Call_A1

Entity_B

Commutation_2

Call_B1

Call_B2

Entity_C

Call_C1

Figura 1.5

Le chiamate A1, B1, B2, e C1 sono dette “entity calls” e sono identificate a loro volta da un “entity_call_id” univoco e generato al momento della creazione delle chiamate stesse.

Se paragoniamo una qualsiasi chiamata ad un’opera teatrale

Le entità di sistema sono gli attori che recitano lo spartito assegnato loro attraverso la configurazione.
Il controllore di chiamata, ossia la commutazione, è il regista che coordina la sceneggiatura utilizzando eventi e comandi dell’ interfaccia comune delle due entità coinvolte.
La sceneggiatura è l’esecuzione di una macchina a stati finiti dove la transizione da uno stato all’ altro è determinata dagli eventi chiamata ricevuti dalle entità coinvolte e dalle segnalazioni inviate alle stesse.
La proprietà “status" della commutazione rappresenta lo stato in cui si trova la commutazione stessa e assume valori in conformità al seguente diagramma di stato (Fig 1.6).

incoming call

outgoing call

call accept

call picking

call accept

call reject or cancell

call close

call divert

call accept

call picking

Inactive

Incoming

Calling

Active

Picking

Terminated

Diverting

Figura 1.6

Strumenti di integrazione

In questo capitolo elencheremo quali sono gli strumenti di integrazione della piattaforma Voispeed e come configurarli per poterli utilizzare nelle vostre applicazioni.

Voispeed fornisce tre livelli di strumenti per l’integrazione (Fig. 2.1):

interfaccia livello utente
interfaccia livello esteso o di sistema
interfaccia livello IVR

Integration

User Interface

IVR Interface

Extended Interface

Figura 2.1

Protocollo http\https

Ciascun livello di integrazione comunica con il mondo esterno
attraverso una interfaccia servizi ed eventi via protocollo
http\https.

Event notification

Service request

interface

Application

Ciascun livello di integrazione è centrato sull’attività telefonica di un settore specifico della piattaforma Voispeed.
Il livello utente, ad esempio, è focalizzato sull’attività degli interni del sistema.
Il livello IVR, invece, è sintonizzato sull’attività di uno o più risponditori automatici.
L’interfaccia estesa, infine, notifica eventi e mette a disposizione servizi relativi a tutte le entità della piattaforma Voispeed da un punto di vista più generale (esteso).
Ciascun tipo di interfaccia è stata pensata per determinati scenari di integrazione che in seguito descriveremo in dettaglio.

Configurazione interfacce utente ed estesa
In questo paragrafo vedremo quali sono le configurazioni necessarie ad abilitare l’integrazione a livello utente e\o livello esteso.

Dal menù Configurazione selezionare la voce Azienda
Nella sezione Integrazione fate click sul pulsante Aggiungi integrazione
Nella finestra popup di Figura 2.2 :
- Inserite il Nome dell’integrazione e Abilitatela.
- Nel menù a tendina Modulo di integrazione scegliere Generico.
- Nella sezione Eventi SSN selezionate gli eventi estesi di vostro interesse.
- Nella sezione Eventi utente selezionate gli eventi utente di vostro interesse.
- Nella sezione Utenti selezionare tutti gli interni per i quali desiderate ricevere notifica.
- Se, oltre che ricevere eventi, desiderate utilizzare i servizi del PBX, selezionate l’opzione Comandi abilitati. NOTA BENE abilitando i comandi, il sistema genererà una “token password” per vostro conto che dovrete inserire in tutte le richieste di servizio e che permetterà al sistema di riconoscere e autenticare velocemente la vostra applicazione.
- Fare click nel tasto OK e la vostra applicazione verrà salvata e sarà visibile nell’elenco delle integrazioni.
- Alla fine della riga corrispondente alla vostra applicazione trovate una serie di icone
  - Icona configura. Facendo click su questa icona si apre una finestra popup in cui dovrete inserire il vostro URL per le notifiche, ossia l’URL HTTP che il PBX invocherà per notificarvi gli eventi che avete configurato nei punti precedenti. All’URL da voi indicato verranno aggiunti i parametri che recheranno le informazioni associate all’evento stesso.
  - Icona mostra dettagli. Facendo click su questa icona verranno mostrati i dettagli della vostra applicazione; ne citiamo due importanti:
    - Il token password da inserire in tutte le richieste di servizio inviati dalla vostra applicazione
    - l’URL integrazione ossia l’url a cui dovete inviare le vostre richieste di servzio
  - Icona modifica. Facendo click su questa icona si apre l’interfaccia di configurazione del vostro modulo di integrazione in cui potete modificare eventi e utenti di vostro interesse e tutte le altre informazioni relative al modulo stesso.
  - Icona elimina. Facendo click su questa icona vi viene chiesto di confermare l’eliminazione del vostro modulo.

figura_2_2

Figura 2.2

Hello world
Ora che abbiamo configurato la nostra prima integrazione, proviamo che tutto funzioni e scriviamo la nostra prima applicazione “Hello world”.
In realtà il nostro “Hello world” non richiederà nessuna scrittura di codice; infatti utilizzando il nostro browser, invieremo il comando call_request per creare una chiamata tra l’interno 35 e il numero esterno 187.

Nota Bene. Prima di iniziare assicuriamoci che, nel vostro PBX, esista un interno “35”, che questo interno abbia almeno un terminale SIP associato, e che ci sia almeno un gateway e\o carrier voip che ci permetta di effettuare chiamate su rete pubblica.

Andate in Configurazione\Azienda\Integrazioni ed editate la vostra integrazione precedentemente creata
Per ora deselezionate tutti gli eventi SSN
Selezionate tutti gli eventi utente
Selezionate tra gli interni il “35”
Abilitate i comandi e prendete nota del token password associato alla vostra applicazione
Salvate le modifiche
Aprite la visualizzazione dettagli del vostro modulo di integrazione e prendete nota dell’ url di integrazione; supponiamo che esso sia seri1.cluana.com/PBX/seri_endpoint.php
Aprite il vostro browser e componete la seguente URL

http://seri1.cluana.com/PBX/seri_endpoint.php?service=call_request&token=vostro_token&ext=35&number=187

seri1.cluana.com/PBX/seri_endpoint.php è l’interfaccia per i servizi inegrati cui dovete sempre rivolgervi (SERI).
il parametro service specifica il servizio richiesto
il parametro token è la vostra password di accesso ai servizi integrati

Analizziamo ora cosa viene mostrato dal vostro browser al termine dell’esecuzione del comando

<?xml version="1.0" encoding="UTF-8" ?>
<result>
<outcome>0</outcome>
<request_id>15652770917203</request_id>
</result>

Risposta

Tutte le richieste di servizio generano una risposta XML incapsulata nel tag result all’interno del quale trovate il tag outcome il cui valore indica il successo o il fallimento del comando.

<outcome>0</outcome> indica che il comando è stato inviato con successo, ossia è stato preso in consegna dal PBX.
Il tag <request_id>15652770917203</request_id> contiene l’identificativo della richiesta.

In caso di fallimento del comando la risposta ottenuta sarà di questo tipo:

<?xml version="1.0" encoding="UTF-8" ?>
<result>
<outcome>1</outcome>
<error>connection not found</error></result>

Il tag <outcome>1</outcome> indica il fallimento.
Il tag <error> contiene la causa del fallimento.

Logger di eventi
Ora implementeremo un semplicissimo “Logger” di eventi su file in modo tale da verificare quanti e quali eventi arrivano relativamente ad una chiamata utente.
Prima di scrivere codice per il nostro applicativo, dobbiamo indicare alla piattaforma Voispeed dove vogliamo ricevere gli eventi. Per fare questo è sufficiente fare click sull’icona Configura del vostro modulo di integrazione ed inserire l’URL per le notifiche (es http://mio_server/logger.php).

Eseguita la configurazione, create il file “logger.php”, copiateci il seguente codice, salvatelo e nel vostro server web.

<?php
	$params=$_SERVER['QUERY_STRING'];
	$file_handle = fopen('logger.txt','a');
	fwrite($file_handle,date(DATE_RSS).' '.$params."\r\n");
	fclose($file_handle);
?>

Abbiamo semplicemente scritto nel file la data_ora di arrivo dell’evento e la querystring dell’evento stesso.

Andate ora nel vostro server WEB e aprite il file “logger.txt” e se tutto è andato liscio, dovreste trovare tre eventi tutti relativi all’interno “35”:

event_type=2&event=9&event_name=outgoing_call&ext=35

event_type=2&event=14&event_name=call_answered&ext=35

event_type=2&event=16&event_name=call_disconnect_out&ext=35

Nei eventi registrati ci sono altri parametri che illustreremo in seguito, ma ora ci focalizzeremo su quelli mostrati sopra.

event_type indica se si tratta di un evento utente o esteso
- 1 = evento esteso (SSN)
- 2= evento utente
event codice dell’evento evento
event_name è il nome dell’evento
ext indica l’interno cui l’evento si riferisce

L’evento 9 “outgoing_call” indica che l’utente “35” ha chiamato il numero 187, presente nel parametro “number” non visualizzato.

L’evento 14 “call_answered” indica che la chiamata al 187 è stata accettata dal 187 stesso.

L’evento 16 “call_disconnect_out” indica che l’interno “35” ha terminato la chiamata.

Ricapitolando

Avete impartito un comando call_request con il quale avete creato una chiamata tra l’interno “35” e il numero “187”
Avete ricevuto eventi relativi alla chiamata che vi informavano sullo stato della stessa.

AppServicesUsr 35Gateway35 call_request 187call 187call 187event outgoing_callevent outgoing_call187 Answered callevent call_answeredevent call_answeredcall_disconnectevent call_disconnect_outevent call_disconnect_outAppServicesUsr 35

Gateway

Integrazione utente

Le richieste a servizio, come abbiamo visto nel piccolo esempio “Hello world”, sono delle “GET HTTP” che ottengono come risposta un XML contenente il tag “outcome”.

<?xml version="1.0" encoding="UTF-8" ?>
<result>
    <outcome>1</outcome>
    <error> error description </error>
</result>

Il tag <outcome> 1 </outcome indica che la richiesta a servizio è stata rifiutata e il tag <error> contiene il motivo del fallimento.

<?xml version="1.0" encoding="UTF-8" ?>
<result>
    <outcome>0</outcome>
    <request_id> 56732980 </request_id>
</result>

Il tag <outcome> 0 </outcome, tuttavia, non significa che il comando è stato eseguito con successo, bensì che il sistema ha ricevuto la richiesta che verrà eseguita in un secondo momento.

L’esecuzione dei servizi richiesti è asincrona, ossia la richiesta viene esaminata e in caso di validazione viene restituito un request_id.
Al momento dell’effettiva esecuzione della richiesta, in caso di fallimento, verrà notificato al mittente, l’evento “comando fallito” contenente il parametro request_id, il cui valore è quello restituito al momento della richiesta.

AppServicesUserrequest (service)response (ok,request_id)exec (service)failure(service)notify (failure, request_id)AppServices

User

Servizi utente

Servizio

Descrizione

call_request

esegue una chiamata

call_action

esegue una azione su di una chiamata

set_user_mode

imposta la modalità utente

get_user_call_report

richiede il report delle chiamate utente

Il parametro service deve essere inserito in tutte le richieste a servizio
per l’identificazione del servizio da erogare

Inoltre

Il parametro token deve essere inserito in tutte le richieste a servizio per l’identificazione ed autenticazione del mittente

Service “call_request”

Descrizione
Consente di effettuare una chiamata da un utente, specificato dal parametro “ext”, verso un numero, specificato dal parametro “number”. E’ altresì possibile specificare con quale terminale effettuare la chiamata e un identificativo esterno che poi verrà inserito in tutte le notifiche riguardanti la chiamata stessa.

Parametri:

service=call_request [obbligatorio]
token [obbligatorio] password di identificazione
ext [obbligatorio] indica l’interno che intende effettuare la chiamata
number [obbligatorio] indica il numero da chiamare
extid [opzionale] identificativo esterno
device [opzionale - default=sip] indica con quale terminale dell’utente effettuare la chiamata. I possibili valori sono:
- sip: specifica che si vuole usare il primo terminale SIP correntemente registrato
- mobile: indica che si vuole usare il telefono cellulare dell’interno
- id terminale: in alternativa alle precedente opzioni, si può specificare un identificativo terminale se lo si conosce

Result

<result> 
    <outcome>0 = Ok \ 1 = KO </outcome>  
    <request_id> service request id </request_id> 
</result>

Esempi

URL?service=call_request&token=mio_token&ext=35&number=187&device=mobile

Service “call_action”

Parametri:

service=call_action [obbligatorio]
token [obbligatorio] password di identificazione
ext [obbligatorio] indica l’interno che esegue l’azione
call_id[obbligatorio] è l’ “entity_call_id” ossia l’id della chiamata utente su cui eseguire l’azione
action [obbligatorio] indica quale azione deve essere eseguita sulla chiamata. I possibili valori sono:
- disconnect: termina la chiamata
- hold - mette in attesa la chiamata
- retrieve: riattiva la chiamata in attesa
- accept: accetta la chiamata entrante per l’utente
- rec_start; attiva la registrazione chiamata
- rec_stop: termina la registrazione della chiamata
- switch : cambio terminale durante una chiamata
- divert: trasferimento della chiamata senza supervisione
- transfer : trasferimento della chiamata con supervisione
number - [obbligatorio per action=divert] indica il numero cui inoltrare la chiamata
note- [opzionale per action=divert] note dell’utente che inoltra la chiamata
device - [obbligatorio per action=switch] specifica il terminale
recipient_call_id - [obbligatorio per action=transfer] id della chiamata cui si intende trasferire la chiamata corrente (call_id).

Result

<result> 
    <outcome>0 = Ok \ 1 = KO </outcome>  
    <request_id> id richiesta servizio </request_id> 
</result>

Esempio divert

 URL?service=call_action&token=567897655&ext=35&call_id=3250&action=divert&number=39&note=mia_nota

Esempio disconnect

URL?service=call_action&token=567897655&ext=35&call_id=3250&action=disconnect

Service “set_user_mode”

Descrizione
Consente di impostare la modalità utente normale, non disturbare, assente e deviazione.

Parametri:

service=set_user_mode [obbligatorio]
token [obbligatorio] password di identificazione
ext [obbligatorio] interno per il quale si vuole impostare la modalità
mode[obbligatorio] modalità da impostare
- 0 = disponibile
- 1 = non disturbare
- 2 = assente

Result

<result> 
    <outcome>0 = Ok \ 1 = KO </outcome>  
    <request_id> service request id </request_id> 
</result>

Esempio set_user_mode

Imposta la modalità a non disturbare

URL?service=call_action&token=567897655&ext=35&mode=2

Service “get_user_call_report”

Parametri:

service=get_user_call_report [obbligatorio]
token [obbligatorio] password di identificazione
ext [obbligatorio] interno per il quale si recupera lo storico chiamate
date_from[opzionale] limite inferiore per la data dello storico chiamate
- se omesso: tutte le chiamate senza limite inferiore di data
- formato: Y-m-d 00:00:00
date_to[opzionale] limite superiore per la data dello storico chiamate
- se omesso: tutte le chiamate senza limite superiore di data
- formato: Y-m-d 00:00:00
limit[opzionale] numero massimo di chiamate restituite
offset[opzionale] numero chiamata da cui partire per una nuova ricerca
callid[opzionale] id della chiamata -
- se omesso vengono recuperate tutte le chiamate
direction[opzionale] direzione della chiamata
- se omesso tutte le direzioni chiamata
- in: chiamate ricevute dall’utente
- out: chiamate effettuate dall’utente
number numero dell’interlocutore dell’utente
outcome esito della chiamata (Tabella 8 )

Result esito negativo

<result> 
    <outcome1</outcome>  
    <error> failure reason </error> 
</result>

Result esito positivo

<result>
	<outcome>0 </outcome>
    <call>
	    <id> autoincrement 
	    <callid> Id commutazione
	    <start_time> ora inizio chiamata
	    <answer_time> ora risposta chiamata
	    <duration> durata in secondi
        <outcome> esito (Appendici\Tabella 8)
	    ..
	    <direction> direzione della chiamata
	    <my_number> interno dell'utente
	    <remote_number> numero interlocutore
	    <local_id> entity_call_id
	    <group_name>nome gruppo di appartenenza
	    ...
	    <company>azienda contatto per “my_number”
	    <surname>cognome contatto per “my_number”
	    <name>nome contatto per “my_number”
	    <remote_company>azienda contatto per “remote_number”
	    <remote_surname>cognome contatto per “remote_number”
	    <remote_name> nome contatto per “remote_number”
      <rec_file> nome del file risultante dalla registrazione della chiamata (se non è valorizzato, indica che la chiamata non è stata registrata)  
    <call>
</result>

Eventi utente

Nel capitolo Strumenti di integrazione abbiamo visto come configurare un modulo di integrazione, nel quale avete specificato:

gli eventi utente di vostro interesse
gli utenti che volete monitorare
il vostro URL per le notifiche

Tutti gli eventi utente conterranno sempre i seguenti parametri:

eventtype: il valore 2 indica che si tratta di un evento utente
event: codice evento (vedi tabella eventi)
event_name: nome evento (vedi tabella eventi)
token: il token associato al vostro modulo integrazione
domain: il nome del dominio Voispeed cui l’evento si riferisce
license_id: licenza dell’installazione Voispeed
ext: l’interno cui l’evento si riferisce

Evento

Codice

Descrizione

cmd_failed

Comando fallito

incoming_call

Chiamata in arrivo all’utente

outgoing_call

Chiamata fatta dall’utente

new_voicemail

Nuovo messaggio vocale per l’utente

lost_call

Nuova chiamata persa per l’utente

call_answered

Chiamata in conversazione

call_rejected

Chiamata rifiutata

call_disconnect_out

Chiamata terminata dall’utente

call_disconnect_in

Terminazione chiamata ricevuta

call_transfer

Chiamata trasferita

Nota bene
l’evento “call_transfer” (codice 18) non è stato ancora implementato.

Evento “cmd_failed”

Codice: 1

Descrizione
Supponiamo che abbiate effettuato una richiesta di servizio relativa ad un certo utente e che l’interfaccia servizi utente l’abbia validata e vi abbia restituito il “request_id”.
Qualora, durante l’esecuzione della richiesta, insorgesse un qualsiasi problema che rende impossibile l’erogazione del servizio del stesso, viene notificato l’evento “cmd_failed”.

Parametri

request_id: id della richiesta fallita
command: nome comando fallito
command_id: codice comando fallito
call_id: id della chiamata utente cui era riferita la richiesta servizio
number: numero da chiamare (solo per il servizio “call_request”)

Evento “incoming_call”

Codice: 8

Descrizione
Questo evento notifica l’arrivo di una chiamata per l’interno “ext” da parte del numero “number”.

Parametri

ext: interno che sta ricevendo la chiamata
datetime: data e ora di arrivo della chiamata
usercallid: id della chiamata utente (da usare nel servizio “call_action”)
callid: id della commutazione
number: numero da cui arriva la chiamata
group: eventuale gruppo cui appartiene l’interno “ext”
name: nome del contatto associato a “number”
surname: cognome del contatto associato a “number”
company: azienda del contatto associato a “number”
external_contact_id: id del contatto della vostra rubrica

Evento “outgoing_call”

Codice: 9

Descrizione
Questo evento notifica che l’interno “ext” sta chiamando il numero “number”.
Parametri

ext: interno che sta effettuando la chiamata
datetime: data e ora di inizio chiamata
usercallid: id della chiamata utente (da usare nel servizio “call_action”)
callid: id della commutazione
number: numero chiamato
name: nome del contatto associato a “number”
surname: cognome del contatto associato a “number”
company: azienda del contatto associato a “number”
extid: id chiamata esterno, inserito da voi nel servizio “call_request”
external_contact_id: id del contatto della vostra rubrica

Evento “new_voicemail”

Codice: 10

Descrizione
Questo evento viene notificato quando c’è un nuovo messaggio vocale nella casella vocale di un utente.

Parametri

file: nome del file relativo al nuovo messaggio vocale
start_time: data ora di inizio del messaggio
end_time: data ora di fine del messaggio
number: numero della persona che ha lasciato il messaggio
name: nome della persona che ha lasciato il messaggio
surname: cognome della persona che ha lasciato il messaggio
company: azienda e/o reparto della persona che ha lasciato il messaggio

Evento “lost_call”

Codice: 12

Descrizione
Questo evento viene notificato quando c’è un nuova chiamata persa (non risposta) per un utente.

Parametri

ext: interno che ha una nuova chiamata persa
number: numero chiamante
name: nome del contatto associato al numero chiamante
surname: cognome del contatto associato al numero chiamante
company: azienda del contatto associato al numero chiamante
callid: id della commutazione
usercallid: id della chiamata utente (entity_call_id)

Evento “call_answered”

Codice: 14

Parametri

ext: interno cui si riferisce l’evento
datetime: data e ora della risposta
usercallid: id della chiamata utente (da usare nel servizio “call_action”)
callid: id della commutazione
number: interlocutore dell’interno “ext” nella chiamata
name: nome del contatto associato a “number”
surname: cognome del contatto associato a “number”
company: azienda del contatto associato a “number”
external_contact_id: id del contatto della vostra rubrica

Evento “call_rejected”

Codice: 15

Parametri

ext: interno cui si riferisce l’evento
datetime: data e ora della risposta
usercallid: id della chiamata utente (da usare nel servizio “call_action”)
callid: id della commutazione
number: interlocutore dell’interno “ext” nella chiamata
name: nome del contatto associato a “number”
surname: cognome del contatto associato a “number”
company: azienda del contatto associato a “number”
external_contact_id: id del contatto della vostra rubrica

Evento “call_disconnect_out”

Codice: 16

Descrizione
Questo evento notifica che l’interno “ext” ha chiuso la chiamata con il numero “number” dopo averci parlato.

Parametri

ext: interno che ha chiuso la chiamata
datetime: data e ora della disconnessione
usercallid: id della chiamata utente
callid: id della commutazione
number: interlocutore dell’interno “ext” nella chiamata
name: nome del contatto associato a “number”
surname: cognome del contatto associato a “number”
company: azienda del contatto associato a “number”
external_contact_id: id del contatto della vostra rubrica

Evento “call_disconnect_in”

Codice: 17

Descrizione
Questo evento notifica che l’interno “ext” ha subito la chiusura la chiamata dal numero “number” dopo averci parlato.

Parametri

ext: interno che ha ricevuto la chiusura della chiamata
datetime: data e ora della disconnessione
usercallid: id della chiamata utente
callid: id della commutazione
number: il numero che ha chiuso la chiamata con l’interno “ext”
name: nome del contatto associato a “number”
surname: cognome del contatto associato a “number”
company: azienda del contatto associato a “number”
external_contact_id: id del contatto della vostra rubrica

Integrazione Estesa

L’interfaccia di integrazione estesa infatti permette operazioni generiche come:

Ottenere la lista delle entità di sistema
Gestire la rubrica aziendale
Ottenere il report delle chiamate
Ottenere la lista delle chiamate in corso

inoltre mette a disposizioni comandi per la gestione estesa delle chiamate:

creare una chiamata tra due entità di sistema (call_request_ext)
mettere in comunicazione una entità coinvolta in una chiamata con una seconda entità coinvolta in un’altra chiamata, disconnettendo i rispettivi interlocutori (call_transfer_ext)
sostituire una entità coinvolta in una chiamata con un’altra entità (call_divert_ext)
attivare la registrazione di una chiamata in corso (call_recording_ext)
abbattere una chiamata esistente (call_terminate)

Servizi estesi

Servizio

Descrizione

get_entities

lista entità

get_call_report

report delle chiamate

get_current_calls

lista delle chiamate correnti

add_phonebook

aggiunge un contatto alla rubrica

update_phonebook

aggiorna un contatto alla rubrica

delete_phonebook

elimina un contatto alla rubrica

get_phonebook

lista contatti della rubrica

call_request_ext

crea una chiamata tra due entità

call_transfer_ext

inoltro con supervisione esteso

call_divert_ext

deviazione chiamata estesa

call_recording_ext

attiva registrazione chiamata

call_terminate

abbatte la chiamata

Il parametro service deve essere inserito in tutte le richieste a servizio
per l’identificazione del servizio da erogare

Inoltre

Il parametro token deve essere inserito in tutte le richieste a servizio per l’identificazione ed autenticazione del mittente

Service “get_entities”

Descrizione

Restituisce una lista di entità specificate dai parametri entity_type e entity_id.
La lista restituita è in formato XML e i tag presenti sono funzione del tipo di entità richiesta.

Parametri:

service=get_entities (obbligatorio)
token: (obbligatorio) password di identificazione
entity_type: (obbligatorio) specifica il tipo di entità richiesta (Tabella 1)
entity_sub_type: (opzionale) ha senso solo se entity_type = gateway e specifica il tipo di gateway richiesto (Tabella 3)
entity_id: (opzionale) se omesso verrà restituita la lista delle entita “entity_type”
owner_id: (opzionale) identificativo del proprietario dell’entità richiesta
- se entity_type=7 (terminale) indica l’ID dell’utente per il quale si sta richiedendo la lista dei terminali
- se entity_type=8 (casella vocale aziendale) indica l’ID dell’utente responsabile della casella vocale

Result per entity_type=0 - Utente

Restituisce N tag ‘user’ all’interno del tag contenitore ‘users’, e ciascun tag utente contiene i campi informativi dell’entità utente:

 <result> 
    <outcome>0</outcome>  
	<users>
	        <user>
	    	    <id> id utente </id> 
	    	    <name> nome</name>
	    	    <surname> cognome</surname> 
	    	    <extension> interno </extension>
	    	    <email> indirizzo email </email>
	    	    <chat_status>(Appendici\Tabella 2)</chat_status>
	    	    <av_status>(Appendici\Tabella 2)</av_status>
	    	    <numoffice> numero ufficio </numoffice>
	    	    <numhome> numero abitazione </numhome>
	    	    <nummobile> numero mobile </nummobile>
	    	    <numfax> numero fax </numfax>
	    	    <phrase> descrizione stato utente </phrase>
	        </user>
	</users>
 </result>

Result per entity_type=1 - Gruppo di squillo
Restituisce N tag ‘group’ all’interno del tag contenitore ‘groups’.
Ciascun tag ‘group’ contiene i campi informativi del gruppo e un tag ‘users’ il quale a sua volta contiene M tag ‘user’ (membri del gruppo di squillo):

<result> 
   <outcome>0</outcome>
   <groups>	  
       <group>
   	    <id> id gruppo_1 </id> 
   	    <name> nome gruppo_1 </name>
   	    <is_broadcast> gruppo per annunci </is_broadcast> 
   	    <visible> visibile nella UI </visible>
   	    <member_login> run time login off/on </member_login>
   	    <pick_disabled> pick call vietata </pick_disabled>
   	    <ring_mode> Modalità di squillo (Appendici\Tabella 10)</ring_mode>
   	    <users>
	   	    <user>
		   	    <id> id utente_1 </id>
		   	    <identity> identità utente_1 </identity>
		   	    <extension>i nterno utente_1 </extension>
	   	    </user>
	   	    ...
		    <user>
		   	    <id> id utente_M </id>
		   	    <identity> identità utente_M </identity>
		   	    <extension>i nterno utente_M </extension>
	   	    </user>
   	    </users>
       </group>
       ....
       <group>
	   <id> id gruppo_N </id> 
   	   <name> nome gruppo_N </name>
   	   ....
       </group>
</groups>
</result>

Result per entity_type=2 - Gateway
Restituisce N tag ‘gateway’ all’interno del tag contenitore 'gateways’
Ciascun tag ‘gateway’ contiene i campi informativi del gateway:

<result> 
   <outcome>0</outcome>  
   <gateways>	       
       <gateway>
   	    <id> id gateway_1 </id> 
   	    <name> nome gateway_1 </name>
   	    <type> tipo gateway_1 (Appendici\Tabella 3) </type> 
   	    <enabled> abilitato </enabled>
   	    <link_status> stato registrazione (Appendici\Tabella 4)</link_status>
   	    <lines> numero linee totali </lines>
   	    <busy_lines> numero linee occupate</busy_lines>
   	    <host_port> IP e porta del gateway_1</host_port>	   	   
       </gateway>
       ....
       <gateway>
	   <id> id gateway_N </id> 
   	   <name> nome gateway_N </name>
   	   ....
      </gateway>
   </gateways>
</result>

Result per entity_type=3 - IVR
Restituisce N tag ‘ivr’ all’interno del tag contenitore ‘ivrs’.
Ciascun tag ‘ivr’ contiene i campi informativi dell’ivr e M tag node all’interno del tag contenitore nodes:

<result> 
   <outcome>0</outcome>  
   <ivrs>
     <ivr>
       <id> id ivr_1 </id> 
	   <name> nome ivr1_1 </name>
	   <description> descrizione ivr_1 </description>
	   <nodes>
	     <node>
   	       <node_id> id nodo_1 </node_id>
		   <parent_id> id nodo padre </parent_id>
		   <description> desc nodo_1 </description>
		   <select_key> chiave ingresso </select_key>
		   <go_back_key> chiave ritorno </go_back_key>
		   <audio_type> 1 (file_audio) </audio_type>
		   <audio_message> file audio del nodo </audio_message>
		   <audio_loop> 1=ciclo continuo - 0=una sola volta</audio_loop>
		   <input_type> tipo input (Appendici\Tabella 11) </input_type>
		   <input_length> (solo per input_type=1) lunghezza input attesa </input_length>
		   <term_char> (solo per input_type=2) carattere terminazione input </term_char>
		   <timeout_last_digit> (solo per input_type=3) tempo atteso da ultima cifra </timeout_last_digit>
		   <waiting_input_time> tempo massimo di attesa input </waiting_input_time>
		   <action> azione del nodo (Appendici\Tabella 12) </action>
		   <called_type> (Solo per action=2) Tipo entità da chiamare -  (Appendici\Tabella 1) </called_type>
		   <called_id> (Solo per action=2) ID entità da chiamare </called_id>
		   <called_external_number> (Solo per action=2) numero da chiamare</called_external_number>
		   <script> (Solo per action=3) script da eseguire </script>				   	    
		   ....
		   ....
		 <node>
		   <node_id> ID nodo_M </node_id>
		   ...
		   ...
		 </node>
	   <nodes>
   	 </ivr>
   	 ...
   	 ...
   	 <ivr>
	   <id> ID ivr N <id>
	   <name> nome ivr N </name>
	   ...
	   <nodes>
	     <node>
		   nodo 1.N
		 </node>
		 ....
		 ....
		 <node>
		   nodo M.N
		 </node>			   	    
	   </nodes>
   	 </ivr>	   	    
   </ivrs>
</result>

Result per entity_type=7 - Terminale

N.B. Questo comando restituisce i terminali di uno specifico utente pertanto è obbligatorio specificare il parametro ‘owner_id’. Omettere il parametro non significa ottenere la lista completa dei terminali bensì una lista nulla.

Restituisce N tag ‘device’ all’interno del tag contenitore ‘devices’, relativi all’utente il cui ID è stato specificato nel parametro ‘owner_id’.
Ciascun tag ‘gateways’ contiene i campi informativi del gateway:

<result> 
  <outcome>0</outcome>
  <devices>  
        <device>
	   	  <id> ID terminale_1 </id> 
	   	  <user_agent> user agent del terminale_1 </user_agent>
	   	  <device_type> tipo terminale_1 (Appendici\Tabella 5) </device_type> 
	   	  <host_port> IP e porta del terminale </host_port>
	   	  <registered> 1/0 - registrato/non_registrato </registered>
        </device>
        ....
	<device>
		  <id> ID device_N </id> 
	   	  ....
	   	  ....
	</device>
   </devices>
</result>

Result per entity_type=8 - Casella vocale aziendale
Restituisce N tag ‘voicemail’ all’interno del tag contenitore 'voicemails’
Ciascun tag ‘voicemail’ contiene i campi informativi della casella vocale aziendale:

<result>
	<voicemails>
	  <voicemail>
	    <id> ID casella vocale  </id>
	    <vmid> ID generale casella vocale aziendale </vmid>
	    <vmname> Nome casella vocale</vmname>
	    <vmcode> Numero da chiamare per accedere alla gestione della casella </vmcode>
	    <vmtobelisten>1/0 ci sono/non ci sono nuovi messaggi </vmtobelisten>
	    <rectobelisten>1/0 ci sono/non ci sono nuove registrazioni </rectobelisten>
	  </voicemail>
      .....
	  <voicemail>
	    <id> ID casella vocale  </id>
	    ....
	  </voicemail>	
	</voicemails>
</result>

Result per entity_type=11 - Linea parcheggio
Restituisce N tag ‘park_line’ all’interno del tag contenitore ‘lines’ '.
Ciascun tag ‘park_line’ contiene i campi informativi della linea parcheggio:

<result>
  <lines>
    <park_line>
      <id> ID linea parcheggio  </id>
      <linecode> codice accesso alla linea </linecode>
      <number> Numero parcheggiato </number>
      <name> Nome del contatto in rubrica </name>
      <parktime> data ora parcheggio YYYY-MM-DD hh:mm:ss</parktime>
      <status> Stato linea parcheggio (Appendici\Tabella 2) </status>
      <note> Nota dell'utente parcheggiante </note>
      <user_id> ID dell'utente parcheggiante <user_id>
    </park_line>
  </lines>
</result>

Service “get_call_report”

Descrizione

Il servizio get_call_report permette di recuperare lo storico delle chiamate transitate nel centralino, che rispondano ad una serie di requisiti specificati dai parametri inseriti nella richiesta.

Parametri:

service=get_call_report (obbligatorio)
token: (obbligatorio) password di identificazione
call_id: (opzionale) identificativo della chiamata
date_from: (opzionale) limite inferiore per la data dello storico chiamate
- se omesso si intende tutte le chiamate senza limite inferiore di data
- formato = YYYY-MM-DD hh:mm:ss
date_to: (opzionale) limite superiore per la data dello storico chiamate
- se omesso si intende tutte le chiamate senza limite superiore di data
- formato = YYYY-MM-DD hh:mm:ss
limit: (opzionale) numero massimo di chiamate restituite
offset: (opzionale) numero chiamata da cui partire per una nuova ricerca
calling_type: (opzionale) tipo entità chiamante (Appendici\Tabella 1)
calling_id: (opzionale) id entità chiamante
calling_number : (opzionale) numero chiamante
called_type: (opzionale) tipo entità chiamata (Appendici\Tabella 1)
called_id: (opzionale) id entità chiamata
called_number: (opzionale) numero chiamato
outcome: (opzionale) esito chiamata (Appendici\Tabella 8)
external_id: (opzionale) id generato da applicazione esterna con il comando call_req_ext

Result:

<result> 
  <outcome>0</outcome>  
  <call>
     <id> identificativo della chiamata</id>  
     <start_time> ora inizio chiamata </start_time>  
     <duration> durata della chiamata in secondi </duration>    	
     <outcome> esito della chiamata (Appendice\Tabella 8) </outcome>
     <calling_id> id dell’entità chiamante </calling_id
     <calling_type> tipo entità chiamante </calling_type>  
     <calling_number> numero chiamante </calling_number>  
     <called_id> id dell’entità chiamata </called_id>  
     <called_type> tipo entità chiamata </called_type>  
     <called_number> numero chiamata </called_number> 
     <connected_id> id ultima entità connessa </connected _id>  
     <connected _type> tipo ultima entità connesso </connected _type>
     <connected _number> ultimo numero connesso </connected _number>
     <ring_time> tempo in squillo in secondi</ring_time>  
     <hold_time> tempo in attesa in secondi </hold_time> 
     <ivr_time> tempo permanenza in IVR in secondi </ivr_time>  
     <talk_time> tempo effettivo conversazione </talk_time>  
     <queue_time> tempo in coda ad un gruppo </queue_time>  
     <call_ref_if> id chiamata della chiamata trasferita 
     </call_ref_id>  
     <external_id> id esterno specificato tramite servizio call_req_ext </external_id>
     <gateway_in> chiamata in uscita da gateway</gateway_in>
     <gateway_out>chiamata in ingresso da gateway</gateway_out>  
     <internal> chiamata tra interni </internal> 
   <call>
 </result>

Service “get_current_calls”

Descrizione

Il servizio get_current_calls permette di recuperare le chiamate in corso al momento della request.
La lista delle chiamate in corso verrà restituita in formato XML e ciascuna chiamata sarà inserita in un tag ‘call’.

Parametri:

service=get_current_calls (obbligatorio)
token: (obbligatorio) password di identificazione
call_id: (opzionale) identificativo dell’unica chiamata di interesse; omettendo questo parametro verrà restituita la lista di tutte le chiamate in corso.

Result:

<result> 
  <outcome>0</outcome>  
  <call>
     <id> identificativo della chiamata</id>  
     <start_time> ora inizio chiamata </start_time>  
     <calling_id> id dell’entità chiamante </calling_id
     <calling_type> tipo entità chiamante </calling_type>  
     <calling_number> numero chiamante </calling_number>  
     <calling_desc> identità del chiamante </calling_desc>  
     <called_id> id dell’entità chiamata </called_id>  
     <called_type> tipo entità chiamata </called_type>  
     <called_number> numero chiamata </called_number> 
     <called_desc> identità del chiamato </called_desc>  
     <connected_id> id entità connessa </connected _id>  
     <connected_type> tipo entità connesso </connected _type>
     <connected_desc> identità del connesso </connected_desc>
     <recording> 1/0 in registrazione</recording>  
     <external_id> id esterno </external_id>
     <p2p> 1/0 peer to peer attivo </p2p>
     <codec> codice codec corrente </codec>
   <call>
 </result>

Service “add_phonebook”

Descrizione

Il servizio add_phonebook permette allo sviluppatore esterno di inserire un contatto nella rubrica centralizzata del PBX VOIspeed.
Se il contatto viene inserito, viene restituito l’identificativo del contatto in VOIspeed.
In futuro sarà possibile eliminare e/o modificare il contatto utilizzando l’identificativo restituito.

Parametri:

service=add_phonebook (obbligatorio)
token: (obbligatorio) password di identificazione
name: nome contatto
surname: cognome contatto
company: azienda contatto
office: numero ufficio
home: numero abitazione
mobile: numero cellulare
fax: numero di fax
other: altro numero
email : indirizzo email
external_contact_id: id esterno del contatto

Result:

<result> 
    <outcome>0</outcome>
    <contact_id> ID del contatto </contact_id>
</result>

Service “update_phonebook”

Descrizione

Il servizio update_phonebook permette allo sviluppatore di modificare un contatto nella rubrica centralizzata del PBX Voispeed, identificato dal parametro contact_id.

Parametri:

service=update_phonebook (obbligatorio)
token: (obbligatorio) password di identificazione
name: nome contatto
contact_id: ID del contatto da modificare
surname: cognome contatto
company: azienda contatto
office: numero ufficio
home: numero abitazione
mobile: numero cellulare
fax: numero di fax
other: altro numero
email : indirizzo email
publicview: booleano (0/1), setta la visibilità pubblica del contatto - default 0 (=no)
publicedit: booleano (0/1), setta la possibilità di modifica pubblica del contatto - default 0 (=no)
external_contact_id: id esterno del contatto

Service “delete_phonebook”

Descrizione

Il servizio delete_phonebook permette allo sviluppatore di eliminare un contatto nella rubrica centralizzata del PBX Voispeed, identificato dal parametro contact_id.
Il comando in questione può essere utilizzato sia per cancellare contatti propri del centralino sia per cancellare contatti provenienti da una sincronizzazione con una rurbica esterna (tramite il comando phonebook_import_sync); nel primo caso andrà utilizzato con il parametro contact_id mentre, nel secondo caso, sarà necessario utilizzare la coppia app_name e external_contact_id.

Parametri:

service=delete_phonebook (obbligatorio)
token: (obbligatorio) password di identificazione
contact_id: (obbligatorio - alternativo alla coppia app_name e external_contact_id) ID del contatto da eliminare
app_name: (obbligatorio in coppia a external_contact_id - alternativo a contact_id) Applicazione proprietaria del contatto da eliminare
external_contact_id: (obbligatorio in coppia a app_name - alternativo a contact_id) ID di riferimento del contatto da eliminare nell’applicazione proprietaria

Service “get_phonebook”

Descrizione

Il servizio get_phonebook permette allo sviluppatore di recuperare una serie di contatti che abbiano una corrispondenza con il parametro di ricerca ‘search’. La ricerca avverrà nei campi (stringa) name, surname, company, email, office, home, mobile, fax e other.
Il servizio restituirà una lista di contatti in formato XML; ciascun contatto è contenuto nel tag .

Parametri:

service=get_phonebook (obbligatorio)
token: (obbligatorio) password di identificazione
search: (obbligatorio) valore da cercare nei vari del contatto
limit: (opzionale) numero massimo di rubrica restituiti
offset: id contatto da cui partire per una nuova ricerca

Result:

<contact>  
  <name> Nome del contatto </name>
  <surname> Cognome del contatto  </surname>
  <company> Azienda del contatto </company>
  <office> Numero dell’ufficio </office>
  <home> Numero dell’abitazione </home>
  <mobile> Numero del cellulare </mobile>
  <fax> Numero del fax </fax>
  <other> Altro numero </other>
  <email> Indirizzo posta elettronica </email>
  <is_favourite> 1\0 contatto preferito o meno </is_favourite>
</contact>

Service “call_request_ext”

Descrizione

Il servizio call_request_ext permette allo sviluppatore di chiamare una entità qualunque del sistema e, nel caso questa accetti la chiamata, di connetterla ad un’altra entità del sistema.

N.B. La prima entità chiamata svolge il ruolo di ‘calling’ mentre la seconda entità svolge il ruolo di ‘called’.

La figura seguente mostra la sequenza delle azioni e degli eventi estesi che scaturiscono dall’esecuzione del comando ‘call_request_ext’:

Parametri:

service=call_request_ext (obbligatorio)
token: (obbligatorio) password di identificazione
calling_id: (obbligatorio) id dell’entità chiamante
calling_type: (obbligatorio) tipo dell’entità chiamante (Appendici\Tabella 1)
calling_number: (obbligatorio) numero dell’entità chiamante
calling_timeout: (opzionale) - default=60 sec. - tempo massimo di attesa per la risposta dell’entità chiamante.
called_id: (obbligatorio) id dell’entità chiamata
called_type: (obbligatorio) tipo dell’entità chiamata (Appendici\Tabella 1)
called_number: (obbligatorio) numero dell’entità chiamata
extid: (opzionale) : identificativo esterno, ad uso dello sviluppatore, che verrà inserito negli eventi SSN e nei report delle chiamate
device: (opzionale) default=primo terminale sip - indica quale terminale deve essere usato qualora l’entità chiamante fosse un utente. Valori ammessi:
- sip
- mobile
- id del terminale se lo si conosce
to_be_rec: (opzionale) - default=0 - indica se la chiamata dovrà essere registrata o meno (valori 1\0)
auto_answer: (opzionale) - default=0 - permette di decidere se una delle entità coinvolte nella chiamata deve o meno rispondere automaticamente. Valori ammessi: Appendici\Tabella 13
swap_event: (opzionale) - default=0 - indica se gli eventi estesi relativi alla chiamata verso la prima entità devono essere scambiati o meno.
- swap_event=0 indica che nel momento della chiamata verso la prima entità dovrà essere sollevato l’evento ‘outgoing_call’
- swap_event=1 indica che:
  - nel momento della chiamata verso la prima entità non verrà sollevato nessun evento SSN
  - nel momento in cui la prima entità accetterà la chiamata verrà sollevato l’evento ‘incoming_call’, come se la chiamata fosse stata fatta attivamente dall’entità stessa.

N.B. il parametro auto_answer verrà considerato solo se riferito ad un utente e se il terminale scelto lo supporta, altrimenti verrà ignorato.

Result esito positivo

<result>  
  <outcome> 0 </outcome>    
  <request_id> request id </request_id>
</result>

Result esito negativo

<result>  
  <outcome> 1 </outcome>    
  <error> error description </error>
</result>

N.B. l’esito positivo significa che il servizio chiamata estesa sia stato erogato bensì che il PBX VOIspeed ha ricevuto la richiesta correttamente e validato il mittente. Il Servizio verrà erogato in modo asincrono in un secondo momento.

Service “call_transfer_ext”

Descrizione

II servizio call_transfer_ext (trasferimento esteso di chiamata) permette di sostituire una entità A connessa attraverso una commutazione COM_1, con una entità B connessa attraverso la commutazione COM_2.

La figura seguente mostra la situazione iniziale prima dell’esecuzione del servizio di trasferimento esteso di chiamata:

La figura seguente mostra la situazione finale dopo l’esecuzione del servizio di trasferimento esteso di chiamata:

L’esecuzione del servizio trasferimento esteso di chiamata avviene attraverso la seguente sequenza di operazioni:

terminazione della chiamata entity_call_A nella Commutazione_1
trasferimento della chiamata entity_call_B dalla Commutazione_2 alla Commutazion_1 sotituendo di fatto entity_call_A
abbattimento della Commutazione 2 e di conseguenza terminazione anche della chiamata entity_call_D

Parametri

service=call_request_ext (obbligatorio)
token: (obbligatorio) password di identificazione
replace_com_id: (obbligatorio) ID della commutazione (COM_1) in cui è presente l’entità A
replace_type: (obbligatorio) - tipo entità A da sostituire nella commutazione COM_1 - Appendici - Tabella 1
replace_id: (obbligatorio) - ID dell’entità A da sostituire nella commutazione COM_1
replace_call_id: (obbligatorio) entity_call_id dell’entità A nella commutazione COM_1 - Sezione Architettura VOIspeed - Figure 1.4 e 1.5)
recipient_com_id: (obbligatorio) - ID della commutazione COM_2 che contiene l’entita B intesa come entità di destinazione del trasferimento esteso.
recipient_type: (obbligatorio) tipo dell’entità B di destinazione - Appendici - Tabella 1
recipient_id: (obbligatorio) ID dell’entità B di destinazione
recipient_call_id: (obbligatorio) entity_call_id dell’entità B nella commutazione COM_2 - Sezione Architettura VOIspeed - Figure 1.4 e 1.5)

Service “call_divert_ext”

Descrizione

Supponiamo di avere una commutazione COM_1 in cui siano coinvolte l’entità_A e l’entità_B, come mostra la figura seguente:

II servizio call_divert_ext (deviazione estesa di chiamata) permette di sostituire l’entità_B con una terza entità C.

La figura seguente mostra la situazione finale dopo l’esecuzione del servizio:

L’esecuzione del servizio deviazione estesa di chiamata prevede le seguenti azioni:

abbattimento chiamata entity_call_B
notifica dell’evento evento esteso ‘disconnect_out’ relativo all’entità B
chiamata verso l’entità C con conseguente creazione di entity_call_C
notifica dell’evento evento esteso ‘call_out’ relativo all’entità C
all’arrivo di un ‘call_progress’ da parte di C, viene fatto sentire un tono di libero sintetico all’entità_A
notifica dell’evento ‘call_progress’ relativamente all’entità C

Parametri

service=call_divert_ext (obbligatorio)
token: (obbligatorio) password di identificazione
com_id: (obbligatorio) ID della commutazione COM_1 dove eseguire la deviazione estesa della chiamata
replace_type: (obbligatorio) - tipo entità B da sostituire nella commutazione COM_1 - Appendici - Tabella 1
replace_id: (obbligatorio) - ID dell’entità B da sostituire nella commutazione COM_1
replace_call_id: (obbligatorio) entity_call_id dell’entità B nella commutazione COM_1 - Sezione Architettura VOIspeed - Figure 1.4 e 1.5)
recipient_type: (obbligatorio) - tipo entità C che rimpiazzerà l’entità B nella commutazione COM_1 - Appendici - Tabella 1
recipient_id: (obbligatorio) - ID dell’entità C
recipient_number: (opzionale) numero associato all’entità C di destinazione

Service “call_recording_ext”

Descrizione

Il servizio attiva\disattiva la registrazione della commutazione identificata dal valore del parametro call_id.

Parametri

service=call_recording_ext (obbligatorio)
token: (obbligatorio) password di identificazione
call_id: (obbligatorio) ID della commutazione su cui attivare\disattivare la registrazione
enabled: (obbligatorio) 1\0 attiva disattiva registrazione.

Service “call_terminate”

Descrizione

Il servizio abbatte la commutazione con conseguente disconnessione delle due entità coinvolte.

Parametri

service=call_terminate (obbligatorio)
token: (obbligatorio) password di identificazione
call_id: (obbligatorio) ID della commutazione da abbattere

Eventi estesi

Nel capitolo Strumenti di integrazione abbiamo visto come configurare un modulo di integrazione, nel quale avete specificato:

gli eventi estesi (SSN) di vostro interesse
il vostro URL per le notifiche

Se avete configurato tutto correttamente, al verificarsi degli eventi che avete selezionato, riceverete delle “notifiche” presso l’URL che avete indicato.

Prima di iniziare la trattazione sugli eventi è opportuno fare una importante precisazione relativamente alla “direzione” degli eventi.

N.B. Gli eventi estesi, a differenza degli eventi utente che hanno l’utente
stesso come oggetto degli eventi, hanno come punto di vista degli
eventi il PBX. L’evento esteso ‘call_in’ sta a significare
che è arrivata al PBX una richiesta di chiamata da parte di una entità
di sistema, mentre l’evento esteso ‘call_out’ significa che dal
PBX è partita una indicazione di chiamata verso una entità di sistema.

Tutti gli eventi sistema (SSN) conterranno sempre i seguenti parametri:

eventtype: il valore 1 indica che si tratta di un evento di sistema
event: codice evento (vedi tabella eventi)
event_name: nome evento (vedi tabella eventi)
token: il token associato al vostro modulo integrazione se avete abilitato i comandi, altrimenti il vaore sarà nullo.
domain: il nome del dominio VOIspeed cui l’evento si riferisce
license_id: licenza dell’installazione VOIspeed
datetime: data ora dell’evento
call_id: ID della commutazione cui si riferisce l’evento
call_id_ext: eventuale ID esterno, qualora fosse stato inserito tra i parametri del servizio '*call_request_ext*’
call_status: stato della commutazione (Appendici - Tabella 9)

Evento	Codice	Descrizione
call_in	1	Chiamata in arrivo da entità
call_progress	2	Chiamata in progress da entità chiamata
call_out	3	Chiamata verso entità
call_response	4	Risposta chiamata (positiva\negativa) da entità
disconnect_in	5	Terminazione chiamata inviata ad entità
disconnect_out	6	Terminazione chiamata ricevuta da entità
call_transfer	7	Chiamata trasferita (inoltro con supervisione)
dtmf_out	8	Evento obsoleto - dismesso
call_divert	9	Chiamata deviata (inoltro cieco)
call_terminated	10	Chiamata terminata
call_held	11	Chiamata messa in attesa da entità
call_retrieved	12	Chiamata attivata (dopo attesa) da entità

Evento “call_in”

Codice: 1

Descrizione

Notifica l’arrivo di una chiamata dal numero ‘calling’ al numero ‘called’ da parte dall’entità individuata dalle coordinate (calling_id, calling_type)

Parametri

calling: numero chiamante
calling_id: ID dell’entità chiamante
calling_type: tipo dell’entità chiamante (Appendici - Tabella 1)
called: numero chiamato

Evento “call_progress”

Codice: 2

Descrizione

Notifica l’arrivo di una segnalazione di chiamata in progress da parte dell’entità specificata dalle coordinate (sender_id, sender_type)

Parametri

sender_id: ID dell’entità che ha inviato la segnalazione di avanzamento chiamata
sender_type: tipo dell’entità che ha inviato la segnalazione di avanzamento chiamata (Appendici - Tabella 1)
progress-code: codice avanzamento chiamata (Appendici - Tabella 14)

Evento “call_out”

Codice: 3

Descrizione

Notifica una chiamata in uscita dal PBX verso l’entità specificata dalle coordinate (called_id, called_type) da parte del numero ‘calling’ per il numero ‘called’

Parametri

calling: numero chiamante
called: numero chiamato
called_id: ID dell’entità cui è stata inviata la chiamata
called_type: tipo dell’entità cui è stata inviata la chiamata (Appendici - Tabella 1)

Evento “call_response”

Codice: 4

Descrizione

Notifica che l’entità identificata dalle coordinate (sender_id, sender_type) ha inviato la risposta definitiva ad una chiamata ad essa inviata. Il parametro ‘outcome’ indica se la chiamata è stata accettata o rifiutata e in tal caso con quale esito.
Solo nel caso di chiamata accettata (esito OK), seguono una serie di parametri che notificano chi sono attualmente gli “attori” della chiamata: vengono notificate le coordinate delle entità ‘calling’, ‘called’ e ‘connected’.

N.B. In ogni chiamata, oltre alle entità ‘calling’ e ‘called’, esiste sempre l’entità connected.
L’entità connessa può coincidere con una delle due entità calling e called nel caso esse siano entità semplici, o non coincidere qualora una delle due sia una entità composta.
Ad esempio se l’entità chiamata è un gruppo di squillo, l’entità connessa è l’utente del gruppo che ha accettato la chiamata.

Parametri

sender_id: ID dell’entità che ha inviato la segnalazione di risposta chiamata
sender_type: tipo dell’entità che ha inviato la segnalazione di risposta chiamata (Appendici - Tabella 1)
outcome: esito della risposta chiamata - (Appendici - Tabella 8)
calling_id: ID dell’entità ‘calling’ al momento della risposta chiamata
calling_type: tipo dell’entità ‘calling’ al momento della risposta chiamata (Appendici - Tabella 1)
calling_local_id: si tratta dell’entity_call_id relativo alla entità ‘calling’
called_id: ID dell’entità ‘called’ al momento della risposta chiamata
called_type: tipo dell’entità ‘called’ al momento della risposta chiamata (Appendici - Tabella 1)
called_local_id: si tratta dell’entity_call_id relativo alla entità ‘called’
connected_id: ID dell’entità ‘connected’
connected_type: tipo dell’entità ‘connected’ al momento della risposta chiamata (Appendici - Tabella 1)
reject-code: solo in caso di esito negativo - codice SIP di rifiuto chiamata chiamata (Appendici - Tabella 14)

Evento “disconnect_in”

Codice: 5

Descrizione

Notifica l’arrivo al PBX di una segnalazione di terminazione chiamata da parte dell’entità identificata dalle coordinate (sender_id, sender_type).

Parametri

sender_id: ID dell’entità che ha inviato la segnalazione di terminazione chiamata
sender_type: tipo dell’entità che ha inviato la segnalazione di terminazione chiamata (Appendici - Tabella 1)

Evento “disconnect_out”

Codice: 5

Descrizione

Notifica PBX da parte del PBX di una segnalazione di terminazione chiamata all’entità identificata dalle coordinate (recipient_id, recipient_type).

Parametri

recipient_id: ID dell’entità di destinazione della segnalazione di terminazione chiamata
recipient_type: tipo dell’entità di destinazione della segnalazione di terminazione chiamata (Appendici - Tabella 1)

Evento “call_transfer”

Codice: 7

Descrizione

Notifica un trasferimento di chiamata dall’entità di coordinate (sender_id, sender_type) della commutazione ‘call_id’, all’entità (recipient_id, recipient_type) della commutazione ‘refer_id’.

N.B. Alla fine del trasferimento l’entità ‘recipient’ verrà inserita nella commutazione dell’entità trasferente, al posto
dell’entità trasferente stessa. La commutazione ‘refer_id’ verrà
abbattuta.

Parametri

call_id: ID della commutazione cui appartiene l’entità trasferente
sender_id: ID dell’entità trasferente
sender_type: tipo dell’entità trasferente (Appendici - Tabella 1)
refer_id: ID della commutazione dove risiede l destinatario del trasferimento
recipient_id: ID dell’entità destinataria del trasferimento
recipient_type: tipo dell’entità di destinazione del trasferimento (Appendici - Tabella 1)

Evento “call_divert”

Codice: 9

Descrizione

Notifica la deviazione di chiamata dall’entità (sender_id, sender_type) della commutazione ‘call_id’, all’entità (recipient_id, recipient_type) della commutazione.

N.B. Alla fine della deviazione, l’entità ‘recipient’ verrà inserita nella commutazione al posto dell’entità ‘sender’ stessa.
L’entità di destinazione ‘recipient’ si trova nello stato di ‘squillo’.

Parametri

call_id: ID della commutazione cui appartiene l’entità trasferente
sender_id: ID dell’entità mittente, che verrà rimpiazzata dall’entità recipient
sender_type: tipo dell’entità mittente (Appendici - Tabella 1)
recipient_id: ID dell’entità destinataria ‘recipient’ della deviazione chiamata; essa prenderà il posto dell’entità mittente ‘sender’
recipient_type: tipo dell’entità di destinazione (Appendici - Tabella 1)

Evento “call_terminated”

Codice: 10

Descrizione

Notifica la terminazione della commutazione identificata dal parametro ‘call_id’. Il parametro ‘outcome’ definisce l’esito finale della chiamata.

Parametri

outcome: esito finale della chiamata (Appendici - Tabella 8)

Evento “call_held”

Codice: 11

Descrizione

Notifica la messa in ‘attesa’ della chiamata da parte dell’utente specificato dal parametro ‘user_id’; il tipo entità è sottinteso (utente).

Parametri

user_id: ID dell’utente che ha messo in attesa la chiamata
user_call_id: ID della chiamata utente (entity_call_id) messa in attesa.

Evento “call_retrieved”

Codice: 12

Descrizione

Notifica il recupero della chiamata dall’attesa da parte dell’utente specificato dal parametro ‘user_id’; il tipo entità è sottinteso (utente).

Parametri

user_id: ID dell’utente che ha riattivato la chiamata
user_call_id: ID della chiamata utente (entity_call_id) riattivata.

Esempio: Predictive dialer

In questa sezione descriveremo quali servizi e quali eventi utilizzare per implementare un semplice predictive dialer.
Un predictive dialer è un software che preleva N numeri da una base dati, li chiama tutti simultaneamente e per ogni chiamata accettata cerca di mettere in comunicazione l’interlocutore con un operatore attualmente libero.

N.B. In questo esempio non scriveremo codice, bensì richiederemo
l’esecuzione di determinati servizi attraverso il nostro browser,
recuperando i parametri da allegare alle richieste da un semplice
logger di eventi su file di testo.

Passo 1 - Abilitare comandi ed eventi estesi (SSN)

Editate il modulo di integrazione che avete creato in precedenza
Abilitate i comandi e prendete nota del “token” assegnatovi
Abilitate tutti gli eventi SSN
Disabilitate tutti gli eventi utente (per semplicità).
Inserite nella URL per le notifiche l’URL del vostro server WEB in modo tale che punti allo script “logger.php” (vedi “Logger di eventi” nel capitolo “Strumenti di integrazione”)

Passo 2 - Configurazione IVR di accoglienza
Il primo passo da eseguire è quello di creare e configurare un nuovo risponditore automatico cui collegare i numeri esterni quando questi accettano la chiamata.

Creare un nuovo IVR e chiamatelo ‘Accoglienza’
Editate l’IVR appena creato e prendete nota del suo ID nella sezione “Informazioni generali”.
Creare un nodo radice dell’IVR e configuratelo come segue:
- selezionare un messaggio del nodo che mandi in play un rumore di fondo o un qualsiasi altro messaggio di benvenuto.
- Impostate “Loop messaggio audio” a “SI”
- Impostate “Tipologia input” a “Non richiesto”
- Impostate “Azione del nodo” a “Nessuna”

Passo 3 - Configurazione IVR attesa-operatore
Creare e configurare un nuovo risponditore automatico cui collegare gli operatori “disponibili” in attesa di connetterli con un numero esterno.

Creare un nuovo IVR e chiamatelo ‘Attesa operatore’
Editate l’IVR appena creato e prendete nota del suo ID nella sezione “Informazioni generali”.
Creare un nodo radice dell’IVR e configuratelo come segue:
- selezionare un messaggio del nodo che mandi in play un un messaggio che indichi all’operatore che sta per essere connesso con un numero esterno.
- Impostate “Loop messaggio audio” a “SI”
- Impostate “Tipologia input” a “Non richiesto”
- Impostate “Azione del nodo” a “Nessuna”

Passo 4 - Ricerca gateway disponibili
Useremo il servizio “get_entities” per ottenere la lista dei gateway e valutarne il numero di linee libere.

Aprire il browser e lanciate il seguente l’URL utilizzando l’URL associato al vostro dominio e il token del vostro modulo di integrazione

 SERI_URL?service=get_entities&entity_type=2&token=mio_token

… e otterrete la lista dei gateway della vostra azienda.
Nel nostro esempio scegliete un gateway con linee libere e prendete nota del suo ID, nel caso generale, invece, per ogni gateway dovreste salvarvi l’ID e il numero di linee libere.

N.B. In questo esempio chiameremo un solo numero esterno e lo collegheremo con un solo utente; tuttavia l’operazione può essere
automatizzata e scalata ad N numeri esterni.

Passo 5 - Ricerca numeri da chiamare
Cercare nel vostro database dei contatti, tutti quelli ancora da chiamare in numero pari al numero di linee libere che avete recuperato al passo 4.
Nel nostro esempio, il numero sarà uno solo e sceglietelo in modo tale che esista e sia raggiungibile.

Passo 6 - Ricerca utenti disponibile
Anche in questo caso, come nel passo 4, useremo il servizio “get_entities” selezionando il tipo “utente”

SERI_URL?service=get_entities&entity_type=0&token=mio_token

… e otterrete la lista degli utenti della vostra azienda.
Nel nostro esempio scegliete un utente “disponibile” per la chiamata (av_status=2) - vedi Appendici Tabella 2) e prendete nota del suo ID che chiameremo “user_id”.
Nel caso generale scegliete un numero M di utenti “disponibili” e per ciascuno memorizzate l’ID utente.

Passo 8 - Lancio chiamate ai numeri esterni
Lanciamo la chiamata al numero esterno scelto al passo 5 utilizzando il “gateway” selezionato al passo 4 e connettiamolo all’IVR “Accoglienza” usando il servizio “call_request_ext” come segue:

SERI_URL?service=call_request_ext&token=MIO_TOKEN
&calling_id=ID_GATEWAY&calling_type=2
&calling_number=NUMERO_ESTERNO
&called_id=ID_IVR_ACCOGLIENZA
&called_type=3
&called_number=VOSTRO_NUMERO_AZIENDALE
&extid=VOSTRO_IDENTIFICATIVO_CHIAMATA

N.B. Il parametro “extid” verrà inserito in tutti gli eventi SSN relativi a questa chiamata; potete usare questo valore, da voi
generato, per associare ogni evento chiamata ricevuto alla relativa
“call_request_ext” che ha generato la chiamata stessa.

Nel caso generale, ossia nel caso in cui abbiamo sviluppato un software di “predictive dialing”, dovremmo lanciare tante chiamate con il servizio “call_request_ext” quante sono le linee libere dei Gateway (passo 4).

Passo 9 - Lancio chiamate verso operatori
Subito dopo aver lanciato la chiamata al numero esterno (passo 8), lanciamo una chiamata all’operatore scelto al passo 6. Anche in questo caso usiamo il servizio “call_request_ext” per connettere l’operatore scelto all’IVR “Attesa-operatore” configurato al passo 3.

SERI_URL?service=call_request_ext&token=MIO_TOKEN
&calling_id=ID_OPERATORE&calling_type=0
&calling_number=NUMERO_ESTERNO
&called_id=ID_IVR_ATTESA_OPERATORE
&called_type=3
&called_number=INTERNO_OPERATORE
&extid=VOSTRO_IDENTIFICATIVO_CHIAMATA
&auto_answer=1

N.B. il parametro “auto_answer” impostato ad 1 sta ad indicare che all’entità “chiamante”, ossia l’operatore scelto, è richiesta la
risposta automatica, qualora il suo terminale la supporti.
Si consiglia di usare la risposta automatica per accorciare il più possibile i tempi di connessione tra l’operatore scelto e l’IVR “Attesa-operatore”.

Con i passi 8 e 9 abbiamo lanciato due chiamate:

la prima commutazione COM_1 per connettere un numero esterno con l’IVR accoglienza con ID commutazione ID_COM_1.
la seconda commutazione per connettere l’operatore con un l’IVR Attesa-operatore con ID commutazione ID_COM_2.

A questo punto non ci resta che attendere gli eventi SSN che derivano dalle due chiamate in questione e recuperare i dati che ci servono dal “logger” degli eventi di cui al passo 1.

Per la prima chiamata riceveremo gli eventi:

1.A - call_out (codice: 3) ossia chiamata verso il gateway scelto
1.B - call_response (codice = 4) ossia chiamata accettata dal numero esterno
1.C - call_out (codice: 3) chiamata verso l’IVR Accoglienza
1.D - call_response (codice = 4) chiamata accettata dall’IVR Accoglienza

Per la seconda chiamata riceveremo gli eventi:

2.A - call_out (codice: 3) ossia chiamata verso l’ operatore scelto
2.B - call_response (codice = 4) ossia chiamata accettata dall’ operatore
2.C - call_out (codice: 3) chiamata verso l’IVR Attesa-operatore
2.D - call_response (codice = 4) chiamata accettata dall’IVR Attesa-operatore

Passo 10 - Interconnessione “numero esterno” - operatore
L’obiettivo finale è quello di avere una sola commutazione che interconnetta il numero esterno con l’operatore e contemporaneamente disconnetta i due IVR che abbiamo usato come “appoggio”.
Il servizio “call_transfer_ext” fà al nostro caso; infatti esso ci consente di sostituire l’IVR Accoglienza nella commutazione COM_1 con l’operatore della commutazione COM_2.
Per fare questo è necessario aprire il “logger” degli eventi e prendere nota dei seguenti dati:

ID_COM_1 estratto dal parametro “call_id” da uno qualsiasi degli eventi della prima commutazione (1.A - 1.B - 1.C - 1.D).
ID_COM_2 estratto dal parametro “call_id” da uno qualsiasi degli eventi della seconda commutazione (2.A - 2.B - 2.C - 2.D).
IVR_CALL_ID estratto dal parametro “called_local_id” dell’evento 1.D.
OPERATOR_CALL_ID estratto dal parametro “calling_local_id” dell’evento 2.B.

Inoltre chiameremo:

IVR_ID l’ID dell’IVR Accoglienza della commutazione com_1
OPERATOR_ID l’ID dell’operatore (utente)

Infine, da Appendici - Tabella1, sappiamo che:

USER_TYPE = 0
GATEWAY_TYPE = 2
IVR_TYPE = 3

A questo punto formattare il comando “call_transfer_ext” come segue:

SERI_URL?service=call_transfer_ext&token=MIO_TOKEN
&replace_com_id=ID_COM_1
&replace_type=IVR_TYPE
&replace_id=IVR_ID
&replace_local_id=IVR_CALL_ID
&recipient_com_id=ID_COM_2
&recipient_type=USER_TYPE
&recipient_id=OPERATOR_ID
&recipient_call_id=OPERATOR_CALL_ID

… e lanciatelo nel vostro browser.
Se non avete commesso errori dovreste constatare che il numero esterno è connesso con l’operatore nella commutazione COM_1 e che la commutazione COM_2 è terminata.

Integrazione IVR

In questo capitolo tratteremo un altro tipo di integrazione molto potente e flessibile con il PBX VOIspeed. Stiamo parlando dell’integrazione lato risponditore automatico o IVR.

Introduzione

VOIspeed permette di creare un albero IVR i cui nodi, dopo aver mandato in play un messaggio audio e aver ricevuto l’eventuale input dell’utente, possono eseguire uno script esterno, indicando nei parametri le informazioni relative al numero connesso, all’ID commutazione, al nodo esplorato e all’input eventualmente ricevuto dall’utente via DTMF.

Inoltre, lo script eseguito, usando una certa sintassi che descriveremo in seguito, può restituire all’IVR mittente le nuove azioni da eseguire come transitare ad un nodo figlio, inoltrare la chiamata ad un numero o ad una entità di sistema oppure cambiare alcune o tutte le proprietà del nodo corrente ed eseguirlo di nuovo.

Configurazione integrazione IVR

Prima di iniziare la trattazione approfondita vediamo come configurare un IVR con un solo nodo radice che esegua uno script esterno.

Entrare in “Configurazione\Risponditori”
Creare un nuovo IVR e chiamatelo “Test integrazione IVR”
Create un nodo radice e chiamatelo “Radice test integrazione”
Selezionate un breve messaggio audio da mandare in play in modalità “NO LOOP”
Impostate “Tipologia input” a "Lunghezza fissa"
Impostate "Numero cifre di input=1"
Impostate “Azione del nodo” a "Esegui script"
nel campo “URL script” inserite “server_web_url/logger_ivr.php”

figura_2_2

Logger eventi IVR

In questa sezione implementeremo un semplice logger degli eventi IVR.
Nel vostro web server editate il file “logger_ivr.php” e inserite il seguente codice:

<?php
	$file_handle = fopen('logger_ivr.txt','a');
	$tmp_time = date(DATE_RSS);
	$tmp_query = $_SERVER['QUERY_STRING'];
	fwrite($file_handle,$tmp_time.' '.$tmp_query."\r\n");
	fclose($file_handle);
	return TRUE;
?>

Create una regola di instradamento per il numero 12345 e associatela all’IVR “Test Integrazione IVR” che avete creato al passo precedente. Prendete ora un terminale registrato dell’interno “35” e chiamate il numero “12345”.
Se avete eseguito correttamente tutte le operazioni indicate, dovreste ascoltare il messaggio audio che avete selezionato per il nodo “Radice test integrazione”. Durante il play del messaggio o alla fine dello stesso premete il tasto “1” del terminale che state usando.

Recatevi ora nel vostro web server ed aprite il file “logger_ivr.txt” e troverete la seguente riga contenente la “querystring” relativa allo script invocato dal nodo “Radice test integrazione”:

license_id=MP3026487718&domain=almach1.it&ivrid=9&nodeid=0
&callid=10724&calling=35&called=12345&input=1&tag=-1

Esaminiamo la “querystring” ricevuta nel dettaglio

license_id: licenza relativa alla vostra installazione VOIspeed
domain: dominio relativo alla vostra installazione VOIspeed
ivrid: ID dell’IVR mittente “Test integrazione IVR”
nodeid: ID del nodo mittente “Radice test integrazione”
callid: ID della commutazione che ospita la chiamata IVR
calling: numero connesso all’IVR
called: numero chiamato dal “calling” per connettersi all’IVR
input: sequenza DTMF inserita dal “calling”
tag: variabile di stato a vostra disposizione, il cui valore corrente è inserito in tutti gli script invocati dal nodo, e aggiornabile da voi al rientro dallo script stesso.

Avrete sicuramente notato che, dopo qualche secondo, la chiamata si è chiusa automaticamente. Prima di capirne il perché, è importante sottolineare:

N.B. Ogni volta che un nodo IVR esegue uno script, vi notifica delle informazioni relative alla chiamata ma, cosa più importante, al
rientro dello script stesso si aspetta vostre indicazioni sull’ azione
da compiere.

Se omettete di inserire le istruzioni, o le avete inserite sintatticamente sbagliate, verrà eseguita l’azione di default ossia terminazione chiamata. Questo spiega la chiusura automatica della nostra chiamata di test, infatti lo script “logger_ivr.php”, dopo aver “loggato” l’evento ritorna TRUE e nessuna istruzione.

Istruzioni di rientro script

Al rientro dello script, il nodo IVR mittente esegue una analisi della vostra risposta per estrarre l’azione da eseguire, pertanto, prima di analizzare in dettaglio quante e quali azioni è possibile definire, diamo alcune regole sintattiche per inviare istruzioni ben formate.

Lo script deve restituire una sequenza di righe di testo separate dal carattere “CRLF” (Carriage Return Line Feeder)
Ogni riga di testo deve contenere il nome di un parametro e il suo valore separati dal carattere “=” (es: parametro=valore)
Il nome del parametro e il suo valore è "case insentive"ossia è indifferente che lo scriviate in maiuscolo o minuscolo o entrambi.
La prima riga deve contenere il parametro COMMAND che specifica l’azione da eseguire (Appendici - Tabella 15).
```
 command=AZIONE
 parametro_1=valore_1
 parametro_2=valore_2
 ....
 parametro_N=valore_N
```

Ogni azione ha i suoi particolari parametri che ne permettono l’esecuzione.

Azione “Termina chiamata”

Codice: 0

Descrizione

Questa azione abbatte la chiamata corrente ed è l’azione di default nel caso in cui non venisse restituita nessuna istruzione o nel caso che le istruzioni fossero mal formate.

Esempio PHP:

<?php
	$file_handle = fopen('logger_ivr.txt','a');
	$tmp_time = date(DATE_RSS);
	$tmp_query = $_SERVER['QUERY_STRING'];
	fwrite($file_handle,$tmp_time.' '.$tmp_query."\r\n");
	fclose($file_handle);
	
	return 'command=0';
?>

Output script:

command=0

Azione “Transita a prossimo nodo”

Codice: 1

Descrizione

Questa azione indica al nodo corrente di transitare ad un suo nodo figlio con la chiave di selezione specificata dal parametro “node_key”.

Qualora non esistesse nessun nodo figlio con la chiave di selezione specificata si rimane nel nodo corrente fino a chiusura chiamata da parte dell’interlocutore.

Parametri

node_key: chiave di ingresso del sotto nodo nel quale si deve transitare.

Esempio PHP:

<?php
	$file_handle = fopen('logger_ivr.txt','a');
	$tmp_time = date(DATE_RSS);
	$tmp_query = $_SERVER['QUERY_STRING'];
	fwrite($file_handle,$tmp_time.' '.$tmp_query."\r\n");
	fclose($file_handle);
	
	$tmp_command = 'command=1';
	$tmp_key = 'node_key=2';
	
	return $tmp_command."\r\n".$tmp_key;
?>

Output script:

command=1
node_key=2

Azione “Trasferisci a numero”

Codice: 2

Descrizione

Questa azione indica al nodo corrente di trasferire la chiamata al numero specificato dal parametro “recipient_number”.

Parametri

recipient_number: numero al quale bisogna trasferire la chiamata.

N.B. L’entità cui verrà effettivamente trasferita la chiamata risulterà dall’analisi delle regole di instradamento configurate nel
PBX utilizzando come parametro di ricerca il numero
“recipient_number”

Esempio PHP:

<?php
	$file_handle = fopen('logger_ivr.txt','a');
	$tmp_time = date(DATE_RSS);
	$tmp_query = $_SERVER['QUERY_STRING'];
	fwrite($file_handle,$tmp_time.' '.$tmp_query."\r\n");
	fclose($file_handle);
	
	$tmp_command = 'command=2';
	$tmp_number = 'recipient_number=385';
	
	return $tmp_command."\r\n".$tmp_number;
?>

Output script:

command=2
recipient_number=385

Azione “Trasferisci ad entità”

Codice: 3

Descrizione

Questa azione indica al nodo corrente di trasferire la chiamata da una entità di sistema specificandone le coordinate tramite i parametri “recipient_id” e “recipient_type” utilizzando come numero chiamato il numero specificato dal parametro “recipient_number”.
Nell’esempio che segue supponiamo di voler trasferire la chiamata al Gruppo “assistenza” con ID=“5” notificandogli il numero aziendale chiamato ad esempio "073333655434"

Parametri:

recipent_id: ID dell’entità di destinazione
recipient_type: tipo dell’entità di destinazione (Appendici - Tabella 1)
recipient_number: numero da utilizzare come numero chiamato quando ci si connette con l’entità di destinazione

Ricordiamo che il codice che identifica il gruppo è 1

Esempio PHP:

<?php
	$file_handle = fopen('logger_ivr.txt','a');
	$tmp_time = date(DATE_RSS);
	$tmp_query = $_SERVER['QUERY_STRING'];
	fwrite($file_handle,$tmp_time.' '.$tmp_query."\r\n");
	fclose($file_handle);
	
	$tmp_cmd = 'command=3'."\r\n";
	$tmp_nr = 'recipient_number=073333655434'."\r\n";
	$tmp_id = 'recipient_id=5'."\r\n";
	$tmp_type = 'recipient_type=1';
	
	return $tmp_cmd.$tmp_nr.$tmp_id.$tmp_type;
?>

Output script:

command=3
recipient_number=073333655434
recipient_id=5
recipient_type=1

Azione “Aggiorna ed esegui nodo”

Codice: 4

Descrizione

Questa azione indica al nodo corrente di aggiornare le sue proprietà interne con il contenuto dei parametri restituiti ed lanciare la nuova esecuzione.

L’azione “Aggiorna ed esegui nodo” è forse il più potente e flessibile strumento di integrazione, in quanto permette all’integratore, al fronte di un unico nodo configurato lato VOIspeed, di eseguire delle logiche di instradamento completamente avulse dalla configurazione interna del PBX.
Assegnando

Parametri

audio_message: percorso del nuovo messaggio da mandare in play nel nodo corrente.
audio_loop: indica la modalità di play:
- “audio_loop=1” play del nuovo messaggio a ciclo continuo
- “audio_loop=0” play del nuovo messaggio una sola volta
input_type: indica la nuova modalità di input (Appendici - Tabella 11)
inpu_timeout: indica quanto tempo deve essere atteso il nuovo input prima che scatti l’azione “su fallimento”
input_length: nuova lunghezza attesa per l’input (solo per input_type=1).
termination_char: nuovo carattere di fine input (solo per input_type=2).
last_digit_timeout: nuovo valore per il timeot da ultima cifra (solo per input_type=3).
back_key: nuova chiave di ritorno al nodo precedente
node_action: la nuova azione che deve essere eseguita dal nodo (Appendici - Tabella 12)
called_id: ID dell’entità cui trasferire la chiamata (solo per “node_action=2”)
called_type: tipo dell’entità cui trasferire la chiamata (solo per “node_action=2”)
called_number: numero con il quale chiamare l’entità cui trasferire la chiamata (solo per “node_action=2”)
node_tag: nuovo tag esterno da applicare al nodo che verrà all’integratore come parametro del successivo script eseguito (solo se “node_action=3”)
script_url: url dello script da eseguire (solo se “node_action=3”)
failure_called_id: ID dell’entità cui trasferire la chiamata in caso non arrivasse l’input richiesto nel tempo previsto
failure_called_type: tipo dell’entità cui trasferire la chiamata in caso non arrivasse l’input richiesto nel tempo previsto
recipient_auto_answer: indica se il destinatario del trasferimento chiamata deve rispondere automaticamente o meno.

Esempio PHP

<?php
	$file_handle = fopen('logger_ivr.txt','a');
	$tmp_time = date(DATE_RSS);
	$tmp_query = $_SERVER['QUERY_STRING'];
	fwrite($file_handle,$tmp_time.' '.$tmp_query."\r\n");
	fclose($file_handle);
	
	$tmp_cmd = 'command=4'."\r\n";
	$tmp_msg = 'audio_message=nuovo_messaggio.wav'."\r\n";
	$tmp_loop = 'audio_loop=0'."\r\n";
	$tmp_len = 'input_length=6'."\r\n";
	$tmp_timeout = 'input_timeout=10'."\r\n";
	$tmp_action = 'node_action=3'."\r\n";
	$tmp_script = 'script_url=nuovo_url'."\r\n";
	$tmp_tag = 'tag=5';

	return $tmp_cmd.$tmp_msg .$tmp_loop .$tmp_len.$tmp_timeout.
	       $tmp_action.$tmp_script.$tmp_tag;
?>

Output script:

command=4
audio_message=nuovo_messaggio
audio_loop=0
input_length=6
input_timeout=30
node_action=3
script_url='nuovo_url'
tag=5

Al rientro dello script, il nodo corrente saprà che

dovrà mandare in play una sola volta il messaggio “nuovo_messaggio”
dovrà aspettare per massimo “30 secondi” un input di “6 cifre”
ricevute talì cifre dovrà invocare lo script “nuovo_script”
al quale script dovrà allegare il parametro “tag=5” (potrebbe essere una variabile di stato dell’integratore per vedere dove si trova, nella sua macchina a stati finiti quando riceve lo script dal nodo.

Esempio: Controllo PIN in ingresso

Supponiamo che una azienda eroghi un servizio di supporto tecnico avanzato telefonico, al quale si può accedere chiamando uno specifico numero “numero_supporto”.
Supponiamo, inoltre, che tale azienda fornisca a tutti i clienti, che hanno sottoscritto e pagato un abbonamento annuo, un PIN di 6 cifre tramite il quale accedere al servizio.
In questo esempio vedremo come implementare il controllo automatico del PIN tramite integrazione lato IVR.

Passo 1 - Creazione gruppo "Gruppo_supporto"

Create un gruppo e chiamatelo “Gruppo supporto”
Impostate modalità di squillo a “simultaneo”
Inserite nel gruppo 2\3 utenti che abbiano almeno un terminale registrato

Passo 2 - Creazione albero "IVR_Supporto"

Create un nuovo risponditore "IVR_Supporto"
al suo interno inserite un nodo radice “Radice_supporto” con le seguenti proprietà
- un messaggio audio di benvenuto, che inviti l’utente a digitare il proprio PIN
- impostare audio_loop=NO
- impostare tipo_input a “lunghezza fissa”
- impostare la lunghezza a “6”
- impostare il timeout a 10 secondi
- impostare l’azione del nodo a “esegui_script”
- impostare lo script da eseguire a “script_supporto.php”
- impostare l’azione su fallimento ad "Trasferisci chiamata a " e scegliete un utente predisposto a ricevere le chiamate “non autenticate”.
Creare un sotto nodo “PIN_errato” del nodo “Radice_supporto” con le seguenti proprietà:
- impostare la chiave di selezione a "1"
- impostate un messaggio di errore che notifichi l’imminente trasferimento all’operatore di default
- impostare “audio_loop=NO”
- impostare tipo input a “nessuno”
- impostare l’azione del nodo a “trasferisci a utente” e scegliete l’utente
Creare un sotto nodo “PIN_ok” del nodo “Radice_supporto” con le seguenti proprietà:
- impostare la chiave di selezione a "2"
- impostare un messaggio audio che notifichi la correttezza del PIN e l’imminente trasferimento al servizio di supporto tecnico.
- impostare “audio_loop=NO”
- impostare tipo input a “nessuno”
- impostare l’azione del nodo a “Trasferisci a Gruppo” e scegliere il “Gruppo_supporto”

Passo 3 - Instradamento
Create una nuova regola di instradamento “Regola_supporto” che connetta tutte le chiamate in ingresso per il numero “Numero_supporto” al risponditore automatico “IVR_Supporto”

Passo 4 - Implementazione script di verifica

Supponiamo per semplicità che l’unico PIN di 6 cifre ammesso nel
nostro piccolo esempio sia “123456” mentre tutte le altre sequenze
sono errate. In una applicazione reale, sicuramente l’azienda dispone di un DB al cui interno esiste una tabella dove verificare l’autenticità del PIN inserito.

Create il file “script_supporto.php” apritelo ed inserite dentro il seguente codice:

<?php
	$tmp_cmd = "command=1"."\r\n";
	if ($_GET["input"] == "123456"){	
    	$tmp_key = "node_key=2";    	
    } 
	else {	    	
    	$tmp_key = "node_key=1";			
	}
	return $tmp_cmd.$tmp_key;    	    	
?>

Analizzando lo script, possiamo vedere che, l’azione di rientro è sempre “Transita al prossimo nodo”, tuttavia, se la sequenza è corretta, la chiave di selezione viene impostata ad “2” ossia il nodo “successo”, se invece la sequenza è sbagliata, la chiave di selezione viene impostata a “1” ossia il nodo "fallimento"

Copiate il vostro script nel vostro web server e da un terminale di un utente terzo, chiamate il numero “numero_supporto”.
Se avete eseguito le configurazioni correttamente la vostra chiamata sarà connessa al nodo “Radice_supporto” del risponditore “IVR_Supporto”. Vi verrà chiesto di inserire un PIN di 6 cifre; digitalelo correttamente ossia “123456”; a questo punto dovreste sentire il messaggio del nodo “PIN_OK” e subito dopo la vostra chiamata sarà trasferita al gruppo “Gruppo_Supporto”.

Se ripetete l’operazione sbagliando la sequenza richiesta, dovreste transitare nel nodo “PIN_Errato” e subito dopo la chiamata sarà trasferita all’utente di default.

Sincronizzazione Rubrica contatti

Introduzione

Il servizio phonebook_import_sync permette allo sviluppatore esterno di importare e/o sincronizzare massivamente un insieme di contatti all’interno della rubrica centralizzata del PBX Voispeed.

Un aspetto importante nella gestione di questo comando è la possibilità di taggare i contatti importati in VOIspeed da un applicativo esterno con un uc_app_name; tale identificativo potrà essere assegnato ad un utente in modo che la UI, effettuando un login con tale identificativo, lo utilizzerà come preferenziale nella scelta della risoluzione del contatto in chiamata.

Gestione parametro uc_app_name

Come indicato nell’introduzione, il parametro uc_app_name (che verrà descritto nel dettaglio nel seguito del manuale) ha un significato importante anche nella gestione della risoluzione nome-numero effettuata dal sistema VOIspeed in fase di chiamata.

Quando VOIspeed gestisce una chiamata con una dato numero esterno cerca di risolverlo con i dati di contatto all’interno della propria rubrica; dal momento che con l’introduzione del servizio uc_app_name i contatti possono essere inseriti in VOIspeed anche da applicazioni di terze parti, l’utilizzatore potrebbe essere interessato a dare un priorità di risoluzione in maniera da risolvere situazioni potenzialmente controverse qualora, ad esempio, uno stesso numero si trovi in rubrica in associazione a diversi nominativi.

Per questo, nella configurazione del Modulo di integrazione (già visto nella sezione Strumenti di integrazione) esiste una sezione apposita dove è possibile specificare:

L’abilitazione del modulo alla sincronizzazione della rubrica;
Il tag di sincronizzazione della rubrica.

Abilitazione rubrica in modulo integrazione

Dopo aver configurato questo aspetto, nel profilo utente sarà possibile selezionare la propria applicazione creata per la sincronizzazione dei contatti in rubrica come applicazione preferenziale di risoluzione nome/numero in chiamata.

Configurazione risoluzione contatti utente

Parametri servizio

service: (obbligatorio) phonebook_import_sync
token: (obbligatorio) password di identificazione
verbose_output: [opzionale] 1 / 0 attiva o disattiva output esteso

Tale servizio deve essere necessariamente invocato tramite metodo http POST, il corpo deve contenere un unico parametro denominato “contacts” e valorizzato con i contatti da importare/sincronizzare in formato JSON. Il corpo della richiesta deve essere codificato secondo lo standard multipart/form-data.

Il singolo contatto è un oggetto con i seguenti attributi:

name: nome contatto
surname: cognome contatto
company: azienda contatto
numoffice: numero ufficio
numhome: numero abitazione
nummobile: numero cellulare
numsms: numero sms
nummobil2: numero cellulare alternativo
numfax: numero di fax
numother: altro numero
email: indirizzo email
uc_app_name: nome dell’applicazione di terze parti da cui proviene il contatto
external_contact_id: (obbligatorio) identificativo del contatto per l’applicazione di terze parti
ext_info: informazioni addizionali contatto.

Esempio del body del POST:

contacts:[{"name":"Gustavo",
	   "surname":"Fring",
           "company":"Los Pollos Hermanos", 
	   "numoffice":"0733123123",
	   "numhome":"0733456456",
	   "nummobile":"3339876543",
	   "numsms":"3339876543",
	   "nummobil2":"3339876543",
	   "numfax":"0733998877",
	   "numother":"0254739399",
	   "email":"gustavofring@yahoo.com",
	   "uc_app_name":"HBO",
	   "uc_external_id":"contact-1",
	   "ext_info":"..."},
	  {"name":"Walter",
	   "surname":"White",
	   "company":"Car Washing Inc.",
	   "numoffice":"555123123",
	   "numhome":"555456456",
	   "nummobile":"5559876543",
	   "numsms":"5559876543",
	   "nummobil2":"5559876543",
	   "numfax":"555998877",
	   "numother":"55554739399",
	   "email":"walterwhite@yahoo.com",
	   "uc_app_name":"HBO",
	   "uc_external_id":"contact-2",
	   "ext_info":"..."},
	  {"name":"Saul",
	   "surname":"Goodman",
	   "company":"Goodman Lawyer",
	   "numoffice":"06123123",
	   "numhome":"06456456",
	   "nummobile":"069876543",
	   "numsms":"069876543",
	   "nummobil2":"069876543",
	   "numfax":"06998877",
	   "numother":"0654739399",
	   "email":"saulgoodman@yahoo.com",
	   "uc_app_name":"HBO",
	   "uc_external_id":"contact-3",
	   "ext_info":"..."}]

I parametri che rappresentato numeri telefonici ammettono stringhe formate esclusivamente da caratteri numerici, al più prefissati con il “+”. Eventuali altri caratteri come lettere, spazi, virgole o caratteri speciali, vengono eliminati (sanificati).

Informazioni addizionali contatto

Il parametro ext_info permette di allegare al contatto delle informazioni addizionali, tipiche dell’applicazione di terze parti. Tali informazioni sono intese come dati di interesse per l’utente, al fine di gestire al meglio i contatti in sede di chiamata. Ad esempio, se il contatto è un cliente dell’azienda, le informazioni potrebbero essere il fatturato del cliente, il fido concesso, le fatture pagate, non pagate, etc. Questi dati possono essere successivamente sfruttati, in fase di chiamata, per essere visualizzate all’interno dell’interfaccia utente (UI VOISpeed). Affiché questi vengano recepiti correttamente devono rispettare un determinato formato. In particolare devono essere codificate in formato JSON e devono essere una collezione di oggetti, ognuno dei quali presenta due campi/attributi: ‘caption’ e ‘value’, che rappresentano rispettivamente il nome o titolo dell’informazione e l’informazione stessa. Ecco un esempio di valorizzazione del parametro ext_info per associare informazioni addizionali in un contatto:

"ext_info":[{"caption":"Saldo",
	     "value":"1000 EUR"},
	    {"caption":"Limite di credito",
	     "value":"2000 EUR"},
	    {"caption":"Agente vendite",
	     "value":"Mario Rossi"},
	     ....
	     ....
	    {"caption":"Indirizzo spedizione",
	     "value":"Corso Repubblica 15"}]

Risultato servizio

Il risultato del servizio si differenzia in base alla scelta del parametro output esteso (verbose_output).

Base:

Nel caso di output base l’xml restituito è il seguente.

<result> 
    <outcome>0</outcome>
    <processed>N contatti processati dal servizio</processed>
	<skipped>N contatti saltati perché non validi</skipped>
	<warnings>N contatti importati ma che hanno generato un avviso</warnings>
	<errors>N contatti non importati a causa di errori del server</errors>
</result>

I contatti possono essere saltati per diverse ragioni:

uno o più parametri obbligatori non sono specificati;
tutti e tre i campi name, surname e company sono vuoti;
tutti i campi che rappresentano numeri telefonici sono vuoti (dopo il processo di sanificazione);
il parametro uc_app_name non è valido (questo parametro è ritenuto valido quando rientra in uno dei valori ammessi tra i moduli di integrazione VOIspeed abilitati a caricare contatti nella rubrica, per ulteriori informazioni vedi documentazione PBX)

I contatti producono un warning in uscita quando:

uno o più campi contengono caratteri non ammessi.

Esteso:

Nel caso di output esteso l’xml restituito, oltre alle informazioni base, include un report esaustivo con le tutte le informazioni relative al singolo contatto.

<result> 
    <outcome>0</outcome>
    <processed>N contatti processati dal servizio</processed>
	<skipped>N contatti saltati perché non validi</skipped>
	<warnings>N contatti importati ma che hanno generato un avviso</warnings>
	<errors>N contatti non importati a causa di errori del server</errors>
	<contacts>
		<contact>
			<uc_external_id>identificativo del contatto per l'applicazione di terze parti</uc_external_id>
			<id>identificativo contatto VOISpeed</id>
			<act>azione svolta durante il processamento del contatto (insert / update)</act>
			<info>eventuale messaggio di errore o avviso</info>
		</contact>
		...
		...
		...
		<contact>
			<uc_external_id>identificativo del contatto per l'applicazione di terze parti</uc_external_id>
			<id>identificativo contatto VOISpeed</id>
			<act>azione svolta durante il processamento del contatto (insert /  update)</act>
			<info>eventuale messaggio di errore o avviso</info>
		</contact>
	</contacts>
</result>

Il tag permette di capire quale azione è stata effettuata sul particolare contatto, ovvero l’inserimento di un nuovo elemento o l’aggiornamento di un elemento esistente. L’algoritmo alla base di questo comportamento si basa su due coordinate, rappresentate dai parametri uc_app_name e external_contact_id. Se nella rubrica VOIspeed non viene trovato nessun contatto che corrisponde al valore di questi due parametri, viene aggiunto un nuovo contatto ( insert ); diversamente se esiste già un contatto con tali coordinate esso non viene duplicato, ma viene sovrascritto ( update ). Questo approccio consente di effettuare una sincronizzazione massiva della rubrica ripetuta nel tempo, evitando duplicazioni dei contatti presenti nell’applicativo esterno.

Appendici

Tabella 1

Valore	Tipo entità
0	Utente
1	Gruppo di squillo
2	Gateway
3	Risponditore automatico IVR
7	Terminale
8	Casella vocale aziendale
10	Sala riunioni
11	Linee parcheggio
13	Reparto

Tabella 2

Valore	Stato audio video
0	Sconosciuto
1	Irraggiungibile
2	Disponibile
3	In squillo
4	Occupato
5	Non disturbare DND
6	Riservato
7	Assente
8	In deviazione

Tabella 3

Valore	Tipo gateway
0	Carrier Voip
1	Linea ISDN
2	Rete GSM
3	Linea Analogica

Tabella 4

Valore	Stato gateway
1	Non registrato
2	Registrato
7	Tentativo registrazione

Tabella 5

Valore	Tipo terminale
0	Sconosciuto
1	Riservato
2	Terminale SIP
3	Terminale USB
4	Terminale DECT
5	Terminale mobile

Tabella 6

Valore	Eventi utente
1	Comando fallito
8	Chiamata in arrivo all’utente
9	Chiamata fatta dall’utente
10	Nuovo messaggio vocale per l’utente
12	Nuova chiamata persa per l’utente
14	Chiamata in conversazione
15	Chiamata rifiutata
16	Chiamata terminata dall’utente
17	Terminazione chiamata ricevuta
18	Chiamata trasferita

Tabella 7

Valore	Stato chiamata utente
0	Sconosciuto
1	In connessione in uscita
2	Attiva
3	In Attesa
4	Terminata
5	In connessione in ingresso

Tabella 8

Valore	Esito chiamate
0	Sconosciuto
1	OK
2	Numero chiamato occupato
3	Rifiutata da numero chiamato
4	Numero chiamato irraggiungibile
5	Numero chiamato non risponde
6	Non ci sono linee disponibili per connessione al numero chiamato
7	Numero chiamato in non disturbare (solo se interno)
8	Numero chiamato assente (solo se interno)
9	Numero chiamante non risponde
10	Numero chiamante occupato
11	Rifiutata da numero chiamante
12	Numero chiamato irraggiungibile
13	Non ci sono linee disponibili per connessione al numero chiamante

Tabella 9

Valore	Stato commutazione
0	Inattiva
1	Chiamata in arrivo da entità chiamante
2	In connessione con entità chiamata
3	Attiva
4	In deviazione verso altra entità o numero
5	In cattura da parte di un utente
6	Chiamato non disponibile
7	In terminazione
8	Terminata

Tabella 10

Valore	Modalità di squillo gruppo
1	squillo simultaneo
2	squillo ciclico
3	squillo ciclico con avanzamento
4	squillo progressivo
5	squillo progressivo con avanzamento
6	non usato
7	accodamento automatico

Tabella 11

Valore	Tipo input nodo IVR
0	nessun input atteso
1	input a lunghezza fissa
2	input terminato da carattere
3	input con timeout da ultima cifra ricevuta

Tabella 12

Valore	Azioni nodo IVR
0	nessuna azione
1	transizione al prossimo nodo
2	esegui chiamata
3	esegui script esterno

Tabella 13

Valore	Risposta automatica
0	nessuna risposta automatica
1	il chiamante risponde automaticamente
2	il chiamato risponde automaticamente

Tabella 14

Codice avanzamento	Descrizione
180	Chiamato in squillo
181	Chiamata inoltrata
183	Avanzamento generico di chiamata

Tabella 15

Valore	Azione di rientro da script IVR
0	Terminare chiamata
1	Transitare al prossimo nodo
2	Trasferire chiamata a numero
3	Trasferire chiamata ad una entità
4	Esegui di nuovo il nodo con le nuove proprietà