Differenze tra le versioni di "AdminGuide:Service:ExternalAPIs"

Da Kalliope Wiki.
Jump to navigation Jump to search
 
(18 versioni intermedie di 4 utenti non mostrate)
Riga 1: Riga 1:
Questa  applicazione permette  di  effettuare  l’instradamento  della chiamata in base alla
[[File:Api esterne.png|miniatura]]
risposta di una API esterna. Tale API viene invocata passando una serie di parametri numerici,  
Questo servizio permette  di  effettuare  l’instradamento  di una chiamata in ingresso sulla base della risposta di una API esterna.
che possono essere richiesti al chiamante tramite prompt vocali preregistrati.<br>
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; in fase di configurazione, è  
L’API deve essere servita da un web server esterno al KalliopePBX.
possibile specificare i seguenti parametri:
 
* URL dell’API: può essere un URL di tipo http o https (senza validazione del certificato  
Configurazione del servizio <br>
del server).
La configurazione del servizio viene effettuata nel pannello Applicazioni PBX -> API ESterne
* Autenticazione:  può  essere  NONE  (nessuna  autenticazione)  o  BASIC  (Basic  http  
In fase di configurazione è necessario specificare i seguenti parametri:
Authentication);  in  questo  secondo  caso  è  necessario  specificare  le  credenziali  di  
* URL dell’API: può essere un URL di tipo http o https (senza validazione del certificato del server).
autenticazione (username e password).
* Autenticazione:  può  essere  NONE  (nessuna  autenticazione)  o  BASIC  (Basic  http Authentication);   
* Tipo  di  richiesta:  l’invocazione  dell’API  può  essere  effettuata  in  GET  o  in  POST;  nel  
in  questo  secondo  caso  è  necessario  specificare  le  credenziali  di autenticazione (username e password).
primo caso gli eventuali parametri vengono passati nella URL di richiesta, mentre nel  
* Tipo  di  richiesta:  l’invocazione  dell’API  può  essere  effettuata  in  GET  o  in  POST;   
secondo  caso  è  possibile  specificare  il  formato  del  corpo  della  richiesta  (contenuto  
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.<br>
POST), ed il relativo Content-Type.<br>
Per  entrambi  i  tipi  di  richiesta  (GET  o  POST),  il  passaggio  dei  parametri  all’API  avviene  
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  
tramite dei placeholder inseriti nell’URL o nel contenuto del POST; i placeholder riconosciuti  
sono:
sono:
* %CALLER_NUM%: indica il numero chiamante  
* %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 [[Registro_delle_chiamate|CDR]].
* %PARAM1%,  …,  %PARAMnn%:  indica  gli  “nn”  parametri  richiesti  al  chiamante  tramite  
* %PARAM1%,  …,  %PARAMnn%:  indica  gli  “nn”  parametri  richiesti  al  chiamante  tramite  
un menù vocale interattivo, costruito come descritto in seguito.<br>
un menù vocale interattivo, costruito come descritto in seguito.<br>
Lo  specifico  formato  della  richiesta  è  ovviamente  funzione  dell’implementazione  dell’API  
Lo  specifico  formato  della  richiesta  è  ovviamente  funzione  dell’implementazione  dell’API  
esterna. <br>
esterna. <br>
<br>
A titolo di esempio, nel caso di richiesta GET l’URL potrebbe essere costruito come:<br>
A titolo di esempio, nel caso di richiesta GET l’URL potrebbe essere costruito come:<br>
<code>http://www.myserver.com/api?arg1=%CALLER_NUM%&arg2=%PARAM1%&arg3=%PARAM2% </code><br>
<code>http://www.myserver.com/api?arg1=%CALLER_NUM%&arg2=%PARAM1%&arg3=%PARAM2% </code><br>
mentre nel caso di richiesta di tipo POST, il corpo potrebbe essere:<br>
mentre nel caso di richiesta di tipo POST, il corpo potrebbe essere:<br>
<syntaxhighlight lang="xml"><?xml version="1.0"?>
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<parameters>
<parameters>
<caller>%CALLER_NUM%</caller>
<caller>%CALLER_NUM%</caller>
<param_01>%PARAM1</param_01>
<param_01>%PARAM1</param_01>
<param_02>%PARAM2</param_02>
<param_02>%PARAM2</param_02>
</parameters></syntaxhighlight><br>
</parameters>
</syntaxhighlight>
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.
<br>
È  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:
 
<syntaxhighlight lang="xml">
<?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>
</syntaxhighlight>
 
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>. <br>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).

Versione attuale delle 20:20, 18 set 2017

Api esterne.png

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