Introduzione

ai4call ti consente di gestire e pilotare una telefonata e di interagire, tramite i servizi TTS, ASR e STT, con:

  • gli utenti chiamanti
  • i tuoi software (gestionali, CRM, ERP, sistemi di prenotazione, etc)
  • sistemi di terze parti (chatgpt, openai, Gemini, chat-bot, etc)

 INFO

ai4call analizza l'audio della telefonata in tempo reale e questo gli consente di poter accettare "comandi vocali" anche durante la riproduzione di un messaggio audio.
In questo modo, non si "costringe" l'utente chiamante ad ascoltare interamente i messaggi audio e a digitare qualche tasto (solitamente il #) per indicare al sistema che ha terminato di parlare.
Inoltre, la gestione in tempo reale di ai4call riduce i tempi dell'ASR offrendo migliori performance.


Prerequisiti

 Per l'attuale fase di test che terminerà il 24/07/2024

Per iniziare ad utilizzare ai4call devi semplicemente richiedere l'account sviluppatori di test da questo >>> [FORM] <<<

Ti verrà assegnato un numero telefonico che potrai immediatamente utilizzare per provare il TUO progetto con ai4call
Ti verrà inviato uno o più più progetti di esempio (solitamente scritti in nodeJS) da cui potrai prendere interessanti spunti


Per iniziare ad utilizzare ai4call devi semplicemente:

  • creare il tuo account su ai4call (interfaccia web di gestione sarà disponibile a partire dal 15/04/2024)
  • configurare il tuo primo progetto su ai4call.com, inserendo questi dati:
    • url della tua prima REST/HTTPS che ai4call deve richiedere all'arrivo della telefonata
    • IP da autorizzare per le segnalazioni SIP
    • la tua API-Key che ai4call deve utilizzare per l'autenticazione al tuo Server REST/HTTPS
  • creare il trunk SIP tra il tuo PBX e ai4call
  • creare il routing SIP tra il tuo PBX e ai4call
  • creare il tuo Server REST/HTTPS

 NOTA

Per interagire con ai4call devi predisporre un Server REST/HTTPS in grado di ricevere richieste REST/HTTPS da ai4call. ai4call, infatti, opera da Client REST/HTTPS ed invia una richiesta al tuo Server REST/HTTPS per ogni telefonata in arrivo.


Logica funzionamento


FLUSSO

1) La telefonata arriva a ai4call (da trunk SIP, ai4call-transfer-connector o ai4call-direct): ai4call invia la richiesta alla url della tua prima REST/HTTPS con:

  • numero di telefono del chiamate
  • numero di telefono chiamato
2) Tu ricevi la richiesta per la tua prima REST/HTTPS: fai le tue elaborazioni in base al progetto (es. controlla l'identità del chiamante in base al suo numero di telefono, se è presente nel tuo DB) e dai come risposta a ai4call:
  • il testo da riprodurre col TTS
  • le informazioni necessarie per una determinata "action" (es. attendi un dato o un comando da parte del chiamante)
  • la next_url, ovvero la «URL» della tua successiva REST che ai4call deve chiamare
Nella risposta alla tua prima REST/HTTPS potrai anche specificare, optionalmente, il "language" da utilizzare per TTS e ASR e la "timezone".

3) ai4call riceve la tua risposta. ai4call procede con:
  • la riproduzione del TTS
  • l'esecuzione della "action" (es. "ascolta una data") ascoltando cosa dice il chiamante ed interpretandolo tramite l'ASR
  • invia le informazioni acquisite alla next_url
4) Tu ricevi la richiesta per la tua next_url: fai le tue elaborazioni in base al progetto
(es. se il progetto è un sistema di prenotazioni, controlla che in quella data ci siano disponibilità) e dai come risposta a ai4call:
  • il testo da riprodurre col TTS
  • le informazioni necessarie per una determinata "action" (es. "ascolta un comando del tipo conferma/annulla")
  • la next_url, ovvero la «url» della tua successiva REST che ai4call deve chiamare
Da qui in poi è un LOOP tra i punti 3 e 4, fino alla chiusura o al trasferimento della telefonata.


Prima REST

All'arrivo della telefonata ai4call invia la prima richiesta HTTPS per la tua prima REST/HTTPS.

POST <client_url_prima_rest>
Content-Type: application/json
X-Api-Key: <api_key>
X-Call-Id: <call_id>
{
	"callerNumber": "39333123456789",
	"recipientNumber": "39333987654321",
}

<call_id> è una stringa identificativa univoca della telefonata, che viene reinviata da ai4call nelle REST successive.
<api_key>  è la tua API-Key, che viene reinviata da ai4call nelle REST successive.

 NOTA

La <client_url_prima_rest> la definisci direttamente da interfaccia web di configurazione del progetto
(>>> vedi documentazione "portale web" <<<).


Hangup REST

Al termine della telefonata, da parte del chiamante o di ai4call stesso, ai4call invia la sua ultima richiesta a una hangup REST.

Nel body vengono passate tutte le variabili raccolte durante la telefonata.

POST <client_url_hangup_rest>
Content-Type: application/json
X-Api-Key: <api_key>
X-Call-Id: <call_id>
{
    "callerNumber": "39333123456789",
    "recipientNumber": "39333987654321",
    "key1": "value1",
    "key2": "value2",
}

NextStep | Formato delle tue risposte

La risposta che devi dare alle richieste HTTPS fatte da ai4call al tuo Server REST/HTTPS deve essere di tipo NextStep, dove NextStep è un JSON con i seguenti campi:

NextStep::= {
	"action": ASR_Type | "redirect" | "hangup" | "none"
	"text": testo per TTS. Può essere interrotto dalla voce del chiamante.
	
	"next_url": «url» della successiva REST che deve essere chiamata da ai4call
	"key": il nome della variabile che deve contenere ciò che pronuncia l'utente al telefono
	"max_repeat": il numero massimo di ripetizioni della frase in text, prima di richiamare next_url
	"repeat_delay": il numero di ms tra due ripetizioni di text
	"min_length": numero minimo di cifre da inserire per action "DTMF" o "ASR_DTMF"
	"max_length": numero massimo di cifre da inserire per action "DTMF" o "ASR_DTMF"
	"accept_timeout": timeout prima di accettare le cifre inserite finora (per action "DTMF" o "ASR_DTMF")
	"accepted_commands": l'array di stringhe contenenti cosa ai4call deve intercettare come "ASR_command" 
	                (es. conferma, annulla, prossimo, etc)
	"extension": l'estensione del tuo PBX a cui ai4call deve trasferire la chiamata (per action "redirect")
}
 NOTA
Solo nella risposta della tua prima REST/HTTPS puoi inserire questi ulteriori campi (opzionali):
NextStep::= {
	"language": ...
	"timezone": ...
	...
}

dove:
language stringa (opzionale) con cui specifichi la lingua da impostare per l'ASR e il TTS. Default: "it"
timezone stringa (opzionale) con cui specifichi il fuso orario con cui interpretare le date e le ore per i tipi "date" e "time". Ad esempio, se l'ora pronunciata dall'utente chiamante è "le quindici" e la timezone selezionata per la telefonata è "Europe/Rome", l'orario restituito dall'ASR sarà "15:00:00UTC+01:00" (in ora solare) o "15:00:00UTC+02:00" (in ora legale). Default: "Europe/Rome"

 Esempio di risposta alla richiesta HTTPS di ai4call
200 OK
Content-Type: application/json
{
      "text": "Benvenuto al sistema di prenotazione della pizzeria Bella Napoli. Per quale giorno desidera prenotare?",
      "action": "ASR_date",
      "key": "data_prenotazione",
      "next_url": "https://api.servizio-esterno.it/ricevi-data"
      // accepted_commands non è specificato perché "action" non è "command"
      // extension non è specificato perché "action" non è "redirect"
}


NextStep::action

Il campo action contiene l'azione che dovrà essere eseguita al prossimo step.
Può contenere il tipo di dato che il riconoscitore vocale dovrà ascoltare dal chiamante al prossimo step della chiamata. In questo caso è di tipo ASR_Type.
Le altre azioni consentite sono "redirect", "hangup" e "none"

action string Required
"ASR_string":vuoi che ai4call ti restituisca quanto pronunciato dall'utente
"ASR_number":vuoi che ai4call intercetti e ti restituisca i numeri pronunciati dall'utente
"ASR_DTMF":vuoi che ai4call intercetti e ti restituisca le cifre pronunciate o digitate dall'utente
"ASR_date":vuoi che ai4call intercetti e ti restituisca la data pronunciata dall'utente, incluse parole quali "oggi", "ieri", "domani", che verranno convertite in date
"ASR_time":vuoi che ai4call intercetti e ti restituisca l'orario pronunciato dall'utente
"ASR_command":vuoi che ai4call intercetti e ti restituisca una specifica parola pronunciata dall'utente fra quelle da te specificate (es. "conferma", "annulla", "prossimo", etc)
"DTMF":vuoi che ai4call intercetti e ti restituisca le cifre digitate dall'utente (senza attivare il riconoscimento vocale)
"redirect":vuoi che ai4call trasferisca la telefonata nuovamente al tuo PBX
"hangup":vuoi che ai4call chiuda la telefonata
"none":vuoi che ai4call riproduca solo il TTS


NextStep::text

Il campo text contiene il testo del TTS che ai4call deve riprodurre. La lunghezza massima è di 4096 caratteri.

text string Optional Nel caso in cui il campo text venga eseguito con un'action di tipo ASR_Type, il testo verrà interrotto nel momento in cui l'ASR rileverà che l'utente sta parlando. Se quando l'utente termina di parlare il tipo di dato richiesto non è stato riconosciuto, il sistema ripeterà il testo.


NextStep::key

Il campo key rappresenta il nome della variabile che contiene quanto ai4call ha intercettato e restituito. Va specificato per tutte le action di tipo ASR_Type. È una stringa contenente solo lettere, numeri e underscore (nessuno spazio o carattere speciale); ad esempio, un valore di key può essere "data_prenotazione"

key string Conditional

La variabile definita col campo key contiene il risultato di quanto ai4call ha intercettato e restituito secondo le "disposizioni" che hai dato nel campo action.

Se action valorizzato a "ASR_string":il valore contenuto sarà quanto pronunciato dall'utente
Se action valorizzato a "ASR_number":il valore contenuto sarà il numero pronunciato dall'utente
Se action valorizzato a "ASR_DTMF" o "DTMF":il valore contenuto saranno le cifre pronunciate o digitate dall'utente
Se action valorizzato a "ASR_date":il valore contenuto sarà la data pronunciata dall'utente
La data verrà comunicata come UTC UNIX timestamp in millisecondi, corrispondente alla mezzanotte in UTC del giorno selezionato.
Se action valorizzato a "ASR_time":il valore contenuto sarà l'orario pronunciato dall'utente
L'ora selezionata verrà comunicata come UTC UNIX timestamp in millisecondi. Per utilizzare l'informazione sull'ora, basterà interpretare il timestamp nel fuso orario corrente e scartare la data.
Se action valorizzato a "ASR_command":devi fornire un array di parole nel campo accepted_commands della tua risposta REST. La variabile contiene il primo comando pronunciato dall'utente fra i comandi in "accepted_commands". Ciascun comando è una singola parola, spazi o numeri non sono ammessi.
Se action valorizzato a "redirect":non viene memorizzato nulla
Se action valorizzato a "hangup":non viene memorizzato nulla
Se action valorizzato a "none":non viene memorizzato nulla

NextStep::next_url

Il campo next_url rappresenta l'«URL» della successiva REST che deve essere chiamata da ai4call.

next_url string Conditional

NextStep::accepted_commands

Il campo accepted_commands contiene l'array dei comandi che ai4call deve intercettare (es. ["conferma", "annulla", "ripeti"]).
Va specificato solo se command è "ASR_command".

accepted_commands array string Conditional

NextStep::extension

Il campo extension specifica a quale estensione del tuo PBX la chiamata dovrà essere inoltrata in caso di un redirect.
Generalmente coincide con il numero di un interno aziendale o un numero di telefono a cui vuoi trasferire la chiamata.
Va specificato solo se action è "redirect".

extension string Conditional

NextStep::max_length e NextStep::min_length

I campi max_length e min_length specificano il numero massimo e minimo di cifre da attendere per un input di tipo DTMF.
Vanno specificati solo se action è "DTMF" o "ASR_DTMF".
Se non specificati, di default sono entrambi pari a 1, ovvero, il DTMF terminerà subito alla prima cifra pronunciata o digitata dall'utente.
Se specificati, l'action DTMF rimarrà in attesa fin quando non verranno digitate (o pronunciate) almeno un numero di cifre pari a min_length, e al più pari a max_length.

max_length string Optional
min_length string Optional

NextStep::accept_timeout

Va specificato solo se action è "DTMF" o "ASR_DTMF". Il campo accept_timeout determina il numero di millisecondi di inattività da attendere prima che il sistema accetti le cifre digitate o pronunciate finora e le invii all'API server
Il campo viene considerato solo se il numero di cifre digitate finora è compreso tra min_length e max_length (estremi inclusi).

accept_timeout string Conditional

NextStep::max_repeat

Il campo max_repeat determina il numero massimo di ripetizioni della frase in text.
Da utilizzare con le action che richiedono input del chiamante, ovvero ASR_Type o DTMF.
Se specificato, nel caso in cui il chiamante non specifichi nessun input, al termine di tutte le ripetizioni la next_url verrà richiamata senza nessun valore all'interno della variabile specificata in key. Se non specificato, ha un valore di default pari a 5.

max_repeat string Optional

NextStep::repeat_delay

Il campo repeat_delay specifica il numero di millisecondi di intervallo tra due ripetizioni della frase in text.
Da utilizzare con le action che richiedono input dell'utente, ovvero ASR_Type o DTMF.
Se non specificato, ai4call ripeterà la frase un numero indefinito di volte fin quando riceverà l'input desiderato dal chiamante.
Se specificato, nel caso in cui il chiamante non specifichi nessun input, al termine di tutte le ripetizioni la next_url verrà richiamata senza nessun valore all'interno della variabile specificata in key.+

max_repeat string Optional

Esempio: flusso di una telefonata

Consideriamo un "progetto prenotazioni" ai4call connesso a un server HTTP (realizzato dal cliente):
https://prenotazioni.example.com per un "sistema di prenotazioni"

Un utente con numero di telefono 393331234567 chiama il numero di telefono 393337654321 connesso a "progetto prenotazioni".

ai4call invia la prima richiesta HTTP al sistema di prenotazioni

ai4call invia la prima richiesta HTTP al sistema di prenotazioni
POST https://prenotazioni.example.com/nuova-telefonata
Content-Type: application/json
X-Api-Key: <api_key>
X-Call-Id: <call_id>
{
     "callerNumber": "393331234567",
     "recipientNumber": "393337654321"
}

Il sistema di prenotazioni risponde con:

sistema di prenotazioni da risposta alla prima richiesta HTTP
200 OK
Content-Type: application/json
{
    "text": "Benvenuto al sistema di prenotazione della pizzeria Bella Napoli. Per quale giorno desidera prenotare?",
    "action": "ASR_date",
    "key": "data_prenotazione",
    "next_url": "https://prenotazioni.example.com/ricevi-data"
}

ai4call riproduce, mediante TTS, al chiamante il testo presente in "text" e rimane in attesa che il chiamante pronunci una data.
Il chiamante pronuncia "il 15 aprile 2024". ai4call interpreta la data e la memorizza nella variabile data_prenotazione. Lo invia quindi alla "next_url" del sistema di prenotazioni, nel body di una nuova richiesta HTTP

ai4call esegue la nuova "action" richiesta da sistema di prenotazioni
POST https://prenotazioni.example.com/ricevi-data
Content-Type: application/json
X-Api-Key: <api_key>
X-Call-Id: <call_id>
{
     "callerNumber": "393331234567",
     "recipientNumber": "393337654321",
     "data_prenotazione": 1713132000000
}

Il sistema di prenotazioni del cliente produce quindi il prossimo NextStep:

sistema di prenotazioni da risposta alla richiesta HTTP
200 OK
Content-Type: application/json
{
     "text": "Per quale ora la prenotazione?",
     "action": "ASR_time",
     "next_url": "https://prenotazioni.example.com/ricevi-ora",
     "key": "ora_prenotazione"
}

ai4call riproduce al chiamante il nuovo testo presente in "text" e rimane in attesa che il chiamante pronunci un orario.
Il chiamante pronuncia "alle venti e quindici". ai4call interpreta l'orario e lo memorizza nella variabile ora_prenotazione. Lo invia quindi alla "next_url" del sistema di prenotazioni, nel body di una nuova richiesta HTTP

ai4call esegue la nuova "action" richiesta da sistema di prenotazioni
POST https://prenotazioni.example.com/ricevi-ora
Content-Type: application/json
X-Api-Key: <api_key>
X-Call-Id: <call_id>
{
     "callerNumber": "393331234567",
     "recipientNumber": "393337654321",
     "data_prenotazione": 1713132000000,
     "ora_prenotazione": 1713204900000
}

Il sistema di prenotazioni del cliente verifica la disponibilità per la data e l'ora specificate. In questo caso lo slot data/ora risulta essere libero. sistema di prenotazioni invia, quindi, una risposta:

sistema di prenotazioni da risposta alla richiesta HTTP
200 OK
Content-Type: application/json
{
     "text": "Le confermiamo la prenotazione per il giorno 15 aprile 2024 alle ore 20:15",
     "action": "hangup"
}

ai4call, quindi, riproduce il nuovo testo presente in "text" e termina la telefonata.


ai4call chiama la Hangup REST passando tutte le variabili precedentemente valorizzare.
POST https://prenotazioni.example.com/hangup-rest
Content-Type: application/json
X-Api-Key: <api_key>
X-Call-Id: <call_id>
{
     "callerNumber": "393331234567",
     "recipientNumber": "393337654321",
     "data_prenotazione": 1713132000000,
     "ora_prenotazione": 1713204900000
}