SpeechCall üzenetek
A SpeechCall egy interaktív hangválasz (IVR) üzenettípus, amely lehetővé teszi automatizált hanghívások indítását menüopciókkal és DTMF (kéthangú többfrekvenciás) interakciókkal.
Áttekintés
A SpeechCall lehetővé teszi a vállalkozások számára, hogy:
- Automatikus hanghívásokat kezdeményezhet az ügyfeleknek
- Bevezető hangüzenetek lejátszása
- Interaktív menüopciók bemutatása
- Kezelje a DTMF billentyűleütési válaszokat (0-9, *, #)
- Egyéni viselkedés meghatározása az érvénytelen/időtúllépési bemenetekhez
- Webhookok aktiválása egyéni törzsekkel és fejlécekkel a felhasználói választások alapján
- A hívásfolyam dinamikus kezelése (navigálás a menük között)
Használati esetek
- Ügyfélfelmérések - Visszajelzés gyűjtése a telefonos menüopciókon keresztül
- Találkozó emlékeztetők - Hangos interakcióval erősítse meg vagy ütemezze át
- Rendeléskövetés - Megrendelés állapotfrissítések biztosítása
- Interaktív értesítések - Fontos információk továbbítása műveleti lehetőségekkel
- Hangellenőrzés - Többtényezős hitelesítés hanghívásokkal
Formátum kérése
Alapfelépítés
{
"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"
}
]
}
}
]
}
]
}
Paraméter leírása
| Paraméter | Típus | Kötelező | Leírás |
|---|---|---|---|
| ”tól” | húr | Igen | Feladó azonosítója (alfa név vagy azonosító) |
| “hoz” | húr | Igen | Címzett telefonszáma nemzetközi formátumban |
| ”szöveg” | húr | Igen | Szöveges érték, jellemzően “ivr” a SpeechCall |
| ”típus” | húr | Igen | A következőnek kell lennie: "beszédhívás" |
| ”menü” | tömb | Igen | Menükonfigurációk tömbje a híváshoz |
Menü konfiguráció
Minden menüelem a következőket tartalmazza:
| Paraméter | Típus | Kötelező | Leírás |
|---|---|---|---|
introUrl | húr | Igen | A bevezető hangfájl URL-je vagy azonosítója |
idleTimeoutMsec | egész | Nem | Időtúllépés ezredmásodpercben a gombnyomásra való várakozáshoz (pl. „10000”). Ha a felhasználó nem válaszol, a “rossz” kulcs alatt beállított műveletek végrehajtásra kerülnek |
| ”dtmfActions” | tárgy | Igen | A műveletekhez tartozó DTMF-kulcsok térképe |
DTMF-műveletek
A “dtmfActions” objektum a DTMF kulcsokat vagy speciális feltételeket művelettömbökhöz rendeli hozzá:
| DTMF kulcs | Leírás |
|---|---|
| ”d0” | Nyomja meg a 0 |
| ”d1” | Nyomja meg az 1 |
| ”d2” | Nyomja meg a 2 |
| … | … |
| “d9” | Nyomja meg a 9 |
d* | Nyomja meg a * |
d# | Nyomja meg a # |
rossz | Akkor aktiválódik, ha érvénytelen billentyűt lenyomnak, vagy ha az `idleTimeoutMsec’ értéket minden bevitel nélkül elérjük |
Minden DTMF-kulcs/feltétel műveletek tömbjére van leképezve, amelyek egymás után kerülnek végrehajtásra.
Támogatott műveletek
| Akció | Paraméterek | Leírás |
|---|---|---|
webhook | url (karakterlánc, kötelező)body (objektum, nem kötelező)fejlécek (objektum, nem kötelező) | HTTP POST kérést küld JSON formátumban a megadott URL-re. A „body” objektum a webhook-kérés „action” mezője alá lesz ágyazva. Az egyéni fejlécek HTTP-fejlécként szerepelnek. |
| `lefagy’ | Nincs | Befejezi a hívást |
gotoMenu | ”menü” (karakterlánc vagy egész) | A hívást a „menu” tömb másik menüjébe navigálja a 0-alapú index használatával (pl. „1”) |
Részletes cselekvési viselkedés
Webhook-művelet (webhook)
A “webhook” művelet HTTP POST kérést küld a visszahívási URL-címére a hívás metaadataival és az opcionális egyéni adatokkal együtt:
- Ha egy “törzs” van megadva, akkor a kulcs-érték párjai a hasznos tehertörzs “action” mezőjébe kerülnek.
- Ha „fejlécek” vannak megadva, akkor azok egyéni HTTP-fejlécként kerülnek elküldésre a kérésben.
Hangbontási művelet (“lehangolás”)
A hangup művelet azonnal leállítja az aktív hívást. A szekvenciában vagy a menükben semmilyen további művelet nem kerül feldolgozásra a „megszakítási” művelet után.
Ugrás a Menüművelethez (gotoMenu)
A “gotoMenu” művelet átirányítja a hívás folyamatát egy másik menüszerkezetre a “menu” tömbön belül. Egyetlen “menu” paraméterre van szükség, amely megadja a célmenü 0-alapú indexét (pl. “1” a második menü eléréséhez, vagy “0” az első menü újraindításához).
Inaktivitás és hibakezelés (rossz)
A dtmfActions-ben található rossz kulcs egy speciális áttöréskezelő. A műveletsorozatot két forgatókönyv szerint hajtja végre:
- Érvénytelen bevitel: A hívó olyan DTMF-billentyűt nyom meg, amely nincs definiálva a “dtmfActions”-ben (például megnyomja a “3”-at, de a menü csak a “d1” és “d2” karakterláncot határozza meg).
- Idle Timeout: A hívó nem nyom le egyetlen gombot sem az “idleTimeoutMsec” által meghatározott időtartamon belül.
Ha a “rossz” nincs megadva, és a hívó érvénytelen gombot nyom meg, vagy időtúllépés lép fel, a hívásfolyam alapértelmezés szerint leáll. A rossz definiálása lehetővé teszi hurokmenük létrehozását (pl. visszalépés ugyanabba a menübe az "action": "gotoMenu", "menu": "0" kifejezéssel), vagy a felhasználó átirányítása egy súgómenübe.
Webhook kézbesítési formátum
Amikor a „webhook” művelet aktiválódik, a rendszer HTTP POST kérést küld a beállított „url” címre a „Content-Type: application/json” paraméterrel.
Webhook kérés fejlécei
Ha a művelet a “headers” paraméterrel van konfigurálva, akkor ezek a kulcs-érték párok HTTP-fejlécként szerepelnek a kérésben.
Webhook kérés törzse
A webhook URL-címére küldött JSON-adattartalom a következő szerkezettel rendelkezik:
{
"from": "0443914272",
"to": "50001",
"mid": "7748021",
"action": {
"confirm": true
}
}
| Mező | Típus | Leírás |
|---|---|---|
| ”tól” | húr | Hívó telefonszáma / Feladó azonosítója |
| ”hoz” | húr | Címzett telefonszáma |
| ”közép” | húr | Üzenetazonosító |
| ”cselekvés” | tárgy | A művelet “body” mezőjében meghatározott egyéni JSON-objektum |
Teljes példa
Egyszerű IVR időtúllépéssel és beviteli ellenőrzéssel
{
"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 több menüvel és DTMF-útválasztással
Ez a példa bemutatja, hogyan definiálhat több menüt, és hogyan navigálhat közöttük a „gotoMenu” művelettel, amikor a felhasználó érvénytelen billentyűt ad meg, vagy amikor a hívás időtúllépése történik. Ezenkívül megjeleníti a webhook-indítókkal küldött egyéni törzseket és egyéni HTTP-fejléceket is.
{
"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"
}
]
}
}
]
}
]
}
Válaszformátum
Sikerreakció
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380XXXXXXXXX",
"status": "sent"
}
]
}
Hibakezelés
| HTTP állapot | Leírás |
|---|---|
| 200 | Sikeres kérés |
| 400 | Érvénytelen kérésformátum |
| 401 | A hitelesítés sikertelen |
| 429 | A díjhatár túllépve |
| 500 | Belső szerverhiba |
cURL példa
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"
}
]
}
}
]
}
]
}'
Bevált gyakorlatok
- Hangfájlok – Győződjön meg arról, hogy a bevezető URL-ek elérhetők, és az audiofájlok támogatott formátumúak
- Webhook megbízhatóság – Webhook tervezése, hogy gyorsan (2 másodpercen belül) válaszoljon.
- DTMF-beállítások - A jobb felhasználói élmény érdekében 4-6 lehetőségre korlátozza a menüopciókat
- Időtúllépés kezelése – Használja az „idleTimeoutMsec” parancsot egyéni inaktivitási korlátok megadásához (pl. 10000 ms), és konfiguráljon egy kecses tartalékot a „rossz” DTMF-kulcs alatt (például a menü megismétlése vagy a telefon letétele).
- Multi-Menu Call Flow – Óvatosan használja a „gotoMenu” parancsot, hogy elkerülje a végtelen hurkokat, amikor a felhasználókat visszairányítja az előző menükbe.
- Tartalékstratégia – Tartalék üzenetek használata azoknak a felhasználóknak, akik nem válaszolnak, vagy nem szakítják meg a kapcsolatot
Kapcsolódó témák
- Üzenet küldése - Általános üzenetküldési útmutató
- Flash Call - Egyszerű hangos ellenőrző hívások
- Állapot ellenőrzése - Az üzenet kézbesítési állapotának nyomon követése
- Üzenettípusok - Az összes támogatott üzenettípus áttekintése