> ## Documentation Index > Fetch the complete documentation index at: https://app.miyon.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Inbound Webhook > Vor einem eingehenden Anruf API-Daten laden und in Begrüßung, KI-Anweisung, Weiterleitung und Nachbearbeitung 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. Sie können diese in der initialen Begrüßung, in der KI-Anweisung (User Prompt), als Ziel einer Anrufweiterleitung und in der Nachbearbeitung verwenden. Typische Beispiele sind der Name eines Kunden, sein Tarif, seine Kunden-ID oder die Rufnummer seines zuständigen Ansprechpartners. Der Voice Agent kann damit persönlich begrüßen, mit passendem Kontext antworten und an das richtige Ziel weiterleiten. > [!NOTE] > > 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 **1. Voice Agent öffnen** Öffnen Sie den gewünschten Voice Agent und wechseln Sie zum Tab **Erweitert**. **2. Inbound Webhook konfigurieren** Öffnen Sie die Karte **Inbound Webhook** und klicken Sie auf **Konfigurieren**. **3. Funktion aktivieren** 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](https://mintcdn.com/miyon/GKHPbvJ_LePpogwL/images/inbound-webhook/overview.jpg?fit=max\&auto=format\&n=GKHPbvJ_LePpogwL\&q=85\&s=0b0852dbace48ec6bca680e8e9f12556) ## 1. Verbindung konfigurieren Im ersten Schritt legen Sie fest, wann und wie die HTTP-Anfrage gesendet wird. ![Verbindung, Timeout und Systemvariablen konfigurieren](https://mintcdn.com/miyon/GKHPbvJ_LePpogwL/images/inbound-webhook/connection-system-variables.jpg?fit=max\&auto=format\&n=GKHPbvJ_LePpogwL\&q=85\&s=2c107a8dc1146fc4922f9beab084b4aa) ### 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. | > [!TIP] > > 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}}` | Weiterleitungskennung aus der Telefonie, sofern vorhanden. Sie kann eine Rufnummer oder eine technische Kennung enthalten. | 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. > [!NOTE] > > In der **HTTP-Anfrage des Inbound Webhooks** verwenden Sie die oben gezeigten Systemvariablen ohne Namensraum, zum Beispiel `{{caller_number}}`. **Werte aus der API-Antwort** verwenden Sie anschließend mit `pre_call`, zum Beispiel `{{pre_call.first_name}}`. ## 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](https://mintcdn.com/miyon/GKHPbvJ_LePpogwL/images/inbound-webhook/test-inputs.jpg?fit=max\&auto=format\&n=GKHPbvJ_LePpogwL\&q=85\&s=bd5c22c27366d7c57d661f62a7349c7f) * **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](https://mintcdn.com/miyon/GKHPbvJ_LePpogwL/images/inbound-webhook/test-select-fields.jpg?fit=max\&auto=format\&n=GKHPbvJ_LePpogwL\&q=85\&s=c8176649b30afd6fbff4c59e8d9a0054) ### 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](https://mintcdn.com/miyon/GKHPbvJ_LePpogwL/images/inbound-webhook/technical-details.jpg?fit=max\&auto=format\&n=GKHPbvJ_LePpogwL\&q=85\&s=2fd0eb4f9b64d41f667c811f93dc7bc5) ### 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](https://mintcdn.com/miyon/GKHPbvJ_LePpogwL/images/inbound-webhook/search-response.jpg?fit=max\&auto=format\&n=GKHPbvJ_LePpogwL\&q=85\&s=6ffb6560eb071ac02b6dc79c6293a630) 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](https://mintcdn.com/miyon/GKHPbvJ_LePpogwL/images/inbound-webhook/array-dot-notation.jpg?fit=max\&auto=format\&n=GKHPbvJ_LePpogwL\&q=85\&s=84f004f2a2716737352f6feed075291f) > [!NOTE] > > 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](https://mintcdn.com/miyon/GKHPbvJ_LePpogwL/images/inbound-webhook/variable-mapping.jpg?fit=max\&auto=format\&n=GKHPbvJ_LePpogwL\&q=85\&s=e073832d3620810a9a416435930e7736) | Feld | Bedeutung | | - | - | | **Variable** | Der Name, den Sie später als Platzhalter verwenden, zum Beispiel `first_name`. In anderen Feldern verwenden Sie ihn als `{{pre_call.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 `{{pre_call.first_name}}` vorgelesen. ## Variablen im Voice Agent verwenden Speichern Sie die Inbound-Webhook-Konfiguration. Eine Variable mit dem Namen `first_name` ist danach als `{{pre_call.first_name}}` verfügbar. Tippen Sie in einem unterstützten Feld `{{` und wählen Sie die Variable aus. | Bereich | Beispiel | Verwendung | | - | - | - | | **Initiale Begrüßung** | `Hallo {{pre_call.first_name}}, wie kann ich helfen?` | Den Anrufer direkt mit passenden Informationen begrüßen. | | **KI-Anweisung (User Prompt)** | `Der Tarif des Kunden ist {{pre_call.plan}}.` | Dem Agenten Kontext für das Gespräch geben; auch im Vollbildeditor verfügbar. | | **Tools → Anrufe weiterleiten → Rufnummer** | `{{pre_call.forward_to}}` | Eine Rufnummer aus Ihrer API als Weiterleitungsziel verwenden. | | **Nachbearbeitung** | `Kunden-ID: {{pre_call.customer_id}}` | Den geladenen Wert in E-Mail-Betreff und Nachricht, SMS, KI-Inhaltsanweisungen sowie API-URL, Header-Werten und Body verwenden. | ### Initiale Begrüßung und KI-Anweisung Bei jedem eingehenden Anruf wird zuerst die HTTP-Anfrage ausgeführt. Die Platzhalter werden mit den Werten aus der Antwort oder den konfigurierten Standardwerten befüllt. Diese Werte stehen für denselben Anruf auch in der Weiterleitung und Nachbearbeitung zur Verfügung. Mehr zum User Prompt finden Sie unter [KI-Anweisungen](/docs/de/ai-prompts). ### Dynamisches Weiterleitungsziel Legen Sie zum Beispiel eine Variable `forward_to` an und ordnen Sie ihr das Rufnummernfeld Ihrer API-Antwort zu. Unter **Tools → Anrufe weiterleiten** tragen Sie im Feld **Rufnummer** den vollständigen Platzhalter `{{pre_call.forward_to}}` ein. Der aufgelöste Wert muss eine Rufnummer im **internationalen Format mit `+` und Ländervorwahl, ohne Leerzeichen** sein, zum Beispiel `+493012345678`. Nationale Schreibweisen wie `03012345678` und Werte wie `+49 30 12345678` werden nicht unterstützt. Kombinieren Sie den Platzhalter nicht mit einer zusätzlichen Vorwahl oder anderem Text. ### Nachbearbeitung mit denselben Werten Verwenden Sie etwa `{{pre_call.customer_id}}`, um eine [Nachbearbeitungsaufgabe](/docs/de/post-processing) dem richtigen Kunden zuzuordnen. Diese Werte stammen aus dem Inbound Webhook vor dem Gespräch. Eigene Extraktionen wie `{{post_call.kunden_email}}` entstehen dagegen erst nach dem Gespräch und stehen deshalb nicht in der Begrüßung, im User Prompt oder als Weiterleitungsziel zur Verfügung. ## 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.