Inbound Webhook

​

Überblick

Der Inbound Webhook sendet eine HTTP-Anfrage, bevor der Voice Agent einen eingehenden Anruf annimmt. Werte aus der JSON-Antwort werden als Variablen bereitgestellt und können die initiale Begrüßung personalisieren. Typische Beispiele sind der Name eines Kunden, sein Tarif oder eine Information aus Ihrem CRM. Der Voice Agent kann dadurch einen Anrufer direkt passend begrüßen.

​

Inbound Webhook öffnen

​

1. Verbindung konfigurieren

Im ersten Schritt legen Sie fest, wann und wie die HTTP-Anfrage gesendet wird.

​

Timeout

Der Timeout bestimmt, wie lange maximal auf die API gewartet wird. Sie können einen Wert zwischen 250 ms und 30.000 ms (30 Sekunden) eingeben. Der Standardwert ist 5.000 ms. Ein längerer Timeout gibt einer langsamen API mehr Zeit, verzögert aber auch die Annahme des Anrufs. Verwenden Sie deshalb den niedrigsten Wert, mit dem Ihre API zuverlässig antwortet.

​

Verhalten bei Fehler oder Timeout

Unter Bei Fehler oder Timeout stehen zwei Optionen zur Verfügung:

​

HTTP-Methode und Endpoint

Verfügbar sind die HTTP-Methoden GET, POST, PUT, PATCH und DELETE. Die Endpoint-URL muss mit https:// beginnen.

• Systemvariablen können im URL-Pfad oder Query-String verwendet werden, zum Beispiel https://api.example.com/customers/{{caller_number}}.
• Bei POST, PUT, PATCH und DELETE können Sie zusätzlich einen JSON-Body konfigurieren.
• GET-Anfragen werden ohne Request-Body gesendet.

​

Authentifizierung

Der Inbound Webhook unterstützt keine Authentifizierung, Bearer Token, API-Key Header, Basic Auth, OAuth 2.0 und JWT OAuth. Für OAuth 2.0 und JWT OAuth wählen Sie eine bereits gespeicherte Verbindung aus. Zugangsdaten werden nicht in den technischen Testdetails angezeigt.

​

Anrufdaten als Systemvariablen senden

Die folgenden Systemvariablen stehen bereits vor dem Anruf zur Verfügung: Sie können diese Variablen in der Endpoint-URL, in zusätzlichen Headern und - bei Methoden mit Request-Body - im JSON-Body verwenden. Klicken Sie in ein unterstütztes Feld und geben Sie {{ ein. Danach wählen Sie die gewünschte Variable aus der Liste. Beispiel für einen zusätzlichen Header: Ist eine Anrufinformation nicht verfügbar, wird an ihrer Stelle ein leerer Wert eingesetzt. Der Platzhalter selbst wird nicht an Ihre API gesendet.

​

2. Verbindung testen und Antwort prüfen

Im zweiten Schritt können Sie Ihre echte API mit frei gewählten Testdaten aufrufen. Die drei Rufnummernfelder sind optional und beeinflussen ausschließlich diesen Test.

• caller_number simuliert die Rufnummer des Anrufers.
• called_number simuliert die angerufene Zielrufnummer.
• forwarded_from_number simuliert eine vorhandene Weiterleitung.

Tragen Sie die Werte ein, die Ihre API für einen realistischen Test benötigt, und klicken Sie auf Test ausführen. Die Werte ersetzen im Test die gleichnamigen Platzhalter in URL, Headern und JSON-Body. Nach einem erfolgreichen Test sehen Sie den HTTP-Status und die Dauer der Anfrage. Darunter können Sie einzelne Werte aus der Antwort direkt auswählen. Aus jedem ausgewählten Wert wird im dritten Schritt eine Inbound-Webhook-Variable.

​

Technische Details

Öffnen Sie Technische Details, um zwei Ansichten nebeneinander zu prüfen:

• Finale Request-Vorschau zeigt Methode, URL, Header und Body nach dem Ersetzen der Systemvariablen. Vertrauliche Authentifizierungswerte werden ausgeblendet.
• JSON-Antwort zeigt die Antwort, die Ihre API beim Test zurückgegeben hat.

​

Antwort durchsuchen

Bei großen Antworten können Sie nach einem Feldnamen, einem Antwortpfad oder einem Wert suchen. Aktivieren Sie anschließend das gewünschte einzelne Feld über die Checkbox. Nur einzelne Werte können als Variable übernommen werden: Text, Zahlen und true oder false. Bei Objekten und Arrays wählen Sie den konkreten Wert innerhalb der Struktur aus.

​

Dot Notation für verschachtelte Antworten und Arrays

Antwortpfade werden in Dot Notation geschrieben. Jeder Punkt führt eine Ebene tiefer. Bei Arrays ist der Index ebenfalls ein Abschnitt des Pfads und beginnt bei 0. Beispiele:

​

Konfiguration ohne erfolgreichen Test

Ein Test ist optional. Wenn Ihre API im Konfigurationsdialog nicht getestet werden kann, wechseln Sie trotzdem zum Schritt Variablen. Dort legen Sie den Variablennamen an und tragen den erwarteten Antwortpfad manuell in Dot Notation ein.

​

3. Variablen und Standardwerte festlegen

Im letzten Schritt prüfen und bearbeiten Sie die Variablenzuordnung. Der Standardwert wird verwendet, wenn der Pfad fehlt, der Wert null oder leer ist oder der Pfad auf ein Objekt beziehungsweise Array statt auf einen einzelnen Wert zeigt. Wenn Anruf mit Standardwerten fortsetzen ausgewählt ist, werden die Standardwerte außerdem bei einem Request-Fehler oder Timeout eingesetzt. Ohne Standardwert bleibt die Variable leer. In der Begrüßung wird dann kein unverarbeiteter Platzhalter wie {{first_name}} vorgelesen.

​

Variable in der initialen Begrüßung verwenden

Speichern Sie die Inbound-Webhook-Konfiguration und öffnen Sie anschließend im Voice Agent die Initiale Begrüßung. Geben Sie {{ ein und wählen Sie eine konfigurierte Variable aus. Beispiel: Hi, {{first_name}} Bei jedem eingehenden Anruf wird zuerst die HTTP-Anfrage ausgeführt. Danach ersetzt der Voice Agent den Platzhalter durch den Wert aus der Antwort oder durch den konfigurierten Standardwert und beginnt mit der fertigen Begrüßung.

​

Anforderungen an die API-Antwort

Damit die Antwort verarbeitet werden kann, muss Ihre API:

• mit einem HTTP-Status zwischen 200 und 299 antworten,
• ein gültiges JSON-Objekt zurückgeben,
• die benötigten Werte als Text, Zahl oder Boolean bereitstellen.

Fehlende, leere oder nicht verwendbare Werte werden nach der konfigurierten Standardwert- und Fehlerlogik behandelt.