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
	"key": il nome della variabile che deve contenere ciò che pronuncia l'utente al telefono
	"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
	"next_url": «url» della successiva REST che deve essere chiamata da ai4call
}

Solo nella risposta della tua prima REST/HTTPS puoi inserire questi ulteriori campi (opzionali):
NextStep::= {
	"language": ...
	"timezone": ...
	...
}

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

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.