NextStep::text

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

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"

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.

NextStep::next_url

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

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

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

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.

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

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.

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

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

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.