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": "BazarCOM",
      "to": "+380936670003",
      "text": "ivr",
      "type": "speechcall",
      "menu": [
        {
          "introUrl": "ivr_651854",
          "idleTimeoutMsec": 10000,
          "dtmfActions": {
            "d1": [
              {
                "action": "webhook",
                "url": "https://api.example.com/callback/option1",
                "body": {
                  "confirm": true
                },
                "headers": {
                  "X-Custom-Header": "value"
                }
              },
              {
                "action": "hangup"
              }
            ],
            "d2": [
              {
                "action": "webhook",
                "url": "https://api.example.com/callback/option2",
                "body": {
                  "confirm": false
                }
              },
              {
                "action": "hangup"
              }
            ],
            "wrong": [
              {
                "action": "hangup"
              }
            ]
          }
        }
      ]
    }
  ]
}

Descrizione dei parametri

Parametro	Digitare	Obbligatorio	Descrizione
"da"	stringa	Sì	Identificatore del mittente (nome alfabetico o ID)
"a"	stringa	Sì	Numero di telefono del destinatario in formato internazionale
"testo"	stringa	Sì	Valore di testo, in genere "ivr" per SpeechCall
"tipo"	stringa	Sì	Deve essere `"chiamata vocale"`
`menù`	matrice	Sì	Serie di configurazioni di menu per la chiamata

Ogni oggetto del menu contiene:

Parametro	Digitare	Obbligatorio	Descrizione
`introUrl`	stringa	Sì	URL o identificatore del file audio introduttivo
`idleTimeoutMsec`	intero	No	Timeout 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`
`dtmfActions`	oggetto	Sì	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 DTMF	Descrizione
`d0`	Premere 0
`d1`	Premere 1
`d2`	Premere 2
...	...
`d9`	Premere 9
`d*`	Premere *
`d#`	Premere #
`sbagliato`	Si 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

Azione	Parametri	Descrizione
"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"	Nessuno	Termina la chiamata
`vai al Menu`	`menu` (stringa o intero)	Sposta la chiamata a un altro menu nell'array `menu` utilizzando il suo indice basato su 0 (ad esempio, `"1"`)

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
  }
}

Campo	Digitare	Descrizione
"da"	stringa	Numero di telefono del chiamante/ID mittente
"a"	stringa	Numero di telefono del destinatario
`mezzo`	stringa	ID messaggio
`azione`	oggetto	L'oggetto JSON personalizzato definito nel campo "corpo" dell'azione

Esempio completo

IVR semplice con timeout e convalida dell'input

CODICE_BLOCCO_2

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_651854",
          "idleTimeoutMsec": 10000,
          "dtmfActions": {
            "d1": [
              {
                "action": "webhook",
                "url": "http://api.smsbat.local/gatereq/temp/hook",
                "body": {
                  "confirm": true
                },
                "headers": {
                  "test-header": "test"
                }
              },
              {
                "action": "hangup"
              }
            ],
            "d2": [
              {
                "action": "webhook",
                "url": "http://api.smsbat.local/gatereq/temp/hook",
                "body": {
                  "confirm": false
                }
              },
              {
                "action": "hangup"
              }
            ],
            "wrong": [
              {
                "action": "gotoMenu",
                "menu": "1"
              }
            ]
          }
        },
        {
          "introUrl": "ivr_651854",
          "idleTimeoutMsec": 10000,
          "dtmfActions": {
            "d1": [
              {
                "action": "webhook",
                "url": "http://localhost/1"
              }
            ],
            "d2": [
              {
                "action": "webhook",
                "url": "http://localhost/1"
              }
            ],
            "wrong": [
              {
                "action": "hangup"
              }
            ]
          }
        }
      ]
    }
  ]
}

Formato della risposta

Risposta riuscita

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

Gestione degli errori

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

Esempio di cURL

CODICE_BLOCCO_5

Migliori pratiche

File audio: assicurati che gli URL introduttivi siano accessibili e che i file audio siano nei formati supportati
Affidabilità del webhook: progetta i webhook per rispondere rapidamente (entro 2 secondi)
Opzioni DTMF: limita le opzioni del menu a 4-6 scelte per una migliore esperienza utente
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)
Flusso chiamate multi-menu: utilizzare "gotoMenu" con attenzione per evitare loop infiniti quando si reindirizzano gli utenti ai menu precedenti
Strategia di fallback: utilizza messaggi di fallback per gli utenti che non rispondono o non si disconnettono

Argomenti correlati

Invia messaggio - Guida generale all'invio di messaggi
Chiamata Flash - Semplici chiamate di verifica vocale
Verifica stato - Tieni traccia dello stato di consegna dei messaggi
Tipi di messaggio - Panoramica di tutti i tipi di messaggio supportati