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": "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"
}
]
}
}
]
}
]
}
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") |
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ă:
| 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": "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
}
},
{
"action": "hangup"
}
],
"d2": [
{
"action": "webhook",
"url": "https://api.example.com/callback/option2",
"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_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"
}
]
}
}
]
}
]
}
Format de răspuns
Răspuns de succes
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380936670003",
"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_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"
}
]
}
}
]
}
]
}'
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 - Utilizaț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