SpeechCall-meddelanden
SpeechCall är en interaktiv röstsvarsmeddelandetyp (IVR) som låter dig ringa automatiska röstsamtal med menyalternativ och DTMF (dual-tone multi-frequency) interaktioner.
Översikt
SpeechCall gör det möjligt för företag att: - Ring automatiska röstsamtal till kunder - Spela inledande ljudmeddelanden - Presentera interaktiva menyalternativ - Hantera DTMF-knapptryckssvar (0-9, *, #) - Definiera anpassat beteende för ogiltiga/timeout-ingångar - Utlösa webhooks med anpassade kroppar och rubriker baserat på användarval - Hantera samtalsflödet dynamiskt (navigera mellan menyer)
Användningsfall
- Kundundersökningar - Samla in feedback via telefonmenyalternativ
- Avtalspåminnelser - Bekräfta eller boka om med röstinteraktion
- Beställningsspårning - Ge orderstatusuppdateringar
- Interaktiva meddelanden - Leverera viktig information med åtgärdsalternativ
- Röstverifiering - Multifaktorautentisering via röstsamtal
Begärformat
Grundläggande 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 Beskrivning
| Parameter | Skriv | Krävs | Beskrivning |
|---|---|---|---|
från |
sträng | Ja | Avsändaridentifierare (alfanamn eller ID) |
till |
sträng | Ja | Mottagarens telefonnummer i internationellt format |
text |
sträng | Ja | Textvärde, vanligtvis "ivr" för SpeechCall |
typ |
sträng | Ja | Måste vara "speechcall" |
meny |
array | Ja | Array av menykonfigurationer för samtalet |
Menykonfiguration
Varje menyobjekt innehåller:
| Parameter | Skriv | Krävs | Beskrivning |
|---|---|---|---|
introUrl |
sträng | Ja | URL eller identifierare för den inledande ljudfilen |
idleTimeoutMsec |
heltal | Nej | Timeout i millisekunder för att vänta på en knapptryckning (t.ex. "10000"). Om användaren inte svarar kommer de åtgärder som konfigurerats under "fel" nyckel att utföras |
dtmfActions |
objekt | Ja | Karta över DTMF-nycklar till åtgärder |
DTMF-åtgärder
"dtmfActions"-objektet mappar DTMF-nycklar eller speciella villkor till arrayer av åtgärder:
| DTMF-nyckel | Beskrivning |
|---|---|
d0 |
Tryck på 0 |
d1 |
Tryck på 1 |
d2 |
Tryck på 2 |
| ... | ... |
d9 |
Tryck på 9 |
d* |
Tryck på * |
d# |
Tryck # |
fel |
Utlöses när en ogiltig tangent trycks ned eller när idleTimeoutMsec nås utan någon inmatning |
Varje DTMF-nyckel/villkor mappas till en rad åtgärder som kommer att utföras i sekvens.
Åtgärder som stöds
| Åtgärd | Parametrar | Beskrivning |
|---|---|---|
webhook |
url (sträng, obligatorisk)body (objekt, valfritt)headers (objekt, valfritt) |
Skickar en HTTP POST-begäran i JSON-format till den angivna URL:en. "body"-objektet kommer att kapslas under "action"-fältet i webhook-begäran. Anpassade rubriker ingår som HTTP-rubriker. |
lägg på |
Inga | Avslutar samtalet |
gotoMenu |
meny (sträng eller heltal) |
Navigerar samtalet till en annan meny i meny-arrayen med hjälp av dess 0-baserade index (t.ex. "1") |
Detaljerat åtgärdsbeteende
Webhook Action (webhook)
Åtgärden "webhook" skickar en HTTP POST-begäran till din återuppringnings-URL med samtalsmetadata och valfria anpassade data: - Om en "kropp" tillhandahålls, skickas dess nyckel-värdepar in i "action"-fältet i nyttolastkroppen. - Om "headers" tillhandahålls skickas de som anpassade HTTP-rubriker i begäran.
Lägg på åtgärd ('lägg på')
"Lägg på"-åtgärden avslutar det aktiva samtalet omedelbart. Inga ytterligare åtgärder i sekvensen eller menyerna kommer att bearbetas efter en "lägg på".
Gå till Menyåtgärd (gotoMenu)
Åtgärden gotoMenu omdirigerar flödet av anropet till en annan menystruktur inom meny-arrayen. Det krävs en enstaka parameter meny som specificerar det 0-baserade indexet för målmenyn (t.ex. "1" för att gå till den andra menyn, eller "0" för att starta om den första menyn).
Inaktivitet och felhantering ('fel')
Den felaktiga nyckeln i dtmfActions är en speciell fallthrough-hanterare. Den utför sin uppsättning av handlingssekvenser i två scenarier:
1. Ogiltig inmatning: Den som ringer trycker på en DTMF-tangent som inte är definierad i dtmfActions (de trycker till exempel 3 men menyn definierar bara d1 och d2).
2. Idle Timeout: Den som ringer trycker inte på någon knapp inom den tid som anges av idleTimeoutMsec.
Om "fel" inte är definierat och den som ringer trycker på en ogiltig knapp eller timeout kommer samtalsflödet att lägga på som standard. Genom att definiera fel kan du bygga loopmenyer (t.ex. gå tillbaka till samma meny med "action": "gotoMenu", "menu": "0") eller omdirigera användaren till en hjälpmeny.
Webhook leveransformat
När "webhook"-åtgärden utlöses, skickar systemet en HTTP POST-begäran till den konfigurerade "url" med "Content-Type: application/json".
Webhook Request Headers
Om åtgärden är konfigurerad med parametern "headers", inkluderas dessa nyckel-värdepar som HTTP-huvuden i begäran.
Webhook Request Body
JSON-nyttolasten som skickas till din webhook-URL har följande struktur:
| Fält | Skriv | Beskrivning |
|---|---|---|
från |
sträng | Uppringarens telefonnummer / avsändar-ID |
till |
sträng | Mottagarens telefonnummer |
mitt |
sträng | Meddelande-ID |
åtgärd |
objekt | Det anpassade JSON-objektet definierat i åtgärdens "kropp"-fält |
Komplett exempel
Enkel IVR med Timeout & Input Validation
{
"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"
}
]
}
}
]
}
]
}
Komplex IVR med flera menyer och DTMF-routing
Det här exemplet visar hur man definierar flera menyer och navigerar mellan dem med "gotoMenu"-åtgärden när användaren matar in en ogiltig nyckel eller när samtalet timeout. Den visar också anpassade kroppar och anpassade HTTP-rubriker som skickas med webhook-utlösare.
{
"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"
}
]
}
}
]
}
]
}
Svarsformat
Framgångssvar
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380XXXXXXXXX",
"status": "sent"
}
]
}
Felhantering
| HTTP-status | Beskrivning |
|---|---|
| 200 | Begäran lyckades |
| 400 | Ogiltigt format för begäran |
| 401 | Autentisering misslyckades |
| 429 | Frekvensgränsen har överskridits |
| 500 | Internt serverfel |
cURL Exempel
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"
}
]
}
}
]
}
]
}'
Bästa metoder
- Ljudfiler - Se till att introduktionsadresser är tillgängliga och att ljudfiler är i format som stöds
- Webhook Reliability - Designa webhooks för att svara snabbt (inom 2 sekunder)
- DTMF-alternativ - Begränsa menyalternativen till 4-6 val för bättre användarupplevelse
- Timeout-hantering - Använd "idleTimeoutMsec" för att ange anpassade inaktivitetsgränser (t.ex. 10 000 ms) och konfigurera en graciös reserv under "fel" DTMF-nyckel (som att upprepa menyn eller lägga på)
- Multi-Menu Call Flow - Använd
gotoMenunoggrant för att förhindra oändliga loopar när du dirigerar användare tillbaka till tidigare menyer - Reservstrategi - Använd reservmeddelanden för användare som inte svarar eller kopplar bort
Relaterade ämnen
- Skicka meddelande - Allmän guide för att skicka meddelanden
- Flash Call - Enkla röstverifieringssamtal
- Kontrollera status - Spåra meddelandeleveransstatus
- Meddelandetyper - Översikt över alla meddelandetyper som stöds