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": "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"
}
]
}
}
]
}
]
}
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“) |
Detailliertes Aktionsverhalten
Webhook-Aktion („Webhook“)
Die Aktion „Webhook“ sendet eine HTTP-POST-Anfrage an Ihre Rückruf-URL mit den Anrufmetadaten und optionalen benutzerdefinierten Daten:
- Wenn ein „Körper“ bereitgestellt wird, werden seine Schlüssel-Wert-Paare im Feld „Aktion“ des Nutzlastkörpers gesendet. – Wenn „Header“ bereitgestellt werden, werden sie als benutzerdefinierte HTTP-Header in der Anfrage gesendet.
Auflegeaktion (hangup)
Die Aktion „Auflegen“ beendet den aktiven Anruf sofort. Nach einer „Auflegen“-Aktion werden keine weiteren Aktionen in der Sequenz oder den Menüs verarbeitet.
Gehe zur Menüaktion („gotoMenu“)
Die Aktion „gotoMenu“ leitet den Aufruffluss zu einer anderen Menüstruktur innerhalb des „menu“-Arrays um. Es benötigt einen einzelnen Parameter „menu“, der den 0-basierten Index des Zielmenüs angibt (z. B. „1“, um zum zweiten Menü zu gelangen, oder „0“, um das erste Menü neu zu starten).
Inaktivität und Fehlerbehandlung („falsch“)
Der „falsche“ Schlüssel in „dtmfActions“ ist ein spezieller Fallthrough-Handler. Es führt seine Reihe von Aktionssequenzen in zwei Szenarien aus:
- Ungültige Eingabe: Der Anrufer drückt eine DTMF-Taste, die nicht in „dtmfActions“ definiert ist (z. B. drückt er „3“, aber das Menü definiert nur „d1“ und „d2“).
- Idle Timeout: Der Anrufer drückt innerhalb der durch „idleTimeoutMsec“ angegebenen Dauer keine Taste.
Wenn „falsch“ nicht definiert ist und der Anrufer eine ungültige Taste drückt oder eine Zeitüberschreitung auftritt, wird der Anrufverlauf standardmäßig aufgelegt. Durch die Definition von „falsch“ können Sie Schleifenmenüs erstellen (z. B. mit „action“: „gotoMenu“, „menu“: „0“ zum gleichen Menü zurückkehren) oder den Benutzer zu einem Hilfemenü umleiten.
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:
{
"from": "0443914272",
"to": "50001",
"mid": "7748021",
"action": {
"confirm": true
}
}
| 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": "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"
}
]
}
}
]
}
]
}
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_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"
}
]
}
}
]
}
]
}
Antwortformat
Erfolgsantwort
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380XXXXXXXXX",
"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_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"
}
]
}
}
]
}
]
}'
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