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": "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 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") |
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": "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"
}
]
}
}
]
}
]
}
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_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"
}
]
}
}
]
}
]
}
Svarsformat
Framgångssvar
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380936670003",
"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_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"
}
]
}
}
]
}
]
}'
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