Mesaje SpeechCall
SpeechCall este un tip de mesaj cu răspuns vocal interactiv (IVR) care vă permite să efectuați apeluri vocale automate cu opțiuni de meniu și interacțiuni DTMF (dual-ton multi-frecvency).
Prezentare generală
SpeechCall permite companiilor să:
- Efectuați apeluri vocale automate către clienți
- Redați mesaje audio introductive
- Prezentați opțiuni de meniu interactiv
- Gestionați răspunsurile la apăsarea tastelor DTMF (0-9, *, #)
- Definiți comportamentul personalizat pentru intrările invalide/timeout
- Declanșați webhook-uri cu corpuri și anteturi personalizate pe baza selecțiilor utilizatorului
- Gestionați fluxul de apeluri în mod dinamic (navigați între meniuri)
Cazuri de utilizare
- Sondaje clienți - Colectați feedback prin opțiunile din meniul telefonului
- Mementouri pentru întâlniri - Confirmați sau reprogramați cu interacțiunea vocală
- Urmărirea comenzii - Furnizați actualizări privind starea comenzii
- Notificări interactive - Furnizează informații importante cu opțiuni de acțiune
- Verificare vocală - Autentificare cu mai mulți factori prin apeluri vocale
Format de solicitare
Structura de bază
{
"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"
}
]
}
}
]
}
]
}
Descrierea parametrului
| Parametru | Tip | Necesar | Descriere |
|---|---|---|---|
din | șir | Da | Identificatorul expeditorului (nume alfa sau ID) |
la | șir | Da | Numărul de telefon al destinatarului în format internațional |
text | șir | Da | Valoare text, de obicei „ivr” pentru SpeechCall |
tip | șir | Da | Trebuie să fie „apel vocal” |
meniu | matrice | Da | Gamă de configurații de meniu pentru apel |
Configurare meniu
Fiecare obiect de meniu conține:
| Parametru | Tip | Necesar | Descriere |
|---|---|---|---|
introUrl | șir | Da | URL sau identificatorul fișierului audio introductiv |
idleTimeoutMsec | întreg | Nu | Timeout în milisecunde pentru a aștepta apăsarea unei taste (de exemplu, „10000”). Dacă utilizatorul nu răspunde, se vor executa acțiunile configurate sub tasta greșită |
dtmfActions | obiect | Da | Harta cheilor DTMF către acțiuni |
Acțiuni DTMF
Obiectul dtmfActions mapează cheile DTMF sau condițiile speciale la matrice de acțiuni:
| Cheie DTMF | Descriere |
|---|---|
d0 | Apăsați 0 |
d1 | Apăsați 1 |
d2 | Apăsați 2 |
| … | … |
d9 | Apăsați 9 |
d* | Apăsați * |
d# | Apăsați # |
greșit | Se declanșează atunci când este apăsată o tastă nevalidă sau când idleTimeoutMsec este atins fără nicio introducere |
Fiecare cheie/condiție DTMF se mapează la o serie de acțiuni care vor fi executate în secvență.
Acțiuni acceptate
| Acțiune | Parametri | Descriere |
|---|---|---|
webhook | url (șir, obligatoriu)body (obiect, opțional)headers (obiect, opțional) | Trimite o solicitare HTTP POST în format JSON la adresa URL specificată. Obiectul body va fi imbricat sub câmpul action din cererea webhook. Antetele personalizate sunt incluse ca antete HTTP. |
închidere | Niciuna | Încheie apelul |
gotoMenu | meniu (șir sau întreg) | Navighează apelul către un alt meniu din matricea menu folosind indexul său bazat pe 0 (de exemplu, "1") |
Comportament de acțiune detaliat
Acțiune webhook (webhook)
Acțiunea „webhook” trimite o solicitare HTTP POST la adresa URL de apel invers cu metadatele apelului și date personalizate opționale:
- Dacă este furnizat un „corp”, perechile sale cheie-valoare sunt trimise în câmpul „acțiune” al corpului încărcăturii utile.
- Dacă sunt furnizate „anteturi”, acestea sunt trimise ca antete HTTP personalizate în cerere.
Acțiune de suspendare („închidere”)
Acțiunea „închidere” încheie apelul activ imediat. Nu vor fi procesate alte acțiuni din secvență sau meniuri după o acțiune de „închidere”.
Accesați Meniu Acțiune (gotoMenu)
Acțiunea gotoMenu redirecționează fluxul apelului către o structură diferită de meniu din matricea menu. Este nevoie de un singur parametru meniu care specifică indexul bazat pe 0 al meniului țintă (de exemplu, "1" pentru a merge la al doilea meniu sau "0" pentru a reporni primul meniu).
Inactivitate și gestionarea erorilor („greșit”)
Cheia „greșită” din interiorul „dtmfActions” este un handler special de fallthrough. Își execută secvența matricei de acțiuni în două scenarii:
- Input Invalid: Apelantul apasă o tastă DTMF care nu este definită în
dtmfActions(de exemplu, ei apasă3, dar meniul definește doard1șid2). - Idle Timeout: Apelantul nu apasă nicio tastă în timpul specificat de
idleTimeoutMsec.
Dacă „greșit” nu este definit și apelantul apasă o tastă nevalidă sau expiră, fluxul de apel se va închide în mod implicit. Definirea „greșit” vă permite să construiți meniuri în buclă (de exemplu, revenirea la același meniu cu „acțiune”: „gotoMenu”, „meniu”: „0”`) sau redirecționarea utilizatorului către un meniu de ajutor.
Format de livrare webhook
Când acțiunea webhook este declanșată, sistemul trimite o solicitare HTTP POST către url configurat cu Content-Type: application/json.
Anteturi de solicitare Webhook
Dacă acțiunea este configurată cu parametrul headers, acele perechi cheie-valoare sunt incluse ca antete HTTP în cerere.
Corpul solicitării webhook
Sarcina utilă JSON trimisă la adresa URL a webhook-ului dvs. are următoarea structură:
{
"from": "0443914272",
"to": "50001",
"mid": "7748021",
"action": {
"confirm": true
}
}
| Câmp | Tip | Descriere |
|---|---|---|
din | șir | Numărul de telefon al apelantului / ID-ul expeditorului |
la | șir | Numărul de telefon al destinatarului |
mid | șir | ID mesaj |
acțiune | obiect | Obiectul JSON personalizat definit în câmpul „corp” al acțiunii |
Exemplu complet
IVR simplu cu Timeout & Validare de intrare
{
"messages": [
{
"from": "YourSender",
"to": "+380XXXXXXXXX",
"text": "ivr",
"type": "speechcall",
"menu": [
{
"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"
}
]
}
}
]
}
]
}
IVR complex cu meniuri multiple și rutare DTMF
Acest exemplu demonstrează cum să definiți mai multe meniuri și să navigați între ele folosind acțiunea gotoMenu atunci când utilizatorul introduce o tastă nevalidă sau când apelul expiră. De asemenea, arată corpuri personalizate și anteturi HTTP personalizate trimise cu declanșatoarele 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"
}
]
}
}
]
}
]
}
Format de răspuns
Răspuns de succes
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380XXXXXXXXX",
"status": "sent"
}
]
}
Gestionarea erorilor
| Stare HTTP | Descriere |
|---|---|
| 200 | Solicitare reușită |
| 400 | Format de solicitare nevalid |
| 401 | Autentificarea eșuată |
| 429 | Limita ratei a fost depășită |
| 500 | Eroare internă server |
Exemplu de cURL
curl -X POST https://restapi.smsbat.com/bat/messagelist \
-u "username:password" \
-H "Content-Type: application/json" \
-d '{
"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"
}
]
}
}
]
}
]
}'
Cele mai bune practici
- Fișiere audio - Asigurați-vă că adresele URL de introducere sunt accesibile și că fișierele audio sunt în formate acceptate
- Webhook Reliability - Proiectați webhook-uri pentru a răspunde rapid (în 2 secunde)
- Opțiuni DTMF - Limitați opțiunile de meniu la 4-6 opțiuni pentru o experiență mai bună a utilizatorului
- Gestionare timeout - Folosiți
idleTimeoutMsecpentru a specifica limite personalizate de inactivitate (de exemplu, 10000 ms) și configurați o rezervă grațioasă sub tasta DTMFgreșită(cum ar fi repetarea meniului sau închiderea) - Flux de apeluri cu mai multe meniu - Utilizați
gotoMenucu atenție pentru a preveni bucle infinite atunci când direcționați utilizatorii înapoi la meniurile anterioare - Fallback Strategy - Folosiți mesaje de rezervă pentru utilizatorii care nu răspund sau nu se deconectează
Subiecte conexe
- Trimite mesaj - Ghid general de trimitere a mesajelor
- Apel flash - Apeluri simple de verificare vocală
- Verificați starea - Urmăriți starea livrării mesajelor
- Tipuri de mesaje - Prezentare generală a tuturor tipurilor de mesaje acceptate