Help Center Messaggi SpeechCall

Messaggi SpeechCall

SpeechCall è un tipo di messaggio di risposta vocale interattiva (IVR) che consente di effettuare chiamate vocali automatizzate con opzioni di menu e interazioni DTMF (multifrequenza a doppio tono).

Panoramica

SpeechCall consente alle aziende di:

  • Effettua chiamate vocali automatizzate ai clienti
  • Riproduci messaggi audio introduttivi
  • Presenti opzioni di menu interattive
  • Gestire le risposte alla pressione dei tasti DTMF (0-9, *, #)
  • Definire il comportamento personalizzato per input non validi/timeout
  • Attiva webhook con corpi e intestazioni personalizzati in base alle selezioni dell’utente
  • Gestire il flusso delle chiamate in modo dinamico (navigare tra i menu)

Casi d’uso

  • Sondaggi sui clienti: raccogli feedback tramite le opzioni del menu del telefono
  • Promemoria appuntamenti - Conferma o riprogramma con l’interazione vocale
  • Tracciamento dell’ordine - Fornisci aggiornamenti sullo stato dell’ordine
  • Notifiche interattive - Fornisci informazioni importanti con opzioni di azione
  • Verifica vocale - Autenticazione a più fattori tramite chiamate vocali

Richiedi formato

Struttura di base

{
  "messages": [
    {
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "text": "ivr",
      "type": "speechcall",
      "menu": [
        {
          "introUrl": "ivr_XXXXX",
          "idleTimeoutMsec": 10000,
          "dtmfActions": {
            "d1": [
              {
                "action": "webhook",
                "url": "https://YourWebhookURL/0",
                "body": {
                  "confirm": true
                },
                "headers": {
                  "test-header": "test"
                }
              },
              {
                "action": "hangup"
              }
            ],
            "d2": [
              {
                "action": "webhook",
                "url": "https://YourWebhookURL/1",
                "body": {
                  "confirm": false
                }
              },
              {
                "action": "hangup"
              }
            ],
            "wrong": [
              {
                "action": "gotoMenu",
                "menu": "1"
              }
            ]
          }
        }
      ]
    }
  ]
}

Descrizione dei parametri

ParametroDigitareObbligatorioDescrizione
”da”stringaSìIdentificatore del mittente (nome alfabetico o ID)
“a”stringaSìNumero di telefono del destinatario in formato internazionale
”testo”stringaSìValore di testo, in genere “ivr” per SpeechCall
”tipo”stringaSìDeve essere "chiamata vocale"
menùmatriceSìSerie di configurazioni di menu per la chiamata

Configurazione del menu

Ogni oggetto del menu contiene:

ParametroDigitareObbligatorioDescrizione
introUrlstringaSìURL o identificatore del file audio introduttivo
idleTimeoutMsecinteroNoTimeout in millisecondi per attendere la pressione di un tasto (ad esempio, 10000). Se l’utente non risponde, verranno eseguite le azioni configurate con la chiave sbagliata
dtmfActionsoggettoSìMappa dei tasti DTMF per le azioni

Azioni DTMF

L’oggetto dtmfActions mappa le chiavi DTMF o le condizioni speciali su array di azioni:

Tasto DTMFDescrizione
d0Premere 0
d1Premere 1
d2Premere 2
……
d9Premere 9
d*Premere *
d#Premere #
sbagliatoSi attiva quando viene premuto un tasto non valido o quando viene raggiunto idleTimeoutMsec senza alcun input

Ciascun tasto/condizione DTMF è associato a una serie di azioni che verranno eseguite in sequenza.

Azioni supportate

AzioneParametriDescrizione
”webhook”url (stringa, obbligatorio)
body (oggetto, opzionale)
headers (oggetto, opzionale)		Invia una richiesta HTTP POST in formato JSON all’URL specificato. L’oggetto “body” verrà nidificato nel campo “action” nella richiesta del webhook. Le intestazioni personalizzate sono incluse come intestazioni HTTP.
”riagganciare”NessunoTermina la chiamata
vai al Menumenu (stringa o intero)Sposta la chiamata a un altro menu nell’array menu utilizzando il suo indice basato su 0 (ad esempio, "1")

Comportamento dettagliato dell’azione

Azione webhook (webhook)

L’azione “webhook” invia una richiesta HTTP POST al tuo URL di richiamata con i metadati della chiamata e dati personalizzati facoltativi:

  • Se viene fornito un “corpo”, le sue coppie chiave-valore vengono inviate all’interno del campo “azione” del corpo del payload.
  • Se vengono fornite “intestazioni”, vengono inviate come intestazioni HTTP personalizzate nella richiesta.

Azione di riaggancio (riaggancia)

L’azione “riaggancia” termina immediatamente la chiamata attiva. Nessuna ulteriore azione nella sequenza o nei menu verrà elaborata dopo un’azione di “riaggancia”.

Vai all’azione del menu (gotoMenu)

L’azione “gotoMenu” reindirizza il flusso della chiamata a una struttura di menu diversa all’interno dell’array “menu”. Richiede un singolo parametro menu che specifica l’indice basato su 0 del menu di destinazione (ad esempio, "1" per andare al secondo menu o "0" per riavviare il primo menu).

Inattività e gestione degli errori (sbagliato)

La chiave “sbagliata” all’interno di “dtmfActions” è uno speciale gestore di fallthrough. Esegue la sequenza di serie di azioni in due scenari:

  1. Input non valido: il chiamante preme un tasto DTMF che non è definito in “dtmfActions” (ad esempio, preme “3” ma il menu definisce solo “d1” e “d2”).
  2. Idle Timeout: il chiamante non preme alcun tasto entro la durata specificata da idleTimeoutMsec.

Se “sbagliato” non è definito e il chiamante preme un tasto non valido o va in timeout, il flusso della chiamata verrà interrotto per impostazione predefinita. La definizione di “sbagliato” consente di creare menu in loop (ad esempio, tornando allo stesso menu con “action”: “gotoMenu”, “menu”: “0”`) o reindirizzando l’utente a un menu di aiuto.

Formato di consegna del webhook

Quando viene attivata l’azione “webhook”, il sistema invia una richiesta HTTP POST all‘“url” configurato con “Content-Type: application/json”.

Intestazioni delle richieste webhook

Se l’azione è configurata con il parametro “headers”, tali coppie chiave-valore vengono incluse come intestazioni HTTP nella richiesta.

Corpo della richiesta webhook

Il payload JSON inviato all’URL del webhook ha la seguente struttura:

{
  "from": "0443914272",
  "to": "50001",
  "mid": "7748021",
  "action": {
    "confirm": true
  }
}
CampoDigitareDescrizione
”da”stringaNumero di telefono del chiamante/ID mittente
”a”stringaNumero di telefono del destinatario
mezzostringaID messaggio
azioneoggettoL’oggetto JSON personalizzato definito nel campo “corpo” dell’azione

Esempio completo

IVR semplice con timeout e convalida dell’input

CODICE_BLOCCO_2

IVR complesso con menu multipli e routing DTMF

Questo esempio dimostra come definire più menu e navigare tra di essi utilizzando l’azione “gotoMenu” quando l’utente immette una chiave non valida o quando la chiamata scade. Mostra anche corpi personalizzati e intestazioni HTTP personalizzate inviate con i trigger webhook.

{
  "messages": [
    {
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "text": "ivr",
      "type": "speechcall",
      "menu": [
        {
          "introUrl": "ivr_XXXXX",
          "idleTimeoutMsec": 10000,
          "dtmfActions": {
            "d1": [
              {
                "action": "webhook",
                "url": "https://YourWebhookURL/0",
                "body": {
                  "confirm": true
                },
                "headers": {
                  "test-header": "test"
                }
              },
              {
                "action": "hangup"
              }
            ],
            "d2": [
              {
                "action": "webhook",
                "url": "https://YourWebhookURL/1",
                "body": {
                  "confirm": false
                }
              },
              {
                "action": "hangup"
              }
            ],
            "wrong": [
              {
                "action": "gotoMenu",
                "menu": "1"
              }
            ]
          }
        },
        {
          "introUrl": "ivr_651854",
          "idleTimeoutMsec": 10000,
          "dtmfActions": {
            "d1": [
              {
                "action": "webhook",
                "url": "https://YourWebhookURL/0",
                "body": {
                  "confirm": true
                }
              },
              {
                "action": "hangup"
              }
            ],
            "d2": [
              {
                "action": "webhook",
                "url": "https://YourWebhookURL/1",
                "body": {
                  "confirm": false
                }
              },
              {
                "action": "hangup"
              }
            ],
            "wrong": [
              {
                "action": "hangup"
              }
            ]
          }
        }
      ]
    }
  ]
}

Formato della risposta

Risposta riuscita

{
  "messages": [
    {
      "messageId": "unique-message-id",
      "recipient": "+380XXXXXXXXX",
      "status": "sent"
    }
  ]
}

Gestione degli errori

Stato HTTPDescrizione
200Richiesta riuscita
400Formato richiesta non valido
401Autenticazione non riuscita
429Limite tariffario superato
500Errore interno del server

Esempio di cURL

CODICE_BLOCCO_5

Migliori pratiche

  1. File audio: assicurati che gli URL introduttivi siano accessibili e che i file audio siano nei formati supportati
  2. Affidabilità del webhook: progetta i webhook per rispondere rapidamente (entro 2 secondi)
  3. Opzioni DTMF: limita le opzioni del menu a 4-6 scelte per una migliore esperienza utente
  4. Gestione del timeout - Utilizza idleTimeoutMsec per specificare limiti di inattività personalizzati (ad esempio 10000 ms) e configura un fallback corretto sotto la chiave DTMF “sbagliata” (come ripetere il menu o riagganciare)
  5. Flusso chiamate multi-menu: utilizzare “gotoMenu” con attenzione per evitare loop infiniti quando si reindirizzano gli utenti ai menu precedenti
  6. Strategia di fallback: utilizza messaggi di fallback per gli utenti che non rispondono o non si disconnettono

Argomenti correlati