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": "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"
}
]
}
}
]
}
]
}
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”) |
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:
| 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": "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 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_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"
}
]
}
}
]
}
]
}
Válaszformátum
Sikerreakció
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380936670003",
"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_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"
}
]
}
}
]
}
]
}'
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