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

# Tools & Webhooks

> Gib Assistenten während Anrufen Tools an die Hand und erhalte danach die Ergebnisse

## Zentrale Tool Registry

Lege API-, MCP- und Built-in-Tools einmal auf der Seite **Tools** an.
Assistenten und Flows referenzieren nur diese zentralen Definitionen. Eine
Änderung gilt dadurch für jeden zugewiesenen Assistenten und Flow, ohne das
Tool erneut einzubauen.

* Zuweisungen verwaltest du unter **Assistant → Settings → Tools**.
* API- und Built-in-Tools lassen sich in der durchsuchbaren
  **Add node**-Bibliothek des Flow Builders direkt hinzufügen.
* Im Node bleiben nur Ablauf- und Routingdaten. Endpoint, Auth,
  Transferziel, Prompt und andere gemeinsame Einstellungen liegen auf
  **Tools**.
* MCP-Einträge stehen für einen kompletten Server und sind deshalb
  Assistant-weit, nicht ein einzelner deterministischer Flow-Node.

Neue Flows besitzen keinen Inline-Modus zur Tool-Definition. Bestehende
Inline-Tools werden als getrennte Registry-Einträge migriert.

### API-Tools

API-Tools rufen HTTP-Endpunkte während des Gesprächs auf. Parameter, statische
Werte, Response-Mappings, Async-Verhalten und Füllsätze werden einmal definiert
und anschließend wiederverwendet.

### MCP-Server

Ein MCP-Tool verbindet einen externen Server mit optionaler Authentifizierung
und Tool-Allowlist:

* Der Transport wird automatisch erkannt (Streamable HTTP oder SSE).
* Eine leere Whitelist bedeutet, dass *alle* Tools dieses Servers erlaubt sind.
* Zu große Tool-Ergebnisse werden sicher gekürzt.
* Ein nicht erreichbarer MCP-Server blockiert nie einen Anruf – er wird übersprungen und als Anruf-Event protokolliert.

### Built-in-Tools

Built-ins umfassen Call Transfer, Warm Transfer, Transfer zu einem anderen
Assistant, SMS, E-Mail, Geschäftszeiten, Rückrufe, DTMF/Keypad, sichere
Kartenerfassung, Variablen und End Call.

Cold- und Warm-Transfer akzeptieren eine E.164-Telefonnummer oder eine
`sip:` URI wie `sip:sales@example.com`. Beim Assistant-Transfer lässt sich
festlegen, welche Gesprächsnachrichten das Ziel erhält.

### API- und MCP-Verwaltung

* **REST-API:** [`GET`/`POST /tools`, `GET`/`PATCH`/`DELETE /tools/{id}`](/api-reference/introduction), `/tools/{id}/usage`, `/tools/{id}/versions`, Restore und revisionsgeschützte Assistant-Zuweisungen.
* **MCP:** [`list_tools`, `get_tool`, `get_tool_usage`, `create_tool`, `update_tool`, `delete_tool`, `list_tool_versions`, `restore_tool_version`, `get_assistant_tools`, `set_assistant_tools`](/api/mcp#available-tools).

Tool-Antworten enthalten eine monotone Revision. Sende beim Aktualisieren
eines Tools oder Ersetzen von Zuweisungen die erwartete Revision, damit
parallele Änderungen nicht verloren gehen. Versions-, Usage- und
Restore-Funktionen stehen in REST und MCP zur Verfügung.

`DELETE` archiviert nur unbenutzte Tools und liefert bei vorhandenen
Referenzen `409 tool_in_use`. Mit `PATCH` und `is_active: false` stoppst du
neue Ausführungen sowie die Nutzung in laufenden Calls sofort, ohne
Zuweisungen zu entfernen.

Geheime Werte verlassen den Server nie und werden als `•••` maskiert.
Laufende Calls übernehmen gültige Änderungen an einer sicheren Tool-Grenze;
bei einem Reload-Fehler bleibt der letzte funktionierende Snapshot aktiv.

## Webhooks nach dem Anruf

Sobald ein Anruf endet, schickt dir die Plattform das Ergebnis – der Standardweg, um CRMs und nachgelagerte Automatisierungen zu füttern.

### `call.completed`

Wird an zwei Arten von Empfängern gesendet:

1. **Webhook-URL pro Assistent** – schnell eingerichtet, unsigniert.
2. **Workspace-Webhooks** – zentral verwaltet, **signiert** mit HMAC-SHA256 über den rohen Body:

```text theme={null}
X-Famulor-Signature: sha256=<hex digest>
```

Zur Verifizierung berechnest du den HMAC des rohen Request-Bodys mit deinem Webhook-Secret und vergleichst die Digests.

### Inhalt des Payloads

Das Payload enthält Anruf-Metadaten (Assistent, Richtung, Status, Dauer, Zeitstempel), das **Transkript**, gesammelte **Flow-Variablen** (aus [Collect-Nodes](/flow-builder/nodes#collect)), Lead-/Kampagnenkontext bei Kampagnenanrufen sowie Links zu Artefakten wie der Aufnahme.

Schlägt ein ausgehender Anruf fehl, enthält `data.failure` dasselbe
anbieterneutrale Objekt wie `GET /calls/{id}`:

```json theme={null}
{
  "operation": "outbound_call",
  "code": "busy",
  "message": "The destination is busy. Try again later.",
  "retryable": true,
  "action": "retry_later"
}
```

Rohe SIP-Statuswerte, Verbindungsdiagnosen und SDK-Fehlertexte bleiben intern.
Ein erneut gesendeter Webhook wird aus dem aktuellen gespeicherten Anruf
aufgebaut und enthält den normalisierten Fehler auch für ältere Anrufe.

<Tip>
  Antworte schnell mit `2xx` (unter ein paar Sekunden) und verarbeite die Daten asynchron. Antworten ohne 2xx gelten als Zustellungsfehler.
</Tip>

## Abrufen statt Pushen

Alles, was ein Webhook liefert, lässt sich auch über die [REST-API](/api-reference/introduction) (`GET /calls`, `GET /calls/{id}`) oder die [MCP-Tools](/api/mcp#available-tools) (`list_calls`, `get_call`) abrufen – nützlich für Abgleichs-Jobs und Backfills. `POST /calls` bleibt asynchron und liefert `queued`; den endgültigen `status` und optionalen `failure` erhältst du per Polling oder Webhook.