SpeechCall-berichten
SpeechCall is een interactief voice response-berichttype (IVR) waarmee u geautomatiseerde spraakoproepen kunt maken met menuopties en DTMF-interacties (dual-tone multi-frequency).
Overzicht
Met SpeechCall kunnen bedrijven:
- Voer geautomatiseerde spraakoproepen naar klanten
- Speel inleidende audioberichten af
- Presenteer interactieve menu-opties
- Behandel DTMF-toetsaanslagreacties (0-9, *, #)
- Definieer aangepast gedrag voor ongeldige/time-outinvoer
- Activeer webhooks met aangepaste hoofdteksten en headers op basis van gebruikersselecties
- Beheer de oproepstroom dynamisch (navigeer tussen menu’s)
Gebruiksscenario’s
- Klantenonderzoeken - Verzamel feedback via telefoonmenu-opties
- Afspraakherinneringen - Bevestig of verplaats uw afspraak met steminteractie
- Bestellingen volgen - Geef updates van de bestelstatus
- Interactieve meldingen - Lever belangrijke informatie met actie-opties
- Spraakverificatie - Multi-factor authenticatie via spraakoproepen
Verzoekformaat
Basisstructuur
{
"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"
}
]
}
}
]
}
]
}
Parameterbeschrijving
| Parameter | Typ | Vereist | Beschrijving |
|---|---|---|---|
van | tekenreeks | Ja | Afzender-ID (alfanaam of ID) |
naar | tekenreeks | Ja | Telefoonnummer van de ontvanger in internationaal formaat |
tekst | tekenreeks | Ja | Tekstwaarde, meestal ‘ivr’ voor SpeechCall |
type | tekenreeks | Ja | Moet "toespraak" zijn |
menu | array | Ja | Array van menuconfiguraties voor de oproep |
Menuconfiguratie
Elk menu-object bevat:
| Parameter | Typ | Vereist | Beschrijving |
|---|---|---|---|
introUrl | tekenreeks | Ja | URL of identificatie van het inleidende audiobestand |
idleTimeoutMsec | geheel getal | Nee | Time-out in milliseconden om te wachten op een toetsaanslag (bijvoorbeeld 10000). Als de gebruiker niet reageert, worden de acties uitgevoerd die zijn geconfigureerd onder de verkeerde sleutel |
dtmfActions | voorwerp | Ja | Kaart met DTMF-sleutels voor acties |
DTMF-acties
Het object dtmfActions wijst DTMF-sleutels of speciale voorwaarden toe aan reeksen acties:
| DTMF-sleutel | Beschrijving |
|---|---|
d0 | Druk op 0 |
d1 | Druk op 1 |
d2 | Druk op 2 |
| … | … |
d9 | Druk op 9 |
d* | Druk op * |
d# | Druk op # |
verkeerd | Wordt geactiveerd wanneer een ongeldige toets wordt ingedrukt of wanneer idleTimeoutMsec wordt bereikt zonder enige invoer |
Elke DTMF-sleutel/voorwaarde verwijst naar een reeks acties die achtereenvolgens worden uitgevoerd.
Ondersteunde acties
| Actie | Parameters | Beschrijving |
|---|---|---|
webhook | url (tekenreeks, vereist)body (object, optioneel)headers (object, optioneel) | Verzendt een HTTP POST-verzoek in JSON-indeling naar de opgegeven URL. Het body-object wordt genest onder het action-veld in de webhookaanvraag. Aangepaste headers zijn opgenomen als HTTP-headers. |
ophangen | Geen | Beëindigt het gesprek |
ga naarMenu | menu (tekenreeks of geheel getal) | Navigeer door de oproep naar een ander menu in de menu array met behulp van de op 0 gebaseerde index (bijvoorbeeld "1") |
Gedetailleerd actiegedrag
Webhook-actie (webhook)
De actie webhook verzendt een HTTP POST-verzoek naar uw callback-URL met de metagegevens van de oproep en optionele aangepaste gegevens:
- Als er een
bodywordt opgegeven, worden de sleutel-waardeparen ervan binnen hetaction-veld van de payload-body verzonden. - Als er ‘headers’ zijn opgegeven, worden deze als aangepaste HTTP-headers in het verzoek verzonden.
Ophangactie (ophangen)
De actie ‘ophangen’ beëindigt het actieve gesprek onmiddellijk. Na een actie ‘ophangen’ worden geen verdere acties in de reeks of menu’s verwerkt.
Ga naar menuactie (“gotoMenu”)
De actie gotoMenu leidt de stroom van de oproep om naar een andere menustructuur binnen de menu-array. Er is een enkele parameter menu nodig die de op 0 gebaseerde index van het doelmenu specificeert (bijvoorbeeld 1 om naar het tweede menu te gaan, of 0 om het eerste menu opnieuw te starten).
Inactiviteit en foutafhandeling (“verkeerd”)
De verkeerde sleutel in dtmfActions is een speciale fallthrough-handler. Het voert zijn reeks acties uit in twee scenario’s:
- Ongeldige invoer: de beller drukt op een DTMF-toets die niet is gedefinieerd in
dtmfActions(ze drukken bijvoorbeeld op3maar het menu definieert alleend1end2). - Time-out bij inactiviteit: De beller drukt op geen enkele toets binnen de tijdsduur gespecificeerd door
idleTimeoutMsec.
Als ‘verkeerd’ niet is gedefinieerd en de beller op een ongeldige toets drukt of een time-out optreedt, wordt de gespreksstroom standaard ophangen. Door fout te definiëren, kunt u lusmenu’s bouwen (bijvoorbeeld teruggaan naar hetzelfde menu met "action": "gotoMenu", "menu": "0") of de gebruiker omleiden naar een helpmenu.
Webhook-leveringsformaat
Wanneer de actie webhook wordt geactiveerd, verzendt het systeem een HTTP POST-verzoek naar de geconfigureerde url met Content-Type: application/json.
Webhook-verzoekheaders
Als de actie is geconfigureerd met de parameter headers, worden deze sleutel-waardeparen als HTTP-headers in het verzoek opgenomen.
Webhookverzoektekst
De JSON-payload die naar uw webhook-URL wordt verzonden, heeft de volgende structuur:
{
"from": "0443914272",
"to": "50001",
"mid": "7748021",
"action": {
"confirm": true
}
}
| Veld | Typ | Beschrijving |
|---|---|---|
van | tekenreeks | Telefoonnummer beller/afzender-ID |
naar | tekenreeks | Telefoonnummer ontvanger |
midden | tekenreeks | Bericht-ID |
actie | voorwerp | Het aangepaste JSON-object dat is gedefinieerd in het body-veld |
Compleet voorbeeld
Eenvoudige IVR met time-out en invoervalidatie
{
"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"
}
]
}
}
]
}
]
}
Complexe IVR met meerdere menu’s en DTMF-routering
Dit voorbeeld demonstreert hoe u meerdere menu’s definieert en ertussen navigeert met behulp van de actie gotoMenu wanneer de gebruiker een ongeldige sleutel invoert of wanneer de oproep een time-out heeft. Het toont ook aangepaste hoofdteksten en aangepaste HTTP-headers die met de webhooktriggers zijn verzonden.
{
"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"
}
]
}
}
]
}
]
}
Antwoordformaat
Succesreactie
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380XXXXXXXXX",
"status": "sent"
}
]
}
Foutafhandeling
| HTTP-status | Beschrijving |
|---|---|
| 200 | Aanvraag succesvol |
| 400 | Ongeldig verzoekformaat |
| 401 | Authenticatie mislukt |
| 429 | Tarieflimiet overschreden |
| 500 | Interne serverfout |
cURL-voorbeeld
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"
}
]
}
}
]
}
]
}'
Beste praktijken
- Audiobestanden - Zorg ervoor dat intro-URL’s toegankelijk zijn en dat audiobestanden de ondersteunde indelingen hebben
- Webhook-betrouwbaarheid - Ontwerp webhooks om snel te reageren (binnen 2 seconden)
- DTMF-opties - Beperk menu-opties tot 4-6 keuzes voor een betere gebruikerservaring
- Time-outafhandeling - Gebruik
idleTimeoutMsecom aangepaste inactiviteitslimieten op te geven (bijvoorbeeld 10.000 ms), en configureer een elegante terugval onder deverkeerdeDTMF-sleutel (zoals het herhalen van het menu of ophangen) - Multi-Menu Call Flow - Gebruik
gotoMenuzorgvuldig om oneindige lussen te voorkomen bij het terugsturen van gebruikers naar vorige menu’s - Fallback-strategie - Gebruik fallback-berichten voor gebruikers die niet opnemen of de verbinding verbreken
Gerelateerde onderwerpen
- Bericht verzenden - Algemene handleiding voor het verzenden van berichten
- Flash Call - Eenvoudige spraakverificatieoproepen
- Status controleren - Volg de bezorgingsstatus van berichten
- Berichttypen - Overzicht van alle ondersteunde berichttypen