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": "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"
}
]
}
}
]
}
]
}
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") |
Detaljeret handlingsadfærd
Webhook Action (webhook)
"Webhook"-handlingen sender en HTTP POST-anmodning til din tilbagekalds-URL med opkaldets metadata og valgfri tilpassede data: - Hvis en "body" er angivet, sendes dens nøgleværdi-par inde i "action"-feltet i nyttelastlegemet. - Hvis "headere" er angivet, sendes de som tilpassede HTTP-headere i anmodningen.
Læg på handling ("læg på")
"Læg på"-handlingen afslutter det aktive opkald med det samme. Ingen yderligere handlinger i sekvensen eller menuerne vil blive behandlet efter en "afslut"-handling.
Gå til menuhandling (gotoMenu)
'gotoMenu'-handlingen omdirigerer strømmen af opkaldet til en anden menustruktur i 'menu'-arrayet. Det kræver en enkelt parameter menu, som specificerer det 0-baserede indeks for målmenuen (f.eks. "1" for at gå til den anden menu, eller "0" for at genstarte den første menu).
Inaktivitet og fejlhåndtering ('forkert')
Den 'forkerte' nøgle inde i 'dtmfActions' er en speciel fallthrough-handler. Den udfører sin række af handlingssekvenser i to scenarier:
1. Ugyldig input: Den, der ringer, trykker på en DTMF-tast, der ikke er defineret i dtmfActions (de trykker f.eks. 3 men menuen definerer kun d1 og d2).
2. Idle Timeout: Den, der ringer op, trykker ikke på nogen tast inden for den varighed, der er angivet af idleTimeoutMsec.
Hvis 'forkert' ikke er defineret, og den, der ringer, trykker på en ugyldig tast eller timeout, vil opkaldsstrømmen lægge på som standard. Ved at definere forkert kan du bygge loop-menuer (f.eks. gå tilbage til den samme menu med "action": "gotoMenu", "menu": "0") eller omdirigere brugeren til en hjælpemenu.
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": "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"
}
]
}
}
]
}
]
}
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_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"
}
]
}
}
]
}
]
}
Svarformat
Successvar
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380XXXXXXXXX",
"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_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"
}
]
}
}
]
}
]
}'
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