> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Grundlegende Konzepte
> Eine Übersicht über alles in der Plattform — was jedes Objekt tut, wo es sich im Dashboard befindet und welche API darauf zugreift.
ThunderPhone ist eine vollständige Plattform zum Erstellen, Betreiben und Verbessern
von KI-Sprachagenten. Diese Seite ist die Übersicht: jedes Konzept, dem Sie begegnen,
jeweils in einem kurzen Abschnitt, mit der entsprechenden Dashboard-Ansicht und der
zugrunde liegenden API. Überfliegen Sie sie einmal und kehren Sie zurück, wenn ein Begriff
näher erläutert werden muss.
Die Dashboard-Seitenleiste spiegelt diese Struktur wider:
[Agenten](#agents), [Telefonnummern](#phone-numbers),
[Web-Widgets](#web-widgets), [Anrufe](#calls),
[Wissensdatenbanken](#knowledge-bases).
[Live-Überwachung](#live-monitoring) und ausgehende
[Kampagnen](#campaigns).
[Apps, APIs, MCP-Server und VoIP-Anbieter](#connections), die Ihre
Agenten verwenden können.
[Simulationen](#simulations), [Experimente](#experiments),
[Probleme](#issues), [Berichte](#reports),
[Beobachtbarkeit](#observability).
[Team & Rollen](#team-and-roles), [API-Schlüssel](#organizations),
[Benachrichtigungen](#alerts), [Abrechnung](#billing).
[Webhooks](#webhooks) und [Funktions-Tools](#function-tools) für
Ihren eigenen Code.
***
## Organisationen
Eine **Organisation** ist die Mandanteneinheit. Jede andere Ressource —
Agenten, Telefonnummern, Anrufe, Schlüssel — gehört genau einer Organisation. Ihr
Konto kann mehreren Organisationen angehören; jede hat ihr eigenes Guthaben, ihre eigenen
Schlüssel und ihre eigene Mitgliederliste.
Der `sk_live_`-API-Schlüssel, den Sie unter **Organisation → Schlüssel** erstellen, ist
an eine Organisation gebunden. Diese Bindung macht die REST-API so
flach: Sie geben nie eine Organisations-ID in URL-Pfaden an, weil Ihr Schlüssel sie bereits
identifiziert.
**Im Dashboard:** der Organisationswechsler (im Fußbereich der Seitenleiste) und
die Einstellungen unter **Organisation** — Registerkarten für Allgemein, Schlüssel, Benachrichtigungen,
Abrechnungseinstellungen und Abrechnungsverlauf.
**In der API:** [`/v1/orgs`](/api-reference/organizations),
[`/v1/developer/api-keys`](/api-reference/developer-api-keys).
***
## Agenten
Ein **Agent** ist die KI-Konfiguration, die einen Anruf ausführt. Sie umfasst:
* Einen **Prompt**, der bestimmt, was der Agent sagt und wie er sich verhält —
einschließlich Anrufaktionen wie Weiterleitungen, Tastendrücken und Auflegen,
die einfache Prompt-Zeilen und keine separate Konfiguration sind.
* Eine **Engine-Stufe** (`spark`, `bolt`, `storm-*`): Spark ist für
Kosten optimiert, Bolt für Geschwindigkeit und Storm für Intelligenz bei komplexen Prompts.
* Eine **Stimme** sowie eine **primäre Sprache** und optionale **zusätzliche
Sprachen** — der Agent wechselt automatisch, wenn ein Anrufer die
Sprache wechselt. Siehe [Unterstützte Sprachen](/de/guides/supported-languages).
* Zugeordnete Funktionen: [verbundene Apps](#connections),
[API-Verbindungen](#connections), [Wissensdatenbanken](#knowledge-bases),
[MCP-Server](#connections) und eingebundene
[Funktions-Tools](#function-tools).
* Verhaltensoptionen: Sprechreihenfolge, Bestätigungsmodus, Hintergrundspur,
Wartezeitlimit.
Änderungen im Builder werden **automatisch als Entwurf gespeichert**; nichts wird veröffentlicht, bis
Sie auf **Bereitstellen** klicken. Jede Bereitstellung wird in der Registerkarte
**Verlauf** des Builders als Snapshot gespeichert, sodass Sie jede frühere Version prüfen und wiederherstellen können.
**Im Dashboard:** **Sprachagenten** → der Agent-Builder
(`/dashboard/agents`). Siehe
[Erstellen Sie Ihren ersten Sprachagenten](/de/guides/build-an-agent).
**In der API:** [`/v1/agents`](/api-reference/agents) — CRUD,
duplizieren, weiterleiten, Versionsverlauf und Prompt-Hilfsfunktionen.
***
## Telefonnummern
Eine **Telefonnummer** gehört zu einer Organisation und leitet eingehende Anrufe an einen
Agenten weiter (und kann für ausgehende Anrufe verwendet werden). Zwei Quellen:
* **Demo-Nummern** — echte US-Telefonnummern aus dem
ThunderPhone-Pool, in Sekundenschnelle aktiv. Nur für eingehende Anrufe, sie melden sich mit einem kurzen gesprochenen
Hinweis, und das Dashboard begrenzt eine Organisation auf 10 davon. Perfekt für
einen ersten Test, nicht für die Produktion.
* **VoIP-Nummern** — über eine eigene
[VoIP-Verbindung](#connections) von Ihrem Anbieter eingebracht. Twilio und Telnyx lassen sich direkt verbinden
(Telnyx bietet eine geführte Einrichtung); SignalWire und Vonage folgen demnächst —
derzeit erreichen Sie sie über eine manuelle SIP-Konfiguration, die jeden
SIP-Trunk akzeptiert. Nach dem Import und der Verifizierung unterstützen VoIP-Nummern eingehende
und ausgehende Anrufe.
In jeder Nummernzeile können Sie einen Routing-Modus festlegen, den Agenten für eingehende Anrufe auswählen
und die Nummer beschriften.
**Im Dashboard:** **Telefonnummern** (`/dashboard/phone-numbers`).
Siehe [Telefonnummer erhalten](/de/guides/get-a-phone-number).
**In der API:** [`/v1/phone-numbers`](/api-reference/phone-numbers),
[`/v1/voip-connections`](/api-reference/voip-connections),
[`/v1/phone-number-labels`](/api-reference/phone-number-labels).
***
## Anrufe
Jeder eingehende Anruf, ausgehende Anruf, jede Simulation und jede Widget-Sitzung
wird zu einem **Anrufprotokoll**. Ein Anruf enthält das vollständige mit Rollen versehene Transkript,
den strukturierten Verlauf der Gesprächszüge (einschließlich Tool-Aufrufen), eine Aufzeichnung,
die Gesamtabrechnung sowie optionale KI-Bewertungen und Problemberichte.
Während ein Anruf **live** ist, können Sie ihn öffnen und **mithören** — Sie nehmen
lautlos teil, und niemand im Anruf hört Sie. Sobald Sie mithören, können Sie
**zuflüstern**: Geben Sie eine Anweisung ein, die direkt während des Anrufs an Ihren Agenten
gesendet wird; der Anrufer hört sie nie, und der Agent befolgt sie live.
**Im Dashboard:** **Anrufverlauf** (`/dashboard/call-history`) für
das Archiv und Details zu einzelnen Anrufen; **Live** für laufende Anrufe. Siehe
[Anrufe prüfen, mithören und coachen](/de/guides/review-calls).
**In der API:** [`/v1/calls`](/api-reference/calls) — Liste, Transkript,
Verlauf, Audio, Bewertung, Export;
[`/v1/issue-reports`](/api-reference/issue-reports).
***
## Web-Widgets
Das **Web-Widget** ermöglicht Ihren Website-Besuchern eine mikrofonbasierte Unterhaltung
mit einem Agenten — keine Telefonnummer erforderlich. Es authentifiziert sich mit einem
**veröffentlichbaren Schlüssel** (`pk_live_...`), der an Ihre
zulässigen Domains gebunden ist und daher sicher in clientseitigem Code verwendet werden kann.
Schlüssel werden in einem von zwei Modi verwendet: `agent` (statisch an einen Agenten gebunden)
oder `webhook` (Ihr Server wählt die Konfiguration pro Besucher — siehe
[Dynamische Konfiguration pro Anruf](/de/guides/dynamic-call-config)). Widget-Sitzungen
laufen über dieselbe Anrufinfrastruktur wie Telefonanrufe.
**Im Dashboard:** **Web-Widgets** (`/dashboard/web-widgets`) —
erstellen Sie Widgets, legen Sie Modus und Agenten fest, verwalten Sie zulässige Domains und
kopieren Sie das Einbettungs-Snippet. Siehe
[Web-Widget erstellen](/de/guides/embed-a-web-widget-dashboard).
**In der API:** [`/v1/publishable-key`](/api-reference/publishable-keys),
[`/v1/mic-session`](/api-reference/mic-sessions) und die
[Widget-SDK-Dokumentation](/de/widget/overview).
***
## Wissensdatenbanken
Eine **Wissensdatenbank** ist eine Sammlung von Dokumenten, die Ihr Agent während eines Anrufs durchsuchen
kann, um seine Antworten zu fundieren — laden Sie Dateien direkt hoch oder importieren Sie sie aus
Google Drive und fügen Sie die Wissensdatenbank dann im Builder einem Agenten hinzu. Der
Agent fragt sie mit einem integrierten Such-Tool ab, wenn die
Unterhaltung es erfordert.
**Im Dashboard:** **Wissen** (`/dashboard/knowledge`) für die
Dokumentbibliothek; der Bereich **Wissen** im Builder, um sie einem
Agenten hinzuzufügen. Siehe
[Geben Sie Ihrem Agenten eine Wissensdatenbank](/de/guides/knowledge-base).
***
## Verbindungen
Verbindungen ermöglichen Agenten den Zugriff auf die Außenwelt. Vier Arten,
eine Seitenleistengruppe:
* **Apps** (`/dashboard/app-connections`) — OAuth-Verbindungen zu
Slack, HubSpot, Salesforce, Google Calendar, Google Sheets und
Cal.com. Einmal verbinden und dann Tools für einzelne Vorgänge
(eine Slack-Nachricht senden, einen HubSpot-Kontakt aktualisieren oder erstellen, einen Cal.com-Termin buchen …)
für jeden Agenten aktivieren. Siehe [Apps verbinden](/de/guides/connect-apps).
* **APIs** (`/dashboard/api-connections`) — jede HTTP-API in eine
Agentenaktion verwandeln. Fügen Sie einen cURL-Befehl ein, und der
KI-Assistent erstellt einen Entwurf für die Tool-Definition, oder
erstellen Sie sie manuell; die Schaltfläche **Anfrage testen** führt
vor der Veröffentlichung einen Sandbox-Aufruf aus. Siehe
[API-Verbindungen](/de/guides/api-connections) — die Dashboard-Oberfläche von
[`/v1/integrations`](/api-reference/integrations).
* **MCP** (`/dashboard/mcp-connections`) — fügen Sie einen Model Context
Protocol-Server per URL hinzu und lassen Sie den Agenten die
bereitgestellten Tools verwenden. Siehe [Einen MCP-Server hinzufügen](/de/guides/mcp-servers).
* **VoIP** (`/dashboard/voip-connections`) — Anbieterzugangsdaten für
[die Verwendung eigener Telefonnummern](#phone-numbers). Siehe
[Einen VoIP-Anbieter verbinden](/de/guides/voip-providers).
**In der API:** [`/v1/integrations`](/api-reference/integrations) und
[`/v1/voip-connections`](/api-reference/voip-connections); siehe auch
[Eine Tool-Integration erstellen](/de/guides/build-tool-integration).
***
## Kampagnen
Eine **Kampagne** führt ausgehende Anrufe im großen Maßstab durch: Laden Sie
eine CSV-Datei mit Kontakten hoch, wählen Sie den Agenten und die
Absendernummer aus und legen Sie das Anruffenster
(Tage und Stunden mit Zeitzonenunterstützung), die Parallelität und die
Wiederholungsrichtlinie fest (maximale Anzahl der Versuche und welche Ergebnisse —
keine Antwort, Mailbox, fehlgeschlagen — erneut versucht werden).
Die Kampagne arbeitet die Liste ab und zeichnet jeden Anruf im Anrufverlauf auf.
**Im Dashboard:** **Kampagnen** (`/dashboard/campaigns`). Siehe
[Eine Kampagne für ausgehende Anrufe ausführen](/de/guides/outbound-campaigns).
**Für einzelne programmatische Anrufe:** die
[API für ausgehende Anrufe](/de/guides/place-outbound-calls).
***
## Live-Überwachung
**Live** zeigt jeden laufenden Anruf in der gesamten Organisation und ermöglicht
Ihnen, jeden davon zu öffnen, um [mitzuhören und einzuflüstern](#calls) in Echtzeit. Es ist
die Überwachungsansicht: Beobachten Sie, wie ein neuer Prompt seinen ersten echten
Traffic verarbeitet, oder behalten Sie eine laufende Kampagne im Blick.
**Im Dashboard:** **Live** (`/dashboard/live`). Siehe
[Live-Anrufe beobachten und überwachen](/de/guides/monitor-live-calls).
***
## Simulationen
Eine **Simulation** ist ein KI-Anrufer, der ein echtes Gespräch mit Ihrem
Agenten führt — derselbe Telefoniepfad, echtes Transkript, echte Bewertung —
damit Sie vor (und nach) der Veröffentlichung testen können. Richten Sie sie auf einen
Agenten oder eine Telefonnummer aus, schreiben Sie das Anruferszenario selbst oder **generieren Sie Szenarien
mit KI** aus dem Prompt des Agenten (einschließlich Randfällen, wenn Sie danach fragen),
und verfolgen Sie den Anruf live.
Szenarien werden in **Suites** gruppiert, die eine Mindest-Erfolgsquote festlegen und
als Release-Gate in CI dienen können; Regressionen gegenüber der akzeptierten
Referenz werden pro Szenario gemeldet.
**Im Dashboard:** **Simulationen** (`/dashboard/simulations`) sowie
die Schaltfläche **Simulation** im Agent-Builder. Siehe
[Einen Anruf simulieren](/de/guides/simulate-a-call).
**In der API:** [`/v1/test-calls`](/api-reference/test-calls) und der
Suite-Runner — siehe [Einen Agenten Ende-zu-Ende testen](/de/guides/test-agents).
***
## Experimente
Ein **Experiment** führt A/B-Tests von Agentenkonfigurationen mit Live-Traffic durch:
Definieren Sie Varianten (unterschiedliche Prompts, Engines oder Einstellungen),
teilen Sie den Traffic zwischen ihnen auf und vergleichen Sie die Ergebnisse pro
Variante. Verwenden Sie dies, statt Bucket-Logik in einem Webhook selbst zu implementieren.
**Im Dashboard:** **Experimente** (`/dashboard/experiments`) und
der Tab **A/B** im Agent-Builder. Siehe
[Experimente (A/B-Tests)](/de/guides/experiments-ab-testing).
***
## Probleme
Ein **Problem** ist ein markiertes Problem bei einem bestimmten Anruf — gemeldet von einem
menschlichen Prüfer oder durch KI-Bewertung erkannt. Probleme enthalten Schweregrad,
Quelle und Status, und die Seite „Probleme“ ist die Triage-Warteschlange: Filtern Sie,
prüfen Sie den betreffenden Anruf und verfolgen Sie Fehlerbehebungen.
**Im Dashboard:** **Probleme** (`/dashboard/issues`) sowie anrufspezifische
Markierungen im Anrufverlauf. Siehe [Problem-Triage](/de/guides/issues).
**In der API:** [`/v1/issue-reports`](/api-reference/issue-reports).
***
## Berichte
Ein **Bericht** beantwortet eine natürlichsprachliche Frage zu Ihren Anrufdaten
(„Was waren letzte Woche die drei häufigsten Gründe, aus denen Anrufer nach einem
Menschen fragten?“) mit einer von KI verfassten Analyse, begrenzt auf die von Ihnen
ausgewählten Agenten und den gewählten Datumsbereich.
**Im Dashboard:** **Berichte** (`/dashboard/reports`). Siehe
[Berichte](/de/guides/reports).
***
## Observability
**Observability** ist die Oberfläche für Metriken: Anrufvolumen, Ergebnisse und
Qualität im Zeitverlauf, filterbar nach Agent und Zeitfenster, mit Export für
nachgelagerte Analysen.
**Im Dashboard:** **Observability** (`/dashboard/observability`).
Siehe [Observability](/de/guides/observability).
***
## Warnungen
Eine **Warnregel** überwacht eine Metrik (Erfolgsrate, Fehlerrate,
durchschnittliche Bewertung, Anrufvolumen, Suite-Regressionen) über ein Zeitfenster
und wird ausgelöst, wenn sie Ihren Schwellenwert überschreitet. Benachrichtigungen
werden per E-Mail und Slack gesendet und lösen ein Ereignis `alert.triggered` an Ihre
[Webhook-Endpunkte](/de/webhooks/endpoints) aus.
**Im Dashboard:** **Organisation → Warnungen**. Siehe
[Warnungen](/de/guides/alerts).
***
## Webhooks
ThunderPhone sendet **HTTP-POST-Webhooks** an Ihren Server, wenn während und nach
einem Anruf Ereignisse eintreten. Zwei Zustellmodelle:
* **Webhook-Endpunkte** (empfohlen): Verwalten Sie mehrere URLs unter
[`/v1/developer/webhook-endpoints`](/de/webhooks/endpoints) mit
endpunktspezifischen Secrets und endpunktspezifischen Ereignisabonnements.
* **Legacy-Webhooks mit einzelner URL**: eine URL pro Organisation. Verwaltet unter
[`/v1/webhook`](/api-reference/organizations#legacy-single-url-webhook)
oder unter **Organisation → Allgemein**. Zur Abwärtskompatibilität beibehalten.
Ereignisse werden in zwei Klassen unterteilt:
* **Blockierende Ereignisse** erwarten von Ihrem Server eine Antwort mit einer
Konfiguration, die den laufenden Anruf beeinflusst — die
[Ereignisse für eingehende Anrufe](/de/webhooks/call-incoming)
(`telephony.incoming` / `web.incoming`). Sie haben bis zu 10 Sekunden Zeit
zu antworten; bei einer Zeitüberschreitung bearbeitet der statisch zugewiesene Agent
den Anruf.
* **Nicht blockierende Ereignisse** sind Fire-and-forget-Benachrichtigungen, die
mit exponentiellem Backoff erneut versucht werden — siehe
[Zustellsemantik](/de/webhooks/overview).
Jede Anfrage enthält eine HMAC-SHA256-Signatur in
`X-ThunderPhone-Signature`. Siehe
[Signaturüberprüfung](/de/webhooks/overview).
***
## Funktions-Tools
Ein **Funktions-Tool** ist ein HTTP-Endpunkt, den Ihr Agent während eines Gesprächs
aufrufen kann. Sie stellen ThunderPhone ein Funktionsschema im OpenAI-Stil sowie eine
Endpunkt-URL bereit; der Agent entscheidet, wann er sie aufruft, und ThunderPhone
sendet die signierte HTTP-Anfrage von seinen Servern und übergibt das Ergebnis an den
Agenten zurück.
Agenten enthalten außerdem **integrierte Anruffunktionen** — den Anruf weiterleiten,
Tastatureingaben (DTMF) senden, den Anruf beenden, in der Warteschleife warten — die
Sie mit einfachen Prompt-Zeilen statt mit Tool-Definitionen aktivieren.
**Im Dashboard:** der Bereich **API-Verbindungen** des Builders (siehe
[Verbindungen](#connections)).
**In der API:** [`/v1/integrations`](/api-reference/integrations) und
die [Spezifikation für Funktions-Tools](/de/tools/overview).
***
## Team und Rollen
Jede Organisation hat eine Mitgliederliste mit zwei Rollen: **Mitglieder** erstellen
und betreiben Agenten; **Administratoren** verwalten zusätzlich das Team und die
Abrechnung. Laden Sie per E-Mail ein — Einladungen laufen nach 7 Tagen ab und können
widerrufen werden; das Menü ⋯ in einer Mitgliederzeile ändert Rollen oder entfernt
jemanden. Single Sign-On kann organisationsweit konfiguriert werden — siehe
[SSO](/de/guides/sso).
**Im Dashboard:** **Organisation → Allgemein**. Siehe
[Team einladen](/de/guides/invite-your-team).
**In der API:** [`/v1/members`](/api-reference/members),
[`/v1/invites`](/api-reference/invites).
***
## Abrechnung
ThunderPhone ist **Prepaid**. Jede Organisation verfügt über ein USD-Guthaben; Anrufe belasten es zum Minutenpreis des Agenten (Engine-Stufe plus Zuschläge —
der Builder zeigt den Gesamtpreis live an, wenn Sie Einstellungen ändern, und
[Premiumsprachen](/de/guides/supported-languages) kosten zusätzlich 2 ¢/Min.). Wenn das
Guthaben null erreicht, werden eingehende Anrufe abgewiesen und ausgehende Anrufe
geben `402 Payment Required` zurück.
Laden Sie Guthaben manuell auf oder aktivieren Sie **automatisches Aufladen** mit einem Guthabenschwellenwert, einem
Aufladebetrag und einem optionalen monatlichen Ausgabenlimit — damit ein Anruf
nie mitten im Satz abbricht.
**Im Dashboard:** **Organisation → Abrechnungseinstellungen** und
**Abrechnungsverlauf**. Siehe
[Guthaben hinzufügen und automatisches Aufladen aktivieren](/de/guides/billing-and-topups).
**In der API:** [`/v1/billing`](/api-reference/billing).
***
## Der In-App-Copilot
Das Dashboard enthält einen integrierten **Copiloten** — fragen Sie ihn „wie mache ich X“,
und er antwortet anhand dieser Docs, bietet Klick-für-Klick-Anleitungen,
die die tatsächlichen Bedienelemente hervorheben, und kann jede der geführten
Touren erneut abspielen. So finden Sie am schnellsten ein Bedienelement, das auf dieser Seite erwähnt wird.
Siehe [Den In-App-Copiloten fragen](/de/guides/ask-the-copilot).
***
## Alles zusammenführen
Der Assistent mit fünf Schritten: Agent → Abrechnung → Nummer → Simulation → Überprüfung.
Derselbe erste Anruf in vier REST-Aufrufen.
Erstellen Sie einen Agenten, laden Sie Guthaben auf, erhalten Sie eine Nummer, simulieren und überprüfen Sie Anrufe.
OAuth-Apps, benutzerdefinierte APIs, MCP-Server und VoIP-Anbieter.
Berichte, Observability, Experimente, Probleme und Warnungen.
Einladungen und Rollen, API-Schlüssel, Sicherheit und SSO.
Die API-Rezepte: eingehend, ausgehend, dynamische Konfiguration, Tools, Tests.
Prüfen Sie HMAC einmal korrekt und verwenden Sie es überall wieder.