SpeechCall-berichten

SpeechCall is een interactief voice response-berichttype (IVR) waarmee u geautomatiseerde spraakoproepen kunt maken met menuopties en DTMF-interacties (dual-tone multi-frequency).

Overzicht

Met SpeechCall kunnen bedrijven: - Voer geautomatiseerde spraakoproepen naar klanten - Speel inleidende audioberichten af - Presenteer interactieve menu-opties - Behandel DTMF-toetsaanslagreacties (0-9, *, #) - Definieer aangepast gedrag voor ongeldige/time-outinvoer - Activeer webhooks met aangepaste hoofdteksten en headers op basis van gebruikersselecties - Beheer de oproepstroom dynamisch (navigeer tussen menu's)

Gebruiksscenario's

Klantenonderzoeken - Verzamel feedback via telefoonmenu-opties
Afspraakherinneringen - Bevestig of verplaats uw afspraak met steminteractie
Bestellingen volgen - Geef updates van de bestelstatus
Interactieve meldingen - Lever belangrijke informatie met actie-opties
Spraakverificatie - Multi-factor authenticatie via spraakoproepen

Verzoekformaat

Basisstructuur

{
  "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"
              }
            ]
          }
        }
      ]
    }
  ]
}

Parameterbeschrijving

Parameter	Typ	Vereist	Beschrijving
`van`	tekenreeks	Ja	Afzender-ID (alfanaam of ID)
`naar`	tekenreeks	Ja	Telefoonnummer van de ontvanger in internationaal formaat
`tekst`	tekenreeks	Ja	Tekstwaarde, meestal 'ivr' voor SpeechCall
`type`	tekenreeks	Ja	Moet `"toespraak"` zijn
`menu`	array	Ja	Array van menuconfiguraties voor de oproep

Menuconfiguratie

Elk menu-object bevat:

Parameter	Typ	Vereist	Beschrijving
`introUrl`	tekenreeks	Ja	URL of identificatie van het inleidende audiobestand
`idleTimeoutMsec`	geheel getal	Nee	Time-out in milliseconden om te wachten op een toetsaanslag (bijvoorbeeld `10000`). Als de gebruiker niet reageert, worden de acties uitgevoerd die zijn geconfigureerd onder de `verkeerde` sleutel
`dtmfActions`	voorwerp	Ja	Kaart met DTMF-sleutels voor acties

DTMF-acties

Het object dtmfActions wijst DTMF-sleutels of speciale voorwaarden toe aan reeksen acties:

DTMF-sleutel	Beschrijving
`d0`	Druk op 0
`d1`	Druk op 1
`d2`	Druk op 2
...	...
`d9`	Druk op 9
`d*`	Druk op *
`d#`	Druk op #
`verkeerd`	Wordt geactiveerd wanneer een ongeldige toets wordt ingedrukt of wanneer `idleTimeoutMsec` wordt bereikt zonder enige invoer

Elke DTMF-sleutel/voorwaarde verwijst naar een reeks acties die achtereenvolgens worden uitgevoerd.

Ondersteunde acties

Actie	Parameters	Beschrijving
`webhook`	`url` (tekenreeks, vereist) `body` (object, optioneel) `headers` (object, optioneel)	Verzendt een HTTP POST-verzoek in JSON-indeling naar de opgegeven URL. Het `body`-object wordt genest onder het `action`-veld in de webhookaanvraag. Aangepaste headers zijn opgenomen als HTTP-headers.
`ophangen`	Geen	Beëindigt het gesprek
`ga naarMenu`	`menu` (tekenreeks of geheel getal)	Navigeer door de oproep naar een ander menu in de `menu` array met behulp van de op 0 gebaseerde index (bijvoorbeeld `"1"`)

Webhook-leveringsformaat

Wanneer de actie webhook wordt geactiveerd, verzendt het systeem een HTTP POST-verzoek naar de geconfigureerde url met Content-Type: application/json.

Webhook-verzoekheaders

Als de actie is geconfigureerd met de parameter headers, worden deze sleutel-waardeparen als HTTP-headers in het verzoek opgenomen.

Webhookverzoektekst

De JSON-payload die naar uw webhook-URL wordt verzonden, heeft de volgende structuur:

{
  "from": "0443914272",
  "to": "50001",
  "mid": "7748021",
  "action": {
    "confirm": true
  }
}

Veld	Typ	Beschrijving
`van`	tekenreeks	Telefoonnummer beller/afzender-ID
`naar`	tekenreeks	Telefoonnummer ontvanger
`midden`	tekenreeks	Bericht-ID
`actie`	voorwerp	Het aangepaste JSON-object dat is gedefinieerd in het `body`-veld

Compleet voorbeeld

Eenvoudige IVR met time-out en invoervalidatie

{
  "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"
              }
            ]
          }
        }
      ]
    }
  ]
}

Complexe IVR met meerdere menu's en DTMF-routering

Dit voorbeeld demonstreert hoe u meerdere menu's definieert en ertussen navigeert met behulp van de actie gotoMenu wanneer de gebruiker een ongeldige sleutel invoert of wanneer de oproep een time-out heeft. Het toont ook aangepaste hoofdteksten en aangepaste HTTP-headers die met de webhooktriggers zijn verzonden.

{
  "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"
              }
            ]
          }
        }
      ]
    }
  ]
}

Antwoordformaat

Succesreactie

{
  "messages": [
    {
      "messageId": "unique-message-id",
      "recipient": "+380936670003",
      "status": "sent"
    }
  ]
}

Foutafhandeling

HTTP-status	Beschrijving
200	Aanvraag succesvol
400	Ongeldig verzoekformaat
401	Authenticatie mislukt
429	Tarieflimiet overschreden
500	Interne serverfout

cURL-voorbeeld

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"
                }
              ]
            }
          }
        ]
      }
    ]
  }'

Beste praktijken

Audiobestanden - Zorg ervoor dat intro-URL's toegankelijk zijn en dat audiobestanden de ondersteunde indelingen hebben
Webhook-betrouwbaarheid - Ontwerp webhooks om snel te reageren (binnen 2 seconden)
DTMF-opties - Beperk menu-opties tot 4-6 keuzes voor een betere gebruikerservaring
Time-outafhandeling - Gebruik idleTimeoutMsec om aangepaste inactiviteitslimieten op te geven (bijvoorbeeld 10.000 ms), en configureer een elegante terugval onder de verkeerde DTMF-sleutel (zoals het herhalen van het menu of ophangen)
Multi-Menu Call Flow - Gebruik gotoMenu zorgvuldig om oneindige lussen te voorkomen bij het terugsturen van gebruikers naar vorige menu's
Fallback-strategie - Gebruik fallback-berichten voor gebruikers die niet opnemen of de verbinding verbreken

Gerelateerde onderwerpen

Bericht verzenden - Algemene handleiding voor het verzenden van berichten
Flash Call - Eenvoudige spraakverificatieoproepen
Status controleren - Volg de bezorgingsstatus van berichten
Berichttypen - Overzicht van alle ondersteunde berichttypen