Help Center Wiadomości głosowe

Wiadomości głosowe

SpeechCall to rodzaj wiadomości z interaktywną odpowiedzią głosową (IVR), który umożliwia wykonywanie automatycznych połączeń głosowych za pomocą opcji menu i interakcji w formacie DTMF (dual-tone multi-frequency).

Przegląd

SpeechCall umożliwia firmom:

  • Wykonuj automatyczne połączenia głosowe z klientami
  • Odtwórz wstępne wiadomości audio
  • Przedstaw interaktywne opcje menu
  • Obsługa reakcji na naciśnięcie klawisza DTMF (0-9, *, #)
  • Zdefiniuj niestandardowe zachowanie dla nieprawidłowych danych wejściowych/przekroczenia limitu czasu
  • Wyzwalaj webhooki z niestandardowymi treściami i nagłówkami w oparciu o wybory użytkownika
  • Zarządzaj dynamicznie przepływem połączeń (nawiguj pomiędzy menu)

Przypadki użycia

  • Ankiety konsumenckie - Zbieraj opinie za pomocą opcji menu telefonu
  • Przypomnienia o spotkaniach - Potwierdź lub przełóż spotkanie za pomocą interakcji głosowej
  • Śledzenie zamówienia - Zapewnia aktualizacje statusu zamówienia
  • Interaktywne powiadomienia - Dostarczaj ważne informacje wraz z opcjami działania
  • Weryfikacja głosowa - Uwierzytelnianie wieloskładnikowe za pośrednictwem połączeń głosowych

##Format żądania

Podstawowa struktura

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

Opis parametru

ParametrWpiszWymaganeOpis
odciągTakIdentyfikator nadawcy (nazwa alfa lub identyfikator)
dociągTakNumer telefonu odbiorcy w formacie międzynarodowym
tekstciągTakWartość tekstowa, zazwyczaj „ivr” dla SpeechCall
typciągTakMusi być "rozmowa"
menutablicaTakTablica konfiguracji menu dla połączenia

Konfiguracja menu

Każdy obiekt menu zawiera:

ParametrWpiszWymaganeOpis
introUrlciągTakAdres URL lub identyfikator wstępnego pliku audio
idleTimeoutMsliczba całkowitaNieLimit czasu w milisekundach oczekiwania na naciśnięcie klawisza (np. „10000”). Jeśli użytkownik nie zareaguje, zostaną wykonane akcje skonfigurowane pod klawiszem zły
dtmfActionsobiektTakMapa kluczy DTMF do akcji

Akcje DTMF

Obiekt dtmfActions odwzorowuje klucze DTMF lub warunki specjalne na tablice akcji:

Klucz DTMFOpis
d0Naciśnij 0
d1Naciśnij 1
d2Naciśnij 2
……
d9Naciśnij 9
d*Naciśnij *
d#Naciśnij #
„źle”Wywołuje się po naciśnięciu nieprawidłowego klawisza lub osiągnięciu idleTimeoutMsec bez wprowadzania danych

Każdy klucz/warunek DTMF jest odwzorowywany na tablicę akcji, które będą wykonywane sekwencyjnie.

Obsługiwane akcje

AkcjaParametryOpis
webhookurl (string, wymagany)
treść (obiekt, opcjonalny)
headers (obiekt, opcjonalny)		Wysyła żądanie HTTP POST w formacie JSON na podany adres URL. Obiekt „treść” zostanie zagnieżdżony w polu „akcja” w żądaniu webhooka. Nagłówki niestandardowe są dołączane jako nagłówki HTTP.
„rozłącz”BrakKończy połączenie
gotoMenumenu (ciąg znaków lub liczba całkowita)Przechodzi wywołanie do innego menu w tablicy menu przy użyciu indeksu opartego na 0 (np. `“1”)

Szczegółowe zachowanie akcji

Akcja webhooka („webhook”)

Akcja „webhook” wysyła żądanie HTTP POST na adres URL wywołania zwrotnego z metadanymi wywołania i opcjonalnymi danymi niestandardowymi:

  • Jeśli podano „treść”, jej pary klucz-wartość są wysyłane do pola „akcja” treści ładunku.
  • Jeśli podano „nagłówki”, są one wysyłane w żądaniu jako niestandardowe nagłówki HTTP.

Akcja rozłączania („rozłączanie”)

Akcja „rozłącz” natychmiast kończy aktywne połączenie. Po akcji „rozłączania” żadne dalsze działania w sekwencji lub menu nie będą przetwarzane.

Przejdź do akcji menu („gotoMenu”)

Akcja gotoMenu przekierowuje przepływ wywołania do innej struktury menu w obrębie tablicy menu. Pobiera pojedynczy parametr menu, który określa indeks menu docelowego oparty na 0 (np. 1'' aby przejść do drugiego menu lub 0” aby zrestartować pierwsze menu).

Brak aktywności i obsługa błędów („źle”)

„Zły” klucz w „dtmfActions” to specjalna procedura obsługi awaryjnej. Wykonuje szereg sekwencji akcji w dwóch scenariuszach:

  1. Nieprawidłowe wejście: Osoba wywołująca naciska klawisz DTMF, który nie jest zdefiniowany w dtmfActions (na przykład naciska 3, ale menu definiuje tylko d1 i d2).
  2. Limit czasu bezczynności: Osoba wywołująca nie naciśnie żadnego klawisza w czasie określonym przez idleTimeoutMsec.

Jeśli słowo „źle” nie zostało zdefiniowane i osoba dzwoniąca naciśnie nieprawidłowy klawisz lub upłynie limit czasu, połączenie zostanie domyślnie rozłączone. Zdefiniowanie wrong pozwala na budowanie menu zapętlonych (np. powrót do tego samego menu za pomocą "action": "gotoMenu", "menu": "0") lub przekierowanie użytkownika do menu pomocy.

Format dostarczania webhooka

Kiedy zostanie uruchomiona akcja webhook, system wysyła żądanie HTTP POST do skonfigurowanego url z Content-Type: application/json.

Nagłówki żądań webhooka

Jeśli akcja jest skonfigurowana z parametrem „headers”, te pary klucz-wartość zostaną uwzględnione w żądaniu jako nagłówki HTTP.

Treść żądania webhooka

Ładunek JSON wysłany na adres URL webhooka ma następującą strukturę:

{
  "from": "0443914272",
  "to": "50001",
  "mid": "7748021",
  "action": {
    "confirm": true
  }
}
PoleWpiszOpis
odciągNumer telefonu osoby dzwoniącej / ID nadawcy
dociągNumer telefonu odbiorcy
środekciągIdentyfikator wiadomości
akcjaobiektNiestandardowy obiekt JSON zdefiniowany w polu treść akcji

Kompletny przykład

Prosty IVR z limitem czasu i walidacją danych wejściowych

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

Złożony IVR z wieloma menu i routingiem DTMF

Ten przykład pokazuje, jak zdefiniować wiele menu i nawigować między nimi za pomocą akcji „gotoMenu”, gdy użytkownik wprowadzi nieprawidłowy klucz lub upłynie limit czasu wywołania. Pokazuje także niestandardowe treści i niestandardowe nagłówki HTTP wysyłane z wyzwalaczami elementu webhook.

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

##Format odpowiedzi

Odpowiedź pomyślna

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

Obsługa błędów

Stan HTTPOpis
200Żądanie powiodło się
400Nieprawidłowy format żądania
401Uwierzytelnienie nie powiodło się
429Przekroczono limit stawki
500Wewnętrzny błąd serwera

cURL Przykład

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

Najlepsze praktyki

  1. Pliki audio — upewnij się, że początkowe adresy URL są dostępne, a pliki audio mają obsługiwane formaty
  2. Niezawodność webhooka – Projektuj webhooki tak, aby szybko reagowały (w ciągu 2 sekund)
  3. Opcje DTMF – Ogranicz opcje menu do 4–6 opcji, aby zapewnić lepszą wygodę użytkowania
  4. Obsługa limitu czasu - Użyj idleTimeoutMsec, aby określić niestandardowe limity braku aktywności (np. 10000 ms) i skonfigurować płynne przywracanie ustawień awaryjnych pod złym klawiszem DTMF (np. powtarzanie menu lub rozłączanie się)
  5. Przepływ połączeń w wielu menu – Używaj gotoMenu ostrożnie, aby zapobiec nieskończonym pętlom podczas przekierowywania użytkowników z powrotem do poprzednich menu
  6. Strategia awaryjna – Używaj wiadomości zastępczych dla użytkowników, którzy nie odbierają lub nie rozłączają się

Powiązane tematy