> For the complete documentation index, see [llms.txt](https://help.sipgate.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.sipgate.de/ai-agents/anbindungen-and-integrationen/datenabruf-bei-anrufbeginn.md). # Datenabruf bei Anrufbeginn Mit dem Datenabruf bei Anrufbeginn ruft Ihr Agent eine von Ihnen hinterlegte URL ab, sobald ein eingehender Anruf startet. Die Antwort steht ihm dann im Gespräch zur Verfügung. ### Wann ist das sinnvoll? Der Datenabruf eignet sich für Inhalte, die sich häufig ändern oder pro Anruf unterschiedlich sind: * **aktuelle Verfügbarkeiten abfragen**: zum Beispiel freie Termine oder Lagerbestände * **CRM-Daten oder Kundenhistorie laden** * **tagesaktuelle Anweisungen:** zum Beispiel Sonderöffnungszeiten oder Aktionen * **vergangene Interaktionen** mit der anrufenden Person **verfügbar machen** {% hint style="info" %} Der Datenabruf ist für konkrete Informationen zum aktuellen Anruf gedacht. Er ersetzt keine allgemeine Wissensbasis und eignet sich nicht für umfangreiche Inhalte wie PDFs, Webseiten oder Dokumentationen. Dauerhaftes Wissen hinterlegen Sie in der Wissensdatenbank. {% endhint %} ### Voraussetzungen * eine URL, die per HTTP oder HTTPS erreichbar ist, HTTPS empfohlen * ein Endpunkt, der schnell antwortet, denn der Abruf erfolgt beim Anrufbeginn * kompakte, gut strukturierte Inhalte, denn die Antwort wird als Text in den Gesprächskontext eingebettet {% hint style="warning" %} **Wichtig:** Nutzen Sie keine öffentlich auffindbare URL. Aktuell erfolgt keine Authentifizierung zwischen sipgate und dem angebundenen Server. Andernfalls könnten unbefugte Dritte den Endpunkt verwenden und übermittelte Anruferdaten abrufen. Beschränken Sie den Zugriff serverseitig auf folgende sipgate IP-Adressen: * `217.116.118.254` * `212.9.46.32` Nutzen Sie dafür zum Beispiel eine Allowlist. So stellt der Server sicher, dass Anfragen an den Endpunkt tatsächlich von sipgate kommen. {% endhint %} {% hint style="info" %} **Hinweis:** Die Antwort des Servers sollte ausschließlich Daten enthalten. Prompt-Anweisungen oder Verhaltensregeln werden ignoriert oder nicht zuverlässig verarbeitet. {% endhint %} ### So richten Sie den Datenabruf ein #### Wo finde ich den Datenabruf? * **sipgate sona:** Agentenübersicht öffnen und Datenabruf bei Anrufbeginn aus der Bibliothek in der Seitenleiste per Drag-and-drop auf Ihren Agent ziehen. * **AI Agents:** Konfiguration Ihres Agents öffnen → Menüpunkt Integrationen → Abschnitt Datenabruf bei Anrufbeginn → Zahnrad-Symbol. {% hint style="info" %} **Hinweis:** Solange kein Datenabruf konfiguriert ist, erscheint in der Agentenübersicht auch keine Karte dafür. Den ersten Datenabruf legen Sie deshalb immer über die Bibliothek an. {% endhint %} {% stepper %} {% step %} Geben Sie im Dialog **Datenabruf konfigurieren** die gewünschte URL ein. {% endstep %} {% step %} Aktivieren Sie optional **Abruf erzwingen**, damit der Abruf erfolgreich sein muss, bevor der Anruf stattfindet. {% endstep %} {% step %} Klicken Sie auf **Speichern**. {% endstep %} {% endstepper %} Die konfigurierte URL erscheint anschließend in der Benutzeroberfläche. Beim nächsten eingehenden Anruf werden die Inhalte automatisch abgerufen. ### Welche Rückgabeformate unterstützt der Agent? Ihr Agent verarbeitet Informationen aus Drittanwendungen nur, wenn sie in einem lesbaren Textformat zurückkommen. PDF-Dateien, Webseiten oder andere Dateiformate kann er nicht direkt auslesen. Unterstützt werden Plain Text, Markdown und JSON. Das gewünschte Format muss in der Anfrage angegeben werden, und der angebundene Server muss den passenden `Content-Type`-Header setzen: Beispiele: * Plain Text: `Content-Type: text/plain` * Markdown: `Content-Type: text/markdown` * JSON: `Content-Type: application/json` ### Welche Parameter werden an den Server übergeben? Ihr Agent übergibt beim Datenabruf Informationen an den angebundenen Server, damit dort passende Daten zum aktuellen Anruf gefunden werden können: ```json { "callerNumber": "+4915XXXXXXXXX", "destinationNumber": "4930xxxxxxx", "sessionId": "pbx-", "assistantId": "" } ``` **`callerNumber`**\ Die Rufnummer der anrufenden Person. **`destinationNumber`**\ Die Rufnummer, über die der Agent angerufen wurde. Wenn dem Agent mehrere Rufnummern zugewiesen sind, wird trotzdem nur die Rufnummer des aktuellen Anrufs übergeben. **`sessionId`**\ Die eindeutige ID des aktuellen Anrufs. Über diese ID kann der Server den Datenabruf eindeutig einem bestimmten Gespräch zuordnen. Die `sessionId` kann außerdem für Live-Anbindungen verwendet werden. So kann der Server denselben Anruf über mehrere Abfragen hinweg wiedererkennen, zum Beispiel zwischen dem initialen Datenabruf und späteren Live-Abfragen während des Gesprächs. **`assistantId`**\ Die interne ID des Agents. Diese ID ist eindeutig einem Agent zugeordnet und hilft dem Server, zwischen mehreren Agents zu unterscheiden. Der angebundene Server muss diese Parameter verarbeiten können und die passenden Informationen im unterstützten Rückgabeformat bereitstellen. ### Option: „Abruf erzwingen“ Mit dieser Checkbox legen Sie fest, wie strikt Ihr Agent mit Fehlern umgeht: * **Deaktiviert (Standard):** Ist die URL nicht erreichbar, wird der Anruf trotzdem durchgestellt, einfach ohne den zusätzlichen Kontext. * **Aktiviert:** Ist die URL nicht erreichbar, wird der Anruf abgelehnt. Wählen Sie das nur, wenn der Kontext unverzichtbar ist, etwa wenn ohne CRM-Daten kein sinnvolles Gespräch möglich ist. ### Datenabruf wieder entfernen 1. Öffnen Sie den Konfigurationsdialog erneut. 2. Klicken Sie auf **Datenabruf löschen**. 3. Bestätigen Sie mit **Endgültig löschen**. Bei kommenden Anrufen findet dann kein Datenabruf mehr statt. ### Häufige Fragen
Wie lange darf der Endpunkt für die Antwort brauchen? So kurz wie möglich. Der Datenabruf erfolgt synchron zu Beginn des Anrufs, lange Antwortzeiten verzögern den Gesprächsstart. Der Abruf startet bereits während des Klingelns und dauert in der Regel 2 bis 5 Sekunden. **Was passiert, wenn die 5 Sekunden überschritten werden?** Antwortet der Endpunkt nicht innerhalb von 5 Sekunden, wird der Abruf abgebrochen und Ihr Agent startet das Gespräch ohne die angefragten Informationen. Im Transkript wird nicht vermerkt, ob der Datenabruf fehlgeschlagen ist.
Was passiert, wenn ich die URL ändere? Beim nächsten eingehenden Anruf wird automatisch die neue URL abgerufen. Es gibt keinen Cache, der vorher geleert werden müsste.
Funktioniert das mit beliebigen URLs? Die URL muss per HTTP oder HTTPS erreichbar sein und eine gültige Top-Level-Domain enthalten. Eingaben ohne Protokoll wie `meine-firma.de` werden beim Speichern automatisch um `https://` ergänzt.
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.sipgate.de/ai-agents/anbindungen-and-integrationen/datenabruf-bei-anrufbeginn.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.