AdminGuide:Service:ExternalAPIs

Questo servizio permette di effettuare l’instradamento di una chiamata in ingresso sulla base della risposta di una API esterna. Tale API viene invocata passando una serie di parametri numerici, che possono essere richiesti al chiamante tramite prompt vocali preregistrati. L’API deve essere servita da un web server esterno al KalliopePBX.

Configurazione del servizio
La configurazione del servizio viene effettuata nel pannello Applicazioni PBX -> API ESterne In fase di configurazione è necessario specificare i seguenti parametri:

• URL dell’API: può essere un URL di tipo http o https (senza validazione del certificato del server).
• Autenticazione: può essere NONE (nessuna autenticazione) o BASIC (Basic http Authentication);

in questo secondo caso è necessario specificare le credenziali di autenticazione (username e password).

• Tipo di richiesta: l’invocazione dell’API può essere effettuata in GET o in POST;

nel primo caso gli eventuali parametri vengono passati nella URL di richiesta, mentre nel secondo caso è possibile specificare il formato del corpo della richiesta (contenuto POST), ed il relativo Content-Type.
Per entrambi i tipi di richiesta (GET o POST), il passaggio dei parametri all’API avviene tramite dei placeholder inseriti nell’URL o nel contenuto del POST; i placeholder riconosciuti sono:

• %CALLER_NUM%: indica il numero chiamante
• %DNID%: indica il numero chiamato
• %UNIQUE_ID%: indica il codice identificativo univoco della chiamata. Tramite tale identificativo è possibile rintracciare la chiamata sul CDR.
• %PARAM1%, …, %PARAMnn%: indica gli “nn” parametri richiesti al chiamante tramite

un menù vocale interattivo, costruito come descritto in seguito.
Lo specifico formato della richiesta è ovviamente funzione dell’implementazione dell’API esterna.

A titolo di esempio, nel caso di richiesta GET l’URL potrebbe essere costruito come:
http://www.myserver.com/api?arg1=%CALLER_NUM%&arg2=%PARAM1%&arg3=%PARAM2%
mentre nel caso di richiesta di tipo POST, il corpo potrebbe essere:

<?xml version="1.0"?>
<parameters>
<caller>%CALLER_NUM%</caller>
<param_01>%PARAM1</param_01>
<param_02>%PARAM2</param_02>
</parameters>

Per ciascun parametro (numerico) da richiedere al chiamante, deve essere inserito un messaggio vocale (ad esempio con la richiesta di inserimento); opzionalmente, è possibile specificare il massimo numero di cifre inseribili. Se non viene specificato tale valore, il sistema assume che l’utente abbia terminato l’inserimento del parametro dopo un timeout di 5 secondi, o alla pressione del tasto “#”. In caso di mancata digitazione di una qualsiasi cifra, è prevista la ripetizione della richiesta per un massimo di 3 volte.
È infine possibile abilitare la richiesta di conferma, mediante l’apposita checkbox; se abilitata, il sistema ripete all’utente le cifre inserite e chiede di confermare la correttezza dell’inserimento mediante la digitazione del tasto “1”. In caso di assenza di conferma, viene ripetuta la richiesta di inserimento del parametro. Una volta che siano stati raccolti tutti i parametri richiesti, viene invocata l’API configurata; il sistema si aspetta dal server web una risposta di tipo “200 OK”, il cui corpo deve contenere un testo XML come segue:

<?xml version="1.0"?>
<response>
<message>
<elem>digit:1</elem>
<elem>number:200</elem>
<elem>alpha:c234</elem>
<elem>audio:custom/TENANT_UID/sounds/misc/pluto</elem>
<elem>number:201</elem>
<elem>digit:123</elem>
<elem>audio:custom/TENANT_UID/sounds/misc/pippo</elem>
</message>
<value>105</value>
</response>

Il tag <value> indica la risposta dell’API, in base alla quale possono essere definite le azioni da compiere. Al chiamante può essere inoltre riprodotto un messaggio, costruito con un messaggio di introduzione (specificato da GUI nel riquadro corrispondente) ed una serie di altri messaggi concatenati l’uno all’altro, e composti in base alla sequenza dei tag <elem> presenti nella risposta <message>.
I valori ammessi per il tag <elem> sono:

• digit: riproduce i singoli digit, uno alla volta (possono essere specificati numeri composti da più cifre, che saranno lette una alla volta)
• number: riproduce l’intero numero
• alpha: accetta cifre e lettere alfabetiche, che riproduce una alla volta
• audio: specifica il percorso di un file audio (contenuto nel PBX) da riprodurre

Tra le azioni possibili di uscita, vi è anche la possibilità di inviare la chiamata al piano di numerazione, utilizzando come selezione il valore di risposta dell’API; è presente infine una azione da compiere in caso di errore nell’invocazione dell’API (es. se il server web non è raggiungibile, o se la risposta non è formattata in modo corretto).