Help Center Taleopkaldsmeddelelser

Taleopkaldsmeddelelser

SpeechCall er en interaktiv stemmesvar (IVR) beskedtype, der giver dig mulighed for at foretage automatiske taleopkald med menuindstillinger og DTMF (dual-tone multi-frequency) interaktioner.

Oversigt

SpeechCall gør det muligt for virksomheder at:

Foretag automatiske taleopkald til kunder
Afspil indledende lydbeskeder
Præsenter interaktive menuindstillinger
Håndter DTMF-tastetryk (0-9, *, #)
Definer tilpasset adfærd for ugyldige/timeout-input
Udløs webhooks med brugerdefinerede tekster og overskrifter baseret på brugervalg
Administrer opkaldsflow dynamisk (naviger mellem menuer)

Use Cases

Kundeundersøgelser - Indsaml feedback via telefonmenuindstillinger
Aftalepåmindelser - Bekræft eller omplanlæg med stemmeinteraktion
Ordresporing - Giv ordrestatusopdateringer
Interaktive meddelelser - Lever vigtige oplysninger med handlingsmuligheder
Stemmebekræftelse - Multifaktorgodkendelse via taleopkald

Forespørgselsformat

Grundlæggende struktur

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

Parameter Beskrivelse

Parameter	Skriv	Påkrævet	Beskrivelse
`fra`	streng	Ja	Afsender-id (alfanavn eller ID)
`til`	streng	Ja	Modtagerens telefonnummer i internationalt format
`tekst`	streng	Ja	Tekstværdi, typisk “ivr” for SpeechCall
`type`	streng	Ja	Skal være `"taleopkald"`
`menu`	række	Ja	Array af menukonfigurationer for opkaldet

Menukonfiguration

Hvert menuobjekt indeholder:

Parameter	Skriv	Påkrævet	Beskrivelse
`introUrl`	streng	Ja	URL eller identifikator for den indledende lydfil
`idleTimeoutMsec`	heltal	Nej	Timeout i millisekunder for at vente på et tastetryk (f.eks. “10000”). Hvis brugeren ikke reagerer, vil handlingerne konfigureret under den ‘forkerte’ nøgle blive udført
`dtmfActions`	objekt	Ja	Kort over DTMF-nøgler til handlinger

DTMF-handlinger

“dtmfActions”-objektet tildeler DTMF-nøgler eller særlige betingelser til rækker af handlinger:

DTMF-nøgle	Beskrivelse
`d0`	Tryk på 0
`d1`	Tryk på 1
`d2`	Tryk på 2
…	…
`d9`	Tryk på 9
`d*`	Tryk på *
`d#`	Tryk på #
`forkert`	Udløses, når der trykkes på en ugyldig tast, eller når `idleTimeoutMsec` nås uden input

Hver DTMF-nøgle/betingelse er knyttet til en række handlinger, der vil blive udført i rækkefølge.

Understøttede handlinger

Handling	Parametre	Beskrivelse
`webhook`	`url` (streng, påkrævet) `body` (objekt, valgfrit) `headers` (objekt, valgfrit)	Sender en HTTP POST-anmodning i JSON-format til den angivne URL. ‘body’-objektet vil blive indlejret under ‘action’-feltet i webhook-anmodningen. Brugerdefinerede headere er inkluderet som HTTP-headere.
‘lægge på’	Ingen	Afslutter opkaldet
`gotoMenu`	”menu” (streng eller heltal)	Navigerer opkaldet til en anden menu i `menu`-arrayet ved hjælp af dets 0-baserede indeks (f.eks. `"1"`)

Detaljeret handlingsadfærd

Webhook Action (`webhook`)

“Webhook”-handlingen sender en HTTP POST-anmodning til din tilbagekalds-URL med opkaldets metadata og valgfri tilpassede data:

Hvis en “body” er angivet, sendes dens nøgleværdi-par inde i “action”-feltet i nyttelastlegemet.
Hvis “headere” er angivet, sendes de som tilpassede HTTP-headere i anmodningen.

Læg på handling (“læg på”)

“Læg på”-handlingen afslutter det aktive opkald med det samme. Ingen yderligere handlinger i sekvensen eller menuerne vil blive behandlet efter en “afslut”-handling.

Gå til menuhandling (`gotoMenu`)

‘gotoMenu’-handlingen omdirigerer strømmen af opkaldet til en anden menustruktur i ‘menu’-arrayet. Det kræver en enkelt parameter menu, som specificerer det 0-baserede indeks for målmenuen (f.eks. "1" for at gå til den anden menu, eller "0" for at genstarte den første menu).

Inaktivitet og fejlhåndtering (‘forkert’)

Den ‘forkerte’ nøgle inde i ‘dtmfActions’ er en speciel fallthrough-handler. Den udfører sin række af handlingssekvenser i to scenarier:

Ugyldig input: Den, der ringer, trykker på en DTMF-tast, der ikke er defineret i dtmfActions (de trykker f.eks. 3 men menuen definerer kun d1 og d2).
Idle Timeout: Den, der ringer op, trykker ikke på nogen tast inden for den varighed, der er angivet af idleTimeoutMsec.

Hvis ‘forkert’ ikke er defineret, og den, der ringer, trykker på en ugyldig tast eller timeout, vil opkaldsstrømmen lægge på som standard. Ved at definere forkert kan du bygge loop-menuer (f.eks. gå tilbage til den samme menu med "action": "gotoMenu", "menu": "0") eller omdirigere brugeren til en hjælpemenu.

Webhook-leveringsformat

Når ‘webhook’-handlingen udløses, sender systemet en HTTP POST-anmodning til den konfigurerede ‘url’ med ‘Content-Type: application/json’.

Webhook Request Headers

Hvis handlingen er konfigureret med parameteren “headers”, inkluderes disse nøgleværdi-par som HTTP-headere i anmodningen.

Webhook Request Body

JSON-nyttelasten, der sendes til din webhook-URL, har følgende struktur:

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

Felt	Skriv	Beskrivelse
`fra`	streng	Opkalds telefonnummer / afsender-id
`til`	streng	Modtagerens telefonnummer
`midt`	streng	Meddelelses-id
`handling`	objekt	Det brugerdefinerede JSON-objekt, der er defineret i handlingens “body”-felt

Komplet eksempel

Simpel IVR med timeout og inputvalidering

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

Kompleks IVR med flere menuer og DTMF-routing

Dette eksempel viser, hvordan man definerer flere menuer og navigerer mellem dem ved hjælp af ‘gotoMenu’-handlingen, når brugeren indtaster en ugyldig nøgle, eller når opkaldet timeout. Det viser også brugerdefinerede bodies og tilpassede HTTP-headere sendt med webhook-udløsere.

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

Svarformat

Successvar

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

Fejlhåndtering

HTTP-status	Beskrivelse
200	Forespørgsel lykkedes
400	Ugyldigt anmodningsformat
401	Godkendelse mislykkedes
429	Satsgrænse overskredet
500	Intern serverfejl

cURL Eksempel

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

Bedste praksis

Lydfiler - Sørg for, at intro-URL’er er tilgængelige, og at lydfiler er i understøttede formater
Webhook Reliability - Design webhooks til at reagere hurtigt (inden for 2 sekunder)
DTMF-indstillinger - Begræns menuindstillinger til 4-6 valg for bedre brugeroplevelse
Timeouthåndtering - Brug idleTimeoutMsec til at angive brugerdefinerede inaktivitetsgrænser (f.eks. 10000 ms), og konfigurer en yndefuld fallback under den “forkerte” DTMF-tast (som at gentage menuen eller lægge på)
Multi-Menu Call Flow - Brug gotoMenu omhyggeligt for at forhindre uendelige sløjfer, når du dirigerer brugere tilbage til tidligere menuer
Fallback-strategi - Brug reservemeddelelser til brugere, der ikke svarer eller afbryder forbindelsen

Relaterede emner

Send besked - Generel vejledning til afsendelse af beskeder
Flash Call - Simple stemmebekræftelsesopkald
Kontroller status - Spor leveringsstatus for beskeder
Meddelelsestyper - Oversigt over alle understøttede meddelelsestyper

Search Results