> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools & Webhooks

> Lass Assistenten im Gespräch Tools aufrufen und Anrufergebnisse per Webhook an deine Systeme senden

Assistenten können während eines Gesprächs Tools aufrufen, um etwas nachzuschlagen oder eine Aktion auszuführen. Wenn ein Anruf oder ein Gespräch endet, kann Famulor das Ergebnis per Webhook an deine Systeme übermitteln.

## Wiederverwendbare Assistenten-Tools

Lege Tools einmal auf der Seite **Tools** an und weise sie unter **Assistant → Settings → Tools** zu oder füge sie einem Flow hinzu. Aktualisierst du ein wiederverwendbares Tool, wirkt sich das auf jede Zuweisung aus.

### API-Tools

API-Tools rufen während eines Gesprächs einen HTTP-Endpunkt auf. Du legst fest:

* den Endpunkt und die Authentifizierung,
* die Eingaben, die der Assistent erfassen soll,
* feste Werte,
* was die Antwort enthalten soll, und
* ob der Anrufer eine kurze Fortschrittsphrase hören soll.

Verwende klare Beschreibungen und gib nur die Daten zurück, die der Assistent braucht, um das Gespräch fortzusetzen. Die Beschreibung eines Tools entscheidet auch, *wann* der Assistent darauf zurückgreift – formuliere die Auslösebedingung klar aus („nutze das, wenn der Anrufer nach einer bestehenden Bestellung fragt“) statt nur zu beschreiben, was das Tool tut.

| Methode  | Wofür                                                           |
| -------- | --------------------------------------------------------------- |
| `GET`    | Daten abrufen – eine Abfrage, eine Verfügbarkeitsprüfung        |
| `POST`   | Etwas Neues anlegen – eine Bestellung, ein Ticket, eine Buchung |
| `PUT`    | Einen bestehenden Datensatz vollständig ersetzen                |
| `PATCH`  | Bestimmte Felder eines bestehenden Datensatzes aktualisieren    |
| `DELETE` | Etwas entfernen                                                 |

Anfragen laufen standardmäßig nach 10 Sekunden in ein Timeout (konfigurierbar bis 120), und eine Antwort über 2 MB wird abgelehnt – halte Endpunkte schnell und Antworten klein. Verwende einen eingeschränkten API-Key nach dem Least-Privilege-Prinzip statt eines Master-Credentials, und halte kundenidentifizierende Details aus jeder Fehlermeldung heraus, die der Assistent vorlesen könnte.

Baue ein API-Tool, wenn sich die Antwort häufig ändert und der Endpunkt schnell und zuverlässig antwortet. Ändert sich die Information kaum, ist eine [Wissensdatenbank](/de/assistants/knowledge-base) oder der System-Prompt günstiger und kann nicht mitten im Anruf ausfallen.

**Beispielkonfigurationen**

Jeder Wert, den der Assistent erfasst, ist ein benannter Parameter mit einer Beschreibung, die festlegt, wonach er fragen soll. Parameter werden bei `GET` und `DELETE` im Query-String übertragen und bei `POST`, `PUT` und `PATCH` im JSON-Body. Um einen stattdessen in den Pfad zu setzen, schreibe `{{parameter_name}}` in die Endpunkt-URL. Setze die Quelle eines Parameters auf **Static** für einen festen Wert, nach dem der Assistent nie fragen muss, und halte Zugangsdaten in **Headers**.

| Muster                    | Methode | Einrichtung                                                                                                                     |
| ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Nachschlagen per ID       | `GET`   | Endpunkt `.../orders/{{order_number}}`, mit `order_number` als Parameter, den der Assistent erfasst                             |
| Etwas anlegen             | `POST`  | Endpunkt `.../appointments`, mit `date` und `service` als Parametern – sie werden im JSON-Body gesendet                         |
| Vor dem Fortfahren prüfen | `GET`   | Endpunkt `.../customers/lookup`, mit `phone` und `email` als Parametern – sie werden als Query-Werte gesendet                   |
| Nur benachrichtigen       | `POST`  | Endpunkt `.../notify` nur mit statischen Parametern; der Assistent bestätigt lediglich, dass er die Nachricht weitergegeben hat |

Der Assistent liest die Antwort und formuliert sie in eigenen Worten – gib deshalb kurze, klar benannte Felder zurück (`ship_date`, `confirmed_time`) statt eines verschachtelten Objekts, das er interpretieren müsste.

### Perplexity Agent Connector

Öffne **Tools → Agent Connectors**, wähle **Perplexity AI** und füge deinen eigenen API-Key ein. Mit **Load models** prüfst du den Key und rufst die aktuell für dein Konto verfügbaren Modelle ab. Dieselbe Modellauswahl steht später unter **Edit** zur Verfügung und lädt den Katalog erneut mit dem sicher gespeicherten Key. Du kannst einen optionalen System-Prompt hinzufügen und Temperature (Standard `0.2`), Top P (`0.9`), Presence Penalty (`0`) und Frequency Penalty (`1`) anpassen. Maximum Tokens ist standardmäßig leer und wird erst nach dem Setzen in Anfragen mitgeschickt. Der System-Prompt steuert Ton, Sprache, Stil und Antwortformat; die vollständige Rechercheanfrage liefert weiterhin der Assistent zur Laufzeit. Der gespeicherte Key wird maskiert und nie über die Tools-API zurückgegeben.

### Externe MCP-Server

Verbinde einen MCP-Server, indem du seine URL und, falls nötig, Authentifizierungsdaten einträgst. Du kannst alle angebotenen Tools erlauben oder nur die Tools auswählen, die ein Assistent nutzen darf. Greif darauf zurück, wenn die Gegenseite bereits ein ganzes MCP-Toolkit anbietet – eine einmalige Verbindung bringt jedes angebotene Tool mit; für einen einzelnen HTTP-Endpunkt ist ein einfaches API-Tool wie oben meist einfacher.

Eine URL, die auf `/mcp` endet, wird als Streamable HTTP behandelt, eine auf `/sse` als klassisches SSE; alles andere versucht zuerst Streamable HTTP und weicht dann auf SSE aus. Die Authentifizierung kann **none**, ein **static header or bearer token** oder **OAuth** sein – unterstützt der Server OAuth, führt Famulor den Anmeldevorgang durch und speichert das resultierende Token.

Die Liste **Installed** zeigt das Ergebnis der letzten Ausführung und markiert Verbindungen, die Aufmerksamkeit brauchen. Läuft OAuth ab, wähle beim bestehenden Tool **Reauthorize**. Der Anmeldevorgang repariert dieses Tool direkt vor Ort, sodass Zuweisungen, erlaubte Tools, Einstellungen und Ausführungshistorie erhalten bleiben.

Für jedes ausgewählte Tool steuerst du unter **Execution behavior** Abbruch, überlappende Aufrufe und gesprochene Fortschrittsmeldungen. Ein Abbruch kann eine bereits abgeschlossene Aktion des externen Diensts nicht rückgängig machen.

<Warning>
  Verbinde nur Dienste, denen du vertraust. Ihre Tool-Beschreibungen, Ergebnisse und Fortschrittsmeldungen können das Gespräch beeinflussen.
</Warning>

### Integrierte Tools

Integrierte Tools decken gängige Aktionen ab, etwa Anrufweiterleitung, Übergabe an einen anderen Assistenten, SMS, E-Mail, Geschäftszeiten-Prüfung, Rückrufe, Tastatureingaben, Zahlungskartenerfassung, Variablen und das Beenden eines Anrufs.

## Tools über die API verwalten

Verwende die öffentliche API, um die Tool-Verwaltung zu automatisieren:

* `GET /api/v1/tools` und `POST /api/v1/tools`
* `POST /api/v1/tools/perplexity/models`, um verfügbare Modelle mit einem übergebenen API-Key oder einer bestehenden Connector-ID aufzulisten
* `GET /api/v1/tools/{id}`, `PATCH /api/v1/tools/{id}` und `DELETE /api/v1/tools/{id}`
* `POST /api/v1/tools/{id}/reauthorize` für eine kurzlebige Browser-Anmelde-URL zu einem bestehenden OAuth-MCP-Tool
* `GET /api/v1/assistants/{id}/tools` und `PUT /api/v1/assistants/{id}/tools`
* `GET /api/v1/assistants/{id}/automations`, `POST /api/v1/assistants/{id}/automations` und `DELETE /api/v1/assistants/{id}/automations/{automationId}`

Der verbundene [MCP-Endpunkt](/de/api/mcp) bietet entsprechende Assistenten-Tool-Operationen, einschließlich `reauthorize_tool` und `list_perplexity_models`. Tool-Listen-Antworten enthalten den Verbindungsstatus ohne Geheimnisse und das Ergebnis der letzten Ausführung. Geheime Authentifizierungswerte werden nach dem Speichern maskiert.

Für eine [Automatisierung](/de/automations/overview), die der Assistent während eines Gesprächs aufrufen soll, verwende den Automatisierungs-Endpunkt des Assistenten oder das MCP-Tool `create_assistant_automation`. Beschreibe genau, wann sie laufen soll. Dieselbe Zuweisung steht in Sprach-, Webchat-, Messaging- und E-Mail-Gesprächen zur Verfügung. Die Plattform erstellt einen Entwurfs-Workflow und verbindet das benötigte Tool sicher, ohne Zugangsdaten zurückzugeben. Baue dessen Schritte, gib ein knappes, für gesprochene oder geschriebene Antworten geeignetes Ergebnis zurück und schalte die Automatisierung auf Live, sobald sie fertig ist; das Pausieren deaktiviert auch das aufrufbare Tool überall. Diese generierten Tools werden als von der Automatisierung verwaltet angezeigt und lassen sich nur über die Assistenten-Einstellungen bearbeiten oder trennen. Wiederholte Aufrufe im Gespräch nutzen denselben Lauf und dieselbe Antwort, sodass weder Abrechnung noch Nebenwirkungen doppelt auftreten.

## Anrufergebnisse per Webhook erhalten

Wenn ein Anruf endet, sendet Famulor das Ergebnis an die am Assistenten konfigurierte Webhook-URL (**Settings → Automations → Call completed**). Die URL ist unsigniert und gehört zu genau diesem einen Assistenten. Zustellungseinstellungen je Assistent – Timeout, Anzahl der Wiederholungen und ein Test-Versand – findest du unter [Webhooks nach dem Anruf](/de/assistants/webhooks).

E-Mail-Threads nutzen dieselbe Assistenten-URL: Sobald der Assistent geantwortet hat, liefert Famulor dort ein `conversation.ended`-Event mit dem Thread-Transkript und dessen Analyse. Telegram, Slack und die anderen Messaging-Connectors haben stattdessen ihre eigene **Conversation ended webhook URL**, die je Connector eingerichtet wird – siehe [Messaging-Kanäle](/de/channels/messaging).

<Note>
  Der eingehende **Variablen-Webhook** wird anders signiert – das ist die Assistenten-URL, die Famulor zu Beginn eines eingehenden Anrufs aufruft, um Variablen anzureichern. Diese Anfrage trägt eine HMAC-SHA256-Signatur; siehe [Benutzerdefinierte Variablen](/de/assistants/variables#eingehender-variablen-webhook).
</Note>

### `call.completed`

Das Ereignis enthält kundenrelevante Anrufdetails wie Assistent, Richtung, Status, Dauer, Zeitstempel, Transkript, erfasste Flow-Variablen, Kampagnenkontext und verfügbare Aufnahmelinks.

Kann der Anruf nicht abgeschlossen werden, enthält die Payload ein providerneutrales `failure`-Objekt mit stabilem Code, kundensicherer Meldung, Wiederholungshinweis und empfohlener Aktion. Baue deine Wiederherstellungslogik auf diesem Objekt auf, nicht auf infrastrukturspezifischen Details.

<Tip>
  Antworte zügig mit einem erfolgreichen `2xx`-Status. Erledige längere Folgearbeiten erst, nachdem du den Webhook bestätigt hast.
</Tip>

## Statt Webhook abfragen

Dasselbe Anrufergebnis kannst du über `GET /api/v1/calls`, `GET /api/v1/calls/{id}` oder die Anrufverlaufs-Tools in [MCP](/de/api/mcp) abrufen. Ein neu erstellter Anruf liefert zunächst seinen aktuellen Status; frage ihn ab, bis er einen Endstatus erreicht.