Taleopkaldsmeddelelser
SpeechCall er en interaktiv stemmesvar (IVR) beskedtype, der giver dig mulighed for at foretage automatiske taleopkald med menuindstillinger og DTMF (dual-tone multi-frequency) interaktioner.
Oversigt
SpeechCall gør det muligt for virksomheder at: - Foretag automatiske taleopkald til kunder - Afspil indledende lydbeskeder - Præsenter interaktive menuindstillinger - Håndter DTMF-tastetryk (0-9, *, #) - Definer tilpasset adfærd for ugyldige/timeout-input - Udløs webhooks med brugerdefinerede tekster og overskrifter baseret på brugervalg - Administrer opkaldsflow dynamisk (naviger mellem menuer)
Use Cases
- Kundeundersøgelser - Indsaml feedback via telefonmenuindstillinger
- Aftalepåmindelser - Bekræft eller omplanlæg med stemmeinteraktion
- Ordresporing - Giv ordrestatusopdateringer
- Interaktive meddelelser - Lever vigtige oplysninger med handlingsmuligheder
- Stemmebekræftelse - Multifaktorgodkendelse via taleopkald
Forespørgselsformat
Grundlæggende struktur
{
"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"
}
]
}
}
]
}
]
}
Parameter Beskrivelse
| Parameter | Skriv | Påkrævet | Beskrivelse |
|---|---|---|---|
fra |
streng | Ja | Afsender-id (alfanavn eller ID) |
til |
streng | Ja | Modtagerens telefonnummer i internationalt format |
tekst |
streng | Ja | Tekstværdi, typisk "ivr" for SpeechCall |
type |
streng | Ja | Skal være "taleopkald" |
menu |
række | Ja | Array af menukonfigurationer for opkaldet |
Menukonfiguration
Hvert menuobjekt indeholder:
| Parameter | Skriv | Påkrævet | Beskrivelse |
|---|---|---|---|
introUrl |
streng | Ja | URL eller identifikator for den indledende lydfil |
idleTimeoutMsec |
heltal | Nej | Timeout i millisekunder for at vente på et tastetryk (f.eks. "10000"). Hvis brugeren ikke reagerer, vil handlingerne konfigureret under den 'forkerte' nøgle blive udført |
dtmfActions |
objekt | Ja | Kort over DTMF-nøgler til handlinger |
DTMF-handlinger
"dtmfActions"-objektet tildeler DTMF-nøgler eller særlige betingelser til rækker af handlinger:
| DTMF-nøgle | Beskrivelse |
|---|---|
d0 |
Tryk på 0 |
d1 |
Tryk på 1 |
d2 |
Tryk på 2 |
| ... | ... |
d9 |
Tryk på 9 |
d* |
Tryk på * |
d# |
Tryk på # |
forkert |
Udløses, når der trykkes på en ugyldig tast, eller når idleTimeoutMsec nås uden input |
Hver DTMF-nøgle/betingelse er knyttet til en række handlinger, der vil blive udført i rækkefølge.
Understøttede handlinger
| Handling | Parametre | Beskrivelse |
|---|---|---|
webhook |
url (streng, påkrævet)body (objekt, valgfrit)headers (objekt, valgfrit) |
Sender en HTTP POST-anmodning i JSON-format til den angivne URL. 'body'-objektet vil blive indlejret under 'action'-feltet i webhook-anmodningen. Brugerdefinerede headere er inkluderet som HTTP-headere. |
| 'lægge på' | Ingen | Afslutter opkaldet |
gotoMenu |
"menu" (streng eller heltal) | Navigerer opkaldet til en anden menu i menu-arrayet ved hjælp af dets 0-baserede indeks (f.eks. "1") |
Webhook-leveringsformat
Når 'webhook'-handlingen udløses, sender systemet en HTTP POST-anmodning til den konfigurerede 'url' med 'Content-Type: application/json'.
Webhook Request Headers
Hvis handlingen er konfigureret med parameteren "headers", inkluderes disse nøgleværdi-par som HTTP-headere i anmodningen.
Webhook Request Body
JSON-nyttelasten, der sendes til din webhook-URL, har følgende struktur:
| Felt | Skriv | Beskrivelse |
|---|---|---|
fra |
streng | Opkalds telefonnummer / afsender-id |
til |
streng | Modtagerens telefonnummer |
midt |
streng | Meddelelses-id |
handling |
objekt | Det brugerdefinerede JSON-objekt, der er defineret i handlingens "body"-felt |
Komplet eksempel
Simpel IVR med timeout og inputvalidering
{
"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"
}
]
}
}
]
}
]
}
Kompleks IVR med flere menuer og DTMF-routing
Dette eksempel viser, hvordan man definerer flere menuer og navigerer mellem dem ved hjælp af 'gotoMenu'-handlingen, når brugeren indtaster en ugyldig nøgle, eller når opkaldet timeout. Det viser også brugerdefinerede bodies og tilpassede HTTP-headere sendt med webhook-udløsere.
{
"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"
}
]
}
}
]
}
]
}
Svarformat
Successvar
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380936670003",
"status": "sent"
}
]
}
Fejlhåndtering
| HTTP-status | Beskrivelse |
|---|---|
| 200 | Forespørgsel lykkedes |
| 400 | Ugyldigt anmodningsformat |
| 401 | Godkendelse mislykkedes |
| 429 | Satsgrænse overskredet |
| 500 | Intern serverfejl |
cURL Eksempel
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"
}
]
}
}
]
}
]
}'
Bedste praksis
- Lydfiler - Sørg for, at intro-URL'er er tilgængelige, og at lydfiler er i understøttede formater
- Webhook Reliability - Design webhooks til at reagere hurtigt (inden for 2 sekunder)
- DTMF-indstillinger - Begræns menuindstillinger til 4-6 valg for bedre brugeroplevelse
- Timeouthåndtering - Brug
idleTimeoutMsectil at angive brugerdefinerede inaktivitetsgrænser (f.eks. 10000 ms), og konfigurer en yndefuld fallback under den "forkerte" DTMF-tast (som at gentage menuen eller lægge på) - Multi-Menu Call Flow - Brug
gotoMenuomhyggeligt for at forhindre uendelige sløjfer, når du dirigerer brugere tilbage til tidligere menuer - Fallback-strategi - Brug reservemeddelelser til brugere, der ikke svarer eller afbryder forbindelsen
Relaterede emner
- Send besked - Generel vejledning til afsendelse af beskeder
- Flash Call - Simple stemmebekræftelsesopkald
- Kontroller status - Spor leveringsstatus for beskeder
- Meddelelsestyper - Oversigt over alle understøttede meddelelsestyper