ai4call ti consente di gestire e pilotare una telefonata e di interagire, tramite i servizi TTS, ASR e STT, con:
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.
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:
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.
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:
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.
La <client_url_prima_rest> la definisci direttamente da interfaccia web di configurazione del progetto
<api_key> è la tua API-Key, che viene reinviata da ai4call
nelle REST successive.
(>>> vedi documentazione "portale web" <<<).
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"
, }
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")
}
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"
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" }
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"
"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 |
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.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 |
Il campo next_url rappresenta l'«URL» della successiva REST che deve essere chiamata da ai4call.
next_url string Conditional
Il campo accepted_commands contiene l'array dei comandi che ai4call deve intercettare (es. ["conferma", "annulla", "ripeti"]).
Va specificato solo se command è "ASR_command".
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".
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.
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).
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.
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.+
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
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:
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
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:
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
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:
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.
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 }