SpeechCall-Nachrichten
SpeechCall ist ein interaktiver Sprachantwort-Nachrichtentyp (IVR), der es Ihnen ermöglicht, automatisierte Sprachanrufe mit Menüoptionen und DTMF-Interaktionen (Dual-Tone Multi-Frequency) zu tätigen.
Übersicht
SpeechCall ermöglicht Unternehmen Folgendes: - Tätigen Sie automatisierte Sprachanrufe an Kunden - Spielen Sie einleitende Audionachrichten ab - Präsentieren Sie interaktive Menüoptionen - Behandeln Sie DTMF-Tastendruckantworten (0-9, *, #) - Definieren Sie benutzerdefiniertes Verhalten für ungültige/Timeout-Eingaben - Lösen Sie Webhooks mit benutzerdefinierten Texten und Headern basierend auf der Benutzerauswahl aus - Anruffluss dynamisch verwalten (zwischen Menüs navigieren)
Anwendungsfälle
- Kundenumfragen – Sammeln Sie Feedback über Telefonmenüoptionen
- Terminerinnerungen – Bestätigen oder verschieben Sie den Termin per Sprachinteraktion
- Auftragsverfolgung – Bereitstellung von Aktualisierungen des Bestellstatus
- Interaktive Benachrichtigungen – Liefern Sie wichtige Informationen mit Aktionsoptionen
- Sprachverifizierung – Multi-Faktor-Authentifizierung über Sprachanrufe
Anforderungsformat
Grundstruktur
{
"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"
}
]
}
}
]
}
]
}
Parameterbeschreibung
| Parameter | Geben Sie | ein Erforderlich | Beschreibung |
|---|---|---|---|
| „von“ | Zeichenfolge | Ja | Absender-ID (Alpha-Name oder ID) |
| „zu“ | Zeichenfolge | Ja | Telefonnummer des Empfängers im internationalen Format |
Text |
Zeichenfolge | Ja | Textwert, normalerweise „ivr“ für SpeechCall |
| „Typ“ | Zeichenfolge | Ja | Muss „speechcall“ sein |
Menü |
Array | Ja | Array von Menükonfigurationen für den Aufruf |
Menükonfiguration
Jedes Menüobjekt enthält:
| Parameter | Geben Sie | ein Erforderlich | Beschreibung |
|---|---|---|---|
introUrl |
Zeichenfolge | Ja | URL oder Kennung der einführenden Audiodatei |
idleTimeoutMsec |
Ganzzahl | Nein | Timeout in Millisekunden, um auf einen Tastendruck zu warten (z. B. „10000“). Wenn der Benutzer nicht antwortet, werden die unter der Taste „falsch“ konfigurierten Aktionen ausgeführt |
dtmfActions |
Objekt | Ja | Zuordnung von DTMF-Tasten zu Aktionen |
DTMF-Aktionen
Das Objekt „dtmfActions“ ordnet DTMF-Tasten oder Sonderbedingungen Arrays von Aktionen zu:
| DTMF-Taste | Beschreibung |
|---|---|
d0 |
Drücken Sie 0 |
d1 |
Drücken Sie 1 |
d2 |
Drücken Sie 2 |
| ... | ... |
d9 |
Drücken Sie 9 |
d* |
Drücken Sie * |
d# |
Drücken Sie # |
| „falsch“ | Wird ausgelöst, wenn eine ungültige Taste gedrückt wird oder wenn „idleTimeoutMsec“ ohne Eingabe erreicht wird |
Jede DTMF-Taste/Bedingung ist einem Array von Aktionen zugeordnet, die nacheinander ausgeführt werden.
Unterstützte Aktionen
| Aktion | Parameter | Beschreibung |
|---|---|---|
Webhook |
url (Zeichenfolge, erforderlich)body (Objekt, optional)headers (Objekt, optional) |
Sendet eine HTTP-POST-Anfrage im JSON-Format an die angegebene URL. Das „body“-Objekt wird unter dem „action“-Feld in der Webhook-Anfrage verschachtelt. Benutzerdefinierte Header sind als HTTP-Header enthalten. |
| „Auflegen“ | Keine | Beendet den Anruf |
gotoMenu |
menu (Zeichenfolge oder Ganzzahl) |
Navigiert den Aufruf zu einem anderen Menü im Array „menu“ unter Verwendung seines 0-basierten Index (z. B. „1“) |
Webhook-Übermittlungsformat
Wenn die Aktion „Webhook“ ausgelöst wird, sendet das System eine HTTP-POST-Anfrage an die konfigurierte „URL“ mit „Content-Type: application/json“.
Webhook-Anforderungsheader
Wenn die Aktion mit dem Parameter „headers“ konfiguriert ist, werden diese Schlüssel-Wert-Paare als HTTP-Header in die Anfrage einbezogen.
Webhook-Anfragetext
Die an Ihre Webhook-URL gesendete JSON-Nutzlast hat die folgende Struktur:
| Feld | Geben Sie | ein Beschreibung |
|---|---|---|
| „von“ | Zeichenfolge | Telefonnummer des Anrufers / Absender-ID |
| „zu“ | Zeichenfolge | Telefonnummer des Empfängers |
| „Mitte“ | Zeichenfolge | Nachrichten-ID |
| „Aktion“ | Objekt | Das benutzerdefinierte JSON-Objekt, das im Feld „body“ der Aktion |
Vollständiges Beispiel
Einfaches IVR mit Timeout und Eingabevalidierung
{
"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"
}
]
}
}
]
}
]
}
Komplexes IVR mit mehreren Menüs und DTMF-Routing
Dieses Beispiel zeigt, wie Sie mehrere Menüs definieren und mithilfe der Aktion „gotoMenu“ zwischen ihnen navigieren, wenn der Benutzer eine ungültige Taste eingibt oder der Aufruf abläuft. Außerdem werden benutzerdefinierte Textkörper und benutzerdefinierte HTTP-Header angezeigt, die mit den Webhook-Triggern gesendet werden.
{
"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"
}
]
}
}
]
}
]
}
Antwortformat
Erfolgsantwort
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380936670003",
"status": "sent"
}
]
}
Fehlerbehandlung
| HTTP-Status | Beschreibung |
|---|---|
| 200 | Anfrage erfolgreich |
| 400 | Ungültiges Anfrageformat |
| 401 | Authentifizierung fehlgeschlagen |
| 429 | Ratenlimit überschritten |
| 500 | Interner Serverfehler |
cURL-Beispiel
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"
}
]
}
}
]
}
]
}'
Best Practices
- Audiodateien – Stellen Sie sicher, dass die Einführungs-URLs zugänglich sind und die Audiodateien in unterstützten Formaten vorliegen
- Webhook-Zuverlässigkeit – Entwerfen Sie Webhooks so, dass sie schnell reagieren (innerhalb von 2 Sekunden).
- DTMF-Optionen – Beschränken Sie die Menüoptionen für ein besseres Benutzererlebnis auf 4–6 Auswahlmöglichkeiten
- Zeitüberschreitungsbehandlung – Verwenden Sie „idleTimeoutMsec“, um benutzerdefinierte Inaktivitätsgrenzen festzulegen (z. B. 10.000 ms) und konfigurieren Sie einen eleganten Fallback unter der „falschen“ DTMF-Taste (z. B. das Wiederholen des Menüs oder das Auflegen).
- Anrufablauf für mehrere Menüs – Verwenden Sie „gotoMenu“ sorgfältig, um Endlosschleifen zu vermeiden, wenn Benutzer zu vorherigen Menüs zurückgeleitet werden
- Fallback-Strategie – Verwenden Sie Fallback-Nachrichten für Benutzer, die nicht antworten oder die Verbindung trennen
Verwandte Themen
- Nachricht senden – Allgemeine Anleitung zum Senden von Nachrichten
- Flash Call – Einfache Anrufe zur Sprachbestätigung
- Status prüfen – Verfolgen Sie den Nachrichtenübermittlungsstatus
- Nachrichtentypen – Übersicht aller unterstützten Nachrichtentypen