> ## Documentation Index > Fetch the complete documentation index at: https://aipro.placetel.de/docs/llms.txt > Use this file to discover all available pages before exploring further. # Inbound Webhook > Vor einem eingehenden Anruf Daten aus einer API laden und in der initialen Begrüßung verwenden. ## Ü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. Der Inbound Webhook wird nur bei eingehenden Anrufen ausgeführt. Die HTTP-Anfrage muss abgeschlossen sein, bevor der Voice Agent den Anruf annimmt. ## Inbound Webhook öffnen Öffnen Sie den gewünschten Voice Agent und wechseln Sie zum Tab **Erweitert**. Öffnen Sie die Karte **Inbound Webhook** und klicken Sie auf **Konfigurieren**. Sobald eine gültige Konfiguration gespeichert wurde, können Sie den Inbound Webhook über den Schalter in der Karte aktivieren oder pausieren. Inbound Webhook im Tab Erweitert ## 1. Verbindung konfigurieren Im ersten Schritt legen Sie fest, wann und wie die HTTP-Anfrage gesendet wird. Verbindung, Timeout und Systemvariablen konfigurieren ### 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: | Option | Verhalten | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Anruf mit Standardwerten fortsetzen** | Der Anruf wird angenommen. Für nicht verfügbare Variablen wird der jeweils konfigurierte Standardwert verwendet. Ohne Standardwert bleibt die Variable leer. | | **Anruf nicht annehmen** | Der Voice Agent nimmt den Anruf nicht an, wenn die HTTP-Anfrage fehlschlägt oder den Timeout überschreitet. | Für die meisten Anwendungsfälle ist **Anruf mit Standardwerten fortsetzen** die robustere Einstellung. So bleibt der Voice Agent auch erreichbar, wenn das angebundene System vorübergehend nicht antwortet. ### 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: | Variable | Bedeutung | | --------------------------- | --------------------------------------------------------------------------------------------------------------- | | `{{caller_number}}` | Rufnummer des eingehenden Anrufers. Bei anonymen Anrufen kann der Wert leer sein. | | `{{called_number}}` | Die vom Anrufer erreichte, kundenbezogene Zielrufnummer. | | `{{forwarded_from_number}}` | Rufnummer, von der der Anruf weitergeleitet wurde, sofern diese Information von der Telefonie übermittelt wird. | 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: | Key | Value | | ------------------- | ------------------- | | `X-Customer-Number` | `{{caller_number}}` | 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. Optionale Testdaten für die HTTP-Anfrage * **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. Felder direkt aus der Testantwort auswählen ### 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. Finale Request-Vorschau und JSON-Antwort ### 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. Ein Feld in der JSON-Antwort suchen 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: | Inhalt | Antwortpfad | | ------------------------------------------------- | ------------------------- | | Erstes Element im Array `users`, Feld `firstName` | `users.0.firstName` | | Zweites Produkt der ersten Bestellung, Feld `sku` | `orders.0.items.1.sku` | | Verschachtelte Firmenadresse | `company.address.address` | Array-Elemente in Dot Notation In der Auswahlliste werden höchstens die ersten 1.000 einzelnen Antwortfelder angezeigt. Verwenden Sie bei größeren Antworten die Suche oder tragen Sie den bekannten Dot-Pfad im nächsten Schritt manuell ein. ### 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. Variablennamen, Antwortpfade und Standardwerte | Feld | Bedeutung | | ---------------- | ------------------------------------------------------------------------------------ | | **Variable** | Der Name, den Sie später als Platzhalter verwenden, zum Beispiel `first_name`. | | **Antwortpfad** | Die genaue Position des Werts in der JSON-Antwort, zum Beispiel `users.0.firstName`. | | **Standardwert** | Optionaler Ersatzwert, falls am Antwortpfad kein verwendbarer Wert gefunden wird. | 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}}` Inbound-Webhook-Variable in der initialen Begrüßung 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.