Puhepuheluviestit
SpeechCall on interaktiivinen äänivastaus (IVR) -viestityyppi, jonka avulla voit soittaa automaattisia äänipuheluita valikkovaihtoehdoilla ja DTMF (dual-tone multi-frequency) -vuorovaikutuksella.
Yleiskatsaus
SpeechCall antaa yrityksille mahdollisuuden: - Soita automaattisia äänipuheluita asiakkaille - Toista johdattelevia ääniviestejä - Esitä interaktiiviset valikkovaihtoehdot - Käsittele DTMF-näppäinpainalluksia (0-9, *, #) - Määritä mukautettu toiminta kelpaamattomille/aikakatkaisutuloille - Käynnistä webhookeja mukautetuilla rungoilla ja otsikoilla käyttäjien valintojen perusteella - Hallitse puhelunkulkua dynaamisesti (navigoi valikkojen välillä)
Käyttötapaukset
- Asiakaskyselyt - Kerää palautetta puhelimen valikon vaihtoehtojen kautta
- Ajanvarausmuistutukset - Vahvista tai siirrä ajasta puheenvuorolla
- Tilauksen seuranta - Tarjoa tilauksen tilapäivityksiä
- Interaktiiviset ilmoitukset - Toimita tärkeitä tietoja toimintavaihtoehdoilla
- Voice Verification - Monivaiheinen todennus äänipuheluilla
Pyydä muotoa
Perusrakenne
{
"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"
}
]
}
}
]
}
]
}
Parametrin kuvaus
| Parametri | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
| "alkaen" | merkkijono | Kyllä | Lähettäjän tunniste (alfa nimi tai tunnus) |
| "to" | merkkijono | Kyllä | Vastaanottajan puhelinnumero kansainvälisessä muodossa |
| "teksti" | merkkijono | Kyllä | Tekstiarvo, yleensä "ivr" SpeechCallille |
| "tyyppi" | merkkijono | Kyllä | Täytyy olla "speechcall" |
| "valikko" | joukko | Kyllä | Joukko valikkokokoonpanoja puhelulle |
Valikkoasetukset
Jokainen valikkoobjekti sisältää:
| Parametri | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
| "introUrl" | merkkijono | Kyllä | Johdantoäänitiedoston URL-osoite tai tunniste |
idleTimeoutMsec |
kokonaisluku | Ei | Aikakatkaisu millisekunteina odottaa näppäinpainallusta (esim. "10000"). Jos käyttäjä ei vastaa, "wrong"-näppäimellä määritetyt toimet suoritetaan |
| `dtmfActions' | esine | Kyllä | Kartta DTMF-avaimista toimintoihin |
DTMF-toiminnot
Objekti "dtmfActions" kartoittaa DTMF-avaimet tai erikoisehdot toimintoryhmiin:
| DTMF-avain | Kuvaus |
|---|---|
| "d0" | Paina 0 |
| "d1" | Paina 1 |
| "d2" | Paina 2 |
| ... | ... |
| "d9" | Paina 9 |
d* |
Paina * |
d# |
Paina # |
| "väärin" | Laukaisee, kun painetaan virheellistä näppäintä tai kun "idleTimeoutMsec" saavutetaan ilman syöttöä |
Jokainen DTMF-avain/ehto kartoitetaan joukkoon toimintoja, jotka suoritetaan peräkkäin.
Tuetut toiminnot
| Toiminta | Parametrit | Kuvaus |
|---|---|---|
| "webhook" | "url" (merkkijono, pakollinen) "body" (objekti, valinnainen) "otsikot" (objekti, valinnainen) |
Lähettää HTTP POST -pyynnön JSON-muodossa määritettyyn URL-osoitteeseen. "body"-objekti sisällytetään webhook-pyynnön "action"-kentän alle. Mukautetut otsikot sisältyvät HTTP-otsikoiksi. |
| 'katkaistaan' | Ei yhtään | Lopettaa puhelun |
gotoMenu |
"valikko" (merkkijono tai kokonaisluku) | Siirtää kutsun toiseen valikkoon "menu"-taulukossa käyttämällä sen 0-pohjaista indeksiä (esim. "1") |
Webhook-toimitusmuoto
Kun "webhook"-toiminto käynnistetään, järjestelmä lähettää HTTP POST -pyynnön määritettyyn "url"-osoitteeseen, jossa on "Content-Type: application/json".
Webhook-pyyntöotsikot
Jos toiminto on määritetty headers-parametrilla, kyseiset avain-arvo-parit sisällytetään pyyntöön HTTP-otsikoina.
Webhook-pyyntöteksti
Webhook-URL-osoitteeseen lähetetyllä JSON-hyötykuormalla on seuraava rakenne:
| Kenttä | Tyyppi | Kuvaus |
|---|---|---|
| "alkaen" | merkkijono | Soittajan puhelinnumero / Lähettäjätunnus |
| "to" | merkkijono | Vastaanottajan puhelinnumero |
| "keski" | merkkijono | Viestin tunnus |
| "toiminta" | esine | Toiminnon body-kentässä määritetty mukautettu JSON-objekti |
Täydellinen esimerkki
Yksinkertainen IVR aikakatkaisulla ja syötteen validoinnilla
{
"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"
}
]
}
}
]
}
]
}
Monimutkainen IVR useilla valikoilla ja DTMF-reitityksellä
Tämä esimerkki osoittaa, kuinka määritellä useita valikkoja ja navigoida niiden välillä käyttämällä "gotoMenu" -toimintoa, kun käyttäjä syöttää virheellisen näppäimen tai kun puhelun aikakatkaisu. Se näyttää myös mukautetut rungot ja mukautetut HTTP-otsikot, jotka lähetetään webhook-laukaisimien kanssa.
{
"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"
}
]
}
}
]
}
]
}
Vastausmuoto
Menestysvastaus
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380936670003",
"status": "sent"
}
]
}
Virheiden käsittely
| HTTP-tila | Kuvaus |
|---|---|
| 200 | Pyyntö onnistui |
| 400 | Virheellinen pyynnön muoto |
| 401 | Todennus epäonnistui |
| 429 | Hintaraja ylitetty |
| 500 | Sisäinen palvelinvirhe |
cURL-esimerkki
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"
}
]
}
}
]
}
]
}'
Parhaat käytännöt
- Äänitiedostot - Varmista, että johdannon URL-osoitteet ovat käytettävissä ja äänitiedostot ovat tuetuissa muodoissa
- Webhookin luotettavuus – Suunnittele webhookit reagoimaan nopeasti (2 sekunnissa)
- DTMF-asetukset - Rajoita valikon vaihtoehtoja 4-6 vaihtoehtoon paremman käyttökokemuksen saavuttamiseksi
- Aikakatkaisun käsittely – Määritä mukautetut toimettomuusrajoitukset (esim. 10 000 ms) käyttämällä parametria "idleTimeoutMsec" ja määritä "väärän" DTMF-näppäimen alle siro varmistus (kuten valikon toistaminen tai puhelun katkaiseminen).
- Multi-Menu Call Flow - Käytä "gotoMenu"-toimintoa varovasti estääksesi loputtomat silmukat reitittäessäsi käyttäjiä takaisin edellisiin valikoihin
- Varastrategia – Käytä varaviestejä käyttäjille, jotka eivät vastaa tai katkaise yhteyttä
Aiheeseen liittyviä aiheita
- Lähetä viesti - Yleinen viestin lähetysopas
- Flash Call - Yksinkertaiset äänivahvistuspuhelut
- Tarkista tila - Seuraa viestin toimituksen tilaa
- Viestityypit - Yleiskatsaus kaikista tuetuista viestityypeistä