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": "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"
}
]
}
}
]
}
]
}
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”) |
Yksityiskohtainen toimintakäyttäytyminen
Webhook-toiminto (webhook)
“Webhook”-toiminto lähettää HTTP POST -pyynnön takaisinsoitto-URL-osoitteeseesi, jossa on puhelun metatiedot ja valinnaiset mukautetut tiedot:
- Jos “body” on annettu, sen avain-arvoparit lähetetään hyötykuorman rungon “toiminta”-kenttään.
- Jos “otsikot” on annettu, ne lähetetään mukautetuina HTTP-otsikoina pyynnössä.
Katkaisutoiminto (“puhelun lopettaminen”)
Katkaisutoiminto lopettaa aktiivisen puhelun välittömästi. Mitään muita toimintoja sarjassa tai valikoissa ei käsitellä puhelun katkaisemisen jälkeen.
Siirry valikkotoimintoon (gotoMenu)
Toiminto “gotoMenu” ohjaa kutsun kulun eri valikkorakenteeseen “menu”-taulukossa. Se vaatii yhden parametrin “menu”, joka määrittää kohdevalikon 0-pohjaisen indeksin (esim. “1” siirtyäksesi toiseen valikkoon tai “0” käynnistääksesi ensimmäisen valikon uudelleen).
Käyttämättömyys ja virheiden käsittely (“väärä”)
Väärä avain dtmfActionsin sisällä on erityinen läpimenokäsittelijä. Se suorittaa toimintosarjansa kahdessa skenaariossa:
- Virheellinen syöttö: Soittaja painaa DTMF-näppäintä, jota ei ole määritetty “dtmfActions” -kohdassa (he esimerkiksi painaa “3”, mutta valikko määrittää vain “d1” ja “d2”).
- Idle Timeout: Soittaja ei paina mitään näppäintä idleTimeoutMsec:n määrittämän ajan kuluessa.
Jos “väärä” ei ole määritetty ja soittaja painaa virheellistä näppäintä tai aikakatkaisu, puhelu katkaistaan oletusarvoisesti. Määrittelemällä “väärä” voit luoda silmukkavalikoita (esim. palata samaan valikkoon ""action”: “gotoMenu”, “menu”: “0”`) tai ohjata käyttäjän ohjevalikkoon.
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:
{
"from": "0443914272",
"to": "50001",
"mid": "7748021",
"action": {
"confirm": true
}
}
| 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": "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"
}
]
}
}
]
}
]
}
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_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"
}
]
}
}
]
}
]
}
Vastausmuoto
Menestysvastaus
{
"messages": [
{
"messageId": "unique-message-id",
"recipient": "+380XXXXXXXXX",
"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_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"
}
]
}
}
]
}
]
}'
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ä