Logo

GUIDA INTEGRAZIONE Voispeed

Introduzione

La piattaforma telefonica multimediale Voispeed dispone di strumenti di integrazione potenti e flessibili che permettono la realizzazione di molte funzionalità ed esigenze altrimenti non ottenibili con la semplice configurazione del PBX.

Nel corso di questa guida descriveremo alcuni concetti base dell’architettura della piattaforma Voispeed e al suo funzionamento; questo preambolo è assolutamente necessario per poi comprendere appieno gli strumenti di sviluppo a vostra disposizione.

Proseguiremo con l’analisi dei vari strumenti di integrazione disponibili e come si configurano per essere subito operativi. Contestualmente a questa sezione, infatti, scriveremo le nostre prime applicazioni “ciao mondo”, una per ogni tipo di integrazione.
Elencheremo tutti i servizi e tutti gli eventi disponibili descrivendone i parametri e il loro significato.

L’ultima parte della guida si focalizzerà su tre scenari molto comuni di integrazione in ambiente aziendale che verranno analizzati, e parzialmente implementati:

  1. Implementeremo una barra telefonica all’interno di un mini CRM, dal quale saremo in grado di creare chiamate, metterle in attesa e recuperarle, abbatterle e visualizzarne contestualmente le schede contatto.
  2. Implementeremo un semplice predictive dialer che in ambito call centre è uno strumento molto usato. La nostra applicazione esempio prenderà in input un numero elevato di numeri. Tali numeri verranno chiamati automaticamente, e al momento della risposta, l’interlocutore esterno verrà messo in comunicazione con un operatore del call centre stesso.
  3. In questo scenario, attraverso la richiesta PIN da parte dell 'IVR, autenticheremo il chiamante per poi inoltrarlo all’operatore più adatto al processamento della chiamata.

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).

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

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).

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.

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).

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.

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.

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:

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

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):

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.

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.

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.

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.

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>

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”:

  1. event_type=2&event=9&event_name=outgoing_call&ext=35
  2. event_type=2&event=14&event_name=call_answered&ext=35
  3. 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.

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

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

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

Ricapitolando

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

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.

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

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:

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:

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:

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:

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” 
    <call>
</result> 

Eventi utente

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

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:

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 rende impossibile l’erogazione del servizio del stesso, viene notificato l’evento “cmd_failed”.

Parametri

Evento “incoming_call”

Codice: 8

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

Parametri

Evento “outgoing_call”

Codice: 9

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

Evento “new_voicemail”

Codice: 10

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

Parametri

Evento “lost_call”

Codice: 12

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

Parametri

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

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

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

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

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:

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

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:

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:

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:

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:

Result:

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

Service “update_phonebook”

Descrizione

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

Parametri:

Service “delete_phonebook”

Descrizione

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

Parametri:

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:

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’:

AppServicesPBXCallingCalledcall_request_ext(calling, called)make_call ( calling, called )OKOK, request_idCALL (from called_number)notify_event ( call_out )CALL_OUT ( calling )CALL_ANSWER ( accepted )notify_event ( response, ok )RESPONSE ( calling )CALL ( from calling_number )notify_event ( call_out )CALL_OUT ( called )CALL_ANSWER ( accepted )notify_event ( response, ok )RESPONSE ( called )AppServicesPBXCallingCalled

Parametri:

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:

Commutation_1
Entity_A
Entity_C
entity_call_A
entity_call_C
Commutation_2
Entity_D
Entity_B
entity_call_D
entity_call_B

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

Commutation_1
Entity_B
Entity_C
entity_call_B
entity_call_C

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

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

Parametri

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:

Commutation_1
Entity_A
Entity_B
entity_call_A
entity_call_B

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:

Commutation_1
Entity_A
Entity_C
entity_call_A
entity_call_C

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

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

Parametri

Service “call_recording_ext”

Descrizione

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

Parametri

Service “call_terminate”

Descrizione

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

Parametri

Eventi estesi

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

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:

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

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

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

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

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

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

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

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

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

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

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

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)

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.

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.

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:

  1. la prima commutazione COM_1 per connettere un numero esterno con l’IVR accoglienza con ID commutazione ID_COM_1.
  2. 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:

Per la seconda chiamata riceveremo gli eventi:

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:

Inoltre chiameremo:

Infine, da Appendici - Tabella1, sappiamo che:

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.

  1. Entrare in “Configurazione\Risponditori
  2. Creare un nuovo IVR e chiamatelo “Test integrazione IVR
  3. Create un nodo radice e chiamatelo “Radice test integrazione
  4. Selezionate un breve messaggio audio da mandare in play in modalità “NO LOOP
  5. Impostate “Tipologia input” a "Lunghezza fissa"
  6. Impostate "Numero cifre di input=1"
  7. Impostate “Azione del nodo” a "Esegui script"
  8. 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 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

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.

callingIVR_NodeAppDTMF(xyz)?NOTIFY( call_info, xyz )ACTIONcallingIVR_NodeApp

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.

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

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

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:

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

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

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"

Passo 2 - Creazione albero "IVR_Supporto"

Chiave: 1
Chiave: 2
Transfer
Transfer
Radice_supporto
PIN_ERRATO
PIN_OK
Default_user
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; digitatelo 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:

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

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:

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:

I contatti producono un warning in uscita quando:

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 <act> 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à