Grundlegende Konzepte

Ein Überblick über alles auf der Plattform – was jedes Objekt tut, wo es sich im Dashboard befindet und welche API damit interagiert.

ThunderPhone ist eine vollständige Plattform zum Entwickeln, Betreiben und Verbessern von KI-Sprachagenten. Diese Seite ist die Übersicht: jedes Konzept, dem Sie begegnen, in einem kurzen Abschnitt, mit der Dashboard-Oberfläche 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:

Organisationen#

Eine Organisation ist die Mandanteneinheit. Jede andere Ressource — Agenten, Telefonnummern, Anrufe, Schlüssel — gehört genau einer Organisation. Ihr Konto kann zu vielen Organisationen gehören; jede hat ihr eigenes Guthaben, ihre eigenen Schlüssel und ihre eigene Mitgliederliste.

Der API-Schlüssel sk_live_, den Sie unter Organisation → Schlüssel erstellen, ist an eine Organisation gebunden. Diese Bindung macht die REST-API so flach: Sie geben niemals eine Organisations-ID in URL-Pfaden an, weil Ihr Schlüssel sie bereits identifiziert.

Im Dashboard: die Organisationsauswahl (im Fußbereich der Seitenleiste) und die Einstellungen unter Organisation — Registerkarten für Mein Konto, Allgemein, Schlüssel, Warnungen, Abrechnungseinstellungen und Abrechnungsverlauf. Siehe die Referenz zu Organisationseinstellungen.

In der API: /v1/orgs, /v1/developer/api-keys.

Agenten#

Ein Agent ist die KI-Konfiguration, die einen Anruf ausführt. Er bündelt:

• Einen Prompt, der bestimmt, was der Agent sagt und wie er sich verhält — einschließlich Anrufaktionen wie Weiterleitungen, Tastatureingaben 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, 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.
• Zugeordnete Funktionen: verbundene Apps, API-Verbindungen, Wissensdatenbanken, MCP-Server und eingebettete Funktionstools.
• Verhaltensoptionen: Sprechreihenfolge, Bestätigungsmodus, Hintergrundtonspur, Wartezeit-Timeout.

Änderungen im Builder werden automatisch als Entwurf gespeichert; nichts wird live geschaltet, 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.

In der API: /v1/agents — CRUD, duplizieren, weiterleiten, Versionsverlauf und Prompt-Hilfsfunktionen.

Stimmen#

Die Stimmenbibliothek enthält die Stimmen, die ein Agent verwenden kann, ihre abspielbaren Beispiele, kompatiblen Sprachen, Gruppierungen nach Geschlecht und Akzent sowie mögliche Aufpreise für Premium-Stimmen/-Sprachen. Mit einer kostenpflichtigen Vorschaufunktion können Sie vor der Auswahl eine eigene Phrase mit 1–500 Zeichen synthetisieren.

Berechtigte Organisationen können auch benutzerdefinierte Stimmen aus einer kurzen WAV- oder MP3-Datei erstellen. Benutzerdefinierte Stimmen haben ein Kontingent und einen asynchronen Erstellungsstatus; sobald sie bereit sind, erscheinen sie in derselben Agentenauswahl wie Bibliotheksstimmen.

Im Dashboard: Stimmen (/dashboard/voices). Siehe Stimmenbibliothek und benutzerdefinierte Stimmen.

In der API: /v1/voices, Stimmbeispiele und benutzerdefinierte Stimmen.

Telefonnummern#

Eine Telefonnummer gehört zu einer Organisation und leitet eingehende Anrufe an einen Agenten weiter (und kann für ausgehende Anrufe verwendet werden). Es gibt zwei Quellen:

• ThunderPhone-Nummern — echte US-Nummern, die aus dem Pool von ThunderPhone bereitgestellt werden und in Sekunden aktiv sind, $1/Monat plus 1 ¢/Min. Aufpreis. Sie sind zunächst nur für eingehende Anrufe verfügbar. Ein Organisationsadministrator kann auf der Seite „Telefonnummern“ ausgehende Anrufe anfordern; ThunderPhone prüft jede Anfrage manuell, und genehmigte Nummern können Anrufe tätigen und Kampagnen durchführen. Eine Organisation kann standardmäßig 25 Nummern besitzen.
• VoIP-Nummern — von Ihrem eigenen Anbieter über eine VoIP-Verbindung eingebracht. Twilio und Telnyx werden direkt mit einem API-Schlüssel verbunden (Telnyx bietet zudem eine geführte Einrichtung für neue Konten); SignalWire, Vonage, Plivo und jeder andere SIP-Trunk werden über die SIP- Einrichtung verbunden, eine manuelle SIP-Konfiguration. Nach dem Import und der Verifizierung unterstützen VoIP- Nummern eingehende und ausgehende Anrufe.

In jeder Nummernzeile können Sie einen Routingmodus festlegen, den Agenten für eingehende Anrufe auswählen und die Nummer beschriften.

Im Dashboard: Telefonnummern (/dashboard/phone-numbers). Siehe Telefonnummer erhalten.

In der API: /v1/phone-numbers, /v1/voip-connections, /v1/phone-number-labels.

Anrufe#

Jeder eingehende Anruf, ausgehende Anruf, jede Simulation und Widget-Sitzung wird zu einem Anrufprotokoll. Ein Anruf enthält das vollständige, nach Rollen gekennzeichnete Transkript, den strukturierten Gesprächsverlauf (einschließlich Tool-Aufrufen), eine Aufzeichnung, den Rechnungsbetrag sowie optionale KI-Bewertungen und Problemberichte.

Während ein Anruf live ist, können Sie ihn öffnen und mithören — Sie nehmen unbemerkt teil, und niemand im Anruf hört Sie. Sobald Sie mithören, können Sie flüstern: Geben Sie eine Anweisung ein, die während des Anrufs direkt an Ihren Agenten geht; der Anrufer hört sie nie, und der Agent befolgt sie live.

Im Dashboard: Anrufverlauf (/dashboard/call-history) für das Archiv und Details pro Anruf; Live für laufende Anrufe. Siehe Anrufe überprüfen, mithören und coachen.

In der API: /v1/calls — Liste, Transkript, Verlauf, Audio, Bewertung, Export; /v1/issue-reports.

Kundenportale#

Ein Kundenportal ist eine gebrandete, schreibgeschützte Ansicht des Anrufverlaufs für einen externen Kunden. Organisationsadministratoren wählen die Agenten aus, deren Anrufe angezeigt werden, fügen genehmigte E-Mail-Adressen von Betrachtern hinzu, laden ein Logo und eine Akzentfarbe hoch und verifizieren optional eine benutzerdefinierte Domain. Portalbetrachter können Anrufdetails, Transkripte und verfügbare Aufzeichnungen prüfen, ohne Zugriff auf das Dashboard zu erhalten.

Im Dashboard: Kundenportale (/dashboard/client-portals). Siehe Kundenportale.

In der API: /v1/client-portals für die Administrationsoberfläche.

Web-Widgets#

Das Web-Widget ermöglicht Ihren Website-Besuchern ein mikrofonbasiertes Gespräch mit einem Agenten — keine Telefonnummer erforderlich. Es authentifiziert sich mit einem veröffentlichbaren Schlüssel (pk_live_...), den Browser nur von Ihren zugelassenen Domains verwenden können, sodass er in clientseitigem Code sicher ist. Die Domainliste ist keine Authentifizierung, und die Sitzungseinstellungen, die eine Seite senden darf, sind deaktiviert, bis Sie sie für den Schlüssel zulassen.

Schlüssel werden in einem von zwei Modi ausgeführt: agent (statisch an einen Agenten gebunden) oder webhook (Ihr Server wählt die Konfiguration pro Besucher aus — siehe Dynamische Konfiguration pro Anruf). 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 erlaubte Domains und kopieren Sie das Einbettungs-Snippet. Siehe Web-Widget erstellen.

In der API: /v1/publishable-key, /v1/mic-session und die Widget-SDK-Dokumentation.

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 hoch, fügen Sie Text ein oder importieren Sie Webseiten per URL und verknüpfen Sie die Wissensdatenbank anschließend im Builder mit einem Agenten. Der Agent fragt sie bei Bedarf über ein integriertes Suchwerkzeug ab.

Im Dashboard: Wissen (/dashboard/knowledge) für die Dokumentbibliothek; der Bereich Wissen im Builder zum Verknüpfen mit einem Agenten. Siehe Agenten eine Wissensdatenbank geben.

Verbindungen#

Über Verbindungen erreichen Agenten die Außenwelt. Vier Arten, eine Gruppe in der Seitenleiste:

• Apps (/dashboard/app-connections) — OAuth-Verbindungen zu Slack, HubSpot, Salesforce, Google Calendar, Google Sheets und Cal.com. Verbinden Sie sie einmal und aktivieren Sie anschließend die Werkzeuge für einzelne Vorgänge (eine Slack-Nachricht senden, einen HubSpot-Kontakt aktualisieren oder erstellen, einen Cal.com-Termin buchen …) für jeden Agenten. Siehe Apps verbinden.
• APIs (/dashboard/api-connections) — verwandeln Sie jede HTTP-API in eine Agentenaktion. Fügen Sie einen cURL-Befehl ein, und der KI-Assistent erstellt einen Entwurf der Werkzeugdefinition, oder erstellen Sie sie manuell; die Schaltfläche Anfrage testen führt vor der Veröffentlichung einen Sandbox-Aufruf aus. Siehe API-Verbindungen — die Dashboard-Oberfläche von /v1/integrations.
• MCP (/dashboard/mcp-connections) — fügen Sie einen Model-Context- Protocol-Server per URL hinzu und lassen Sie den Agenten die bereitgestellten Werkzeuge verwenden. Siehe MCP-Server hinzufügen.
• VoIP (/dashboard/voip-connections) — Anbieterzugangsdaten für das Einbinden eigener Telefonnummern. Siehe VoIP-Anbieter verbinden.

ThunderPhone stellt zudem einen eigenen MCP-Endpunkt bereit, sodass ein externer MCP-Client Agenten auflisten, Anrufe und Transkripte prüfen sowie Anrufe tätigen kann. Siehe ThunderPhone als MCP-Server verwenden.

In der API: /v1/integrations, /v1/mcp-servers und /v1/voip-connections; siehe auch Tool-Integration erstellen.

Kampagnen#

Eine Kampagne tätigt ausgehende Anrufe in großem Umfang: Laden Sie eine CSV-Datei mit Kontakten hoch, wählen Sie den Agenten und die Absendernummer aus und legen Sie Anruffenster (Tage und Stunden unter Berücksichtigung der Zeitzone), Parallelität und Wiederholungsrichtlinie (maximale Anzahl von Versuchen und die Ergebnisse — nicht angenommen, Voicemail, fehlgeschlagen —, die wiederholt werden sollen) fest. Die Kampagne arbeitet die Liste ab und zeichnet jeden Anruf im Anrufverlauf auf.

Im Dashboard: Kampagnen (/dashboard/campaigns). Siehe Kampagne für ausgehende Anrufe durchführen.

Für einzelne programmgesteuerte Anrufe: die API für ausgehende Anrufe.

Live-Überwachung#

Live zeigt jeden laufenden Anruf in der gesamten Organisation und ermöglicht es Ihnen, jeden davon zu öffnen, um in Echtzeit zuzuhören und einzuflüstern. Dies ist die Überwachungsansicht: Beobachten Sie, wie ein neuer Prompt seine ersten echten Anrufe verarbeitet, oder behalten Sie eine laufende Kampagne im Blick.

Im Dashboard: Live (/dashboard/live). Siehe Live-Anrufe beobachten und überwachen.

Simulationen#

Eine Simulation ist ein KI-Anrufer, der ein echtes Gespräch mit Ihrem Sprachagenten führt — mit demselben Telefoniepfad, echtem Transkript und echter Bewertung —, damit Sie vor (und nach) der Veröffentlichung testen können. Richten Sie sie auf einen Sprachagenten oder eine Telefonnummer aus, schreiben Sie das Anruferszenario selbst oder generieren Sie Szenarien mit KI aus dem Prompt des Sprachagenten (einschließlich Sonderfällen, wenn Sie danach fragen), und beobachten Sie den Anruf live.

Szenarien werden in Suiten zusammengefasst, die eine Mindestbestehensquote festlegen und Veröffentlichungen in CI steuern können; Regressionen gegenüber der akzeptierten Referenzbasis werden pro Szenario gemeldet.

Im Dashboard: Simulationen (/dashboard/simulations) sowie die Schaltfläche Simulation im Sprachagenten-Builder. Siehe Einen Anruf simulieren.

In der API: /v1/test-calls und der Suite-Runner — siehe Einen Sprachagenten Ende-zu-Ende testen.

Validierungssets#

Ein Validierungsset macht aus Momenten realer Anrufe wiederholbare Regressionstests für einzelne Gesprächszüge. Jedes Beispiel hält den Gesprächskontext, relevante Anruferaudio, die ursprüngliche Antwort und das erwartete Verhalten fest. Wiederholungen werden gegen den aktuellen Entwurf des Sprachagenten ausgeführt, ohne einen weiteren Anruf zu tätigen, und der Bereitstellungsdialog kann anzeigen, ob der letzte Durchlauf weiterhin mit diesem Entwurf übereinstimmt.

Im Dashboard: Validierungssets (/dashboard/validation) für den Organisationsdatensatz sowie der Tab Validierung im Sprachagenten-Builder für Durchläufe. Siehe Validierungssets.

In der API: /v1/validation-sets sowie die Endpunkte für Sprachagenten- und Beispielwiederholungen auf derselben Referenzseite.

Experimente#

Ein Experiment führt A/B-Tests von Sprachagenten-Konfigurationen mit echtem 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 selbst in einem Webhook zu implementieren.

Im Dashboard: Experimente (/dashboard/experiments) und der Tab A/B im Sprachagenten-Builder. Siehe Experimente (A/B-Tests).

Probleme#

Ein Problem ist ein markiertes Problem bei einem bestimmten Anruf — eingereicht 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, untersuchen Sie den betroffenen Anruf und verfolgen Sie Korrekturen.

Im Dashboard: Probleme (/dashboard/issues) sowie die Markierung pro Anruf im Anrufverlauf. Siehe Problem-Triage.

In der API: /v1/issue-reports.

Berichte#

Ein Bericht beantwortet eine Frage in natürlicher Sprache zu Ihren Anrufdaten („Aus welchen drei häufigsten Gründen fragten Anrufer letzte Woche nach einem menschlichen Ansprechpartner?“) mit einer KI-erstellten Analyse, begrenzt auf die von Ihnen ausgewählten Sprachagenten und den gewählten Datumsbereich.

Im Dashboard: Berichte (/dashboard/reports). Siehe Berichte.

Beobachtbarkeit#

Beobachtbarkeit ist der Bereich für Metriken: Anrufvolumen, Ergebnisse und Qualität im Zeitverlauf, filterbar nach Sprachagent und Zeitfenster, mit Export für nachgelagerte Analysen.

Im Dashboard: Beobachtbarkeit (/dashboard/observability). Siehe Beobachtbarkeit.

Warnungen#

Eine Warnregel überwacht eine Metrik (Erfolgsquote, Fehlerquote, Durchschnittsbewertung, 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 alert.triggered-Ereignis an Ihre Webhook-Endpunkte aus.

Im Dashboard: Organisation → Warnungen. Siehe Warnungen.

Webhooks#

ThunderPhone sendet HTTP-POST-Webhooks an Ihren Server, wenn während und nach einem Anruf Ereignisse auftreten. Zwei Zustellmodelle:

• Webhook-Endpunkte (empfohlen): Verwalten Sie mehrere URLs unter /v1/developer/webhook-endpoints mit Secrets und Ereignisabonnements pro Endpunkt.
• Legacy-Webhooks mit einzelner URL: eine URL pro Organisation. Verwaltet unter /v1/webhook oder unter Organisation → Allgemein. Aus Gründen der Abwärtskompatibilität beibehalten.

Ereignisse sind in zwei Klassen unterteilt:

• Blockierende Ereignisse erwarten, dass Ihr Server mit einer Konfiguration antwortet, die den laufenden Anruf gestaltet — die Ereignisse für eingehende Anrufe (telephony.incoming / web.incoming). Ein Telefonanruf wartet bis zu 13 Sekunden, einschließlich eines Wiederholungsversuchs, und eine Widget-Sitzung 10 Sekunden. Es gibt keinen Ersatzagenten: Ohne eine verwendbare Konfiguration wird der Telefonanruf beendet und die Widget-Sitzung schlägt fehl.
• Nicht blockierende Ereignisse sind Fire-and-Forget-Benachrichtigungen, die mit exponentiellem Backoff wiederholt werden — siehe Zustellungssemantik.

Jede Anfrage enthält eine mit Zeitstempel versehene HMAC-SHA256-Signatur in X-ThunderPhone-Signature-V2 sowie die veraltete, ausschließlich den Body betreffende X-ThunderPhone-Signature. Siehe Signaturüberprüfung.

Funktionstools#

Ein Funktionstool ist ein HTTP-Endpunkt, den Ihr Agent während eines Gesprächs aufrufen kann. Sie geben ThunderPhone ein Funktionsschema im OpenAI-Stil sowie eine Endpunkt-URL; der Agent entscheidet, wann er sie aufruft, und ThunderPhone führt die signierte HTTP-Anfrage von seinen Servern aus 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).

In der API: /v1/integrations und die Spezifikation für Funktionstools.

Team und Rollen#

Jede Organisation verfügt über 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; über das Menü ⋯ in einer Mitgliederzeile können Rollen geändert oder Personen entfernt werden. Single Sign-on kann organisationsweit konfiguriert werden — siehe SSO.

Im Dashboard: Organisation → Allgemein. Siehe Ihr Team einladen.

In der API: /v1/members, /v1/invites.

Abrechnung#

ThunderPhone ist vorausbezahlt. Jede Organisation verfügt über ein USD-Guthaben; Anrufe werden zum Minutenpreis des Agenten abgebucht (Engine-Tarif plus Zuschläge — der Builder zeigt den Gesamtpreis beim Ändern der Einstellungen live an, und ausgewählte zusätzliche Sprachen kosten 3 ¢/Min.). Wenn das Guthaben null erreicht, werden eingehende Anrufe abgelehnt 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 sowie die vollständige Preisreferenz.

In der API: /v1/billing.

Der Copilot in der App#

Das Dashboard enthält einen integrierten Copiloten — fragen Sie ihn „wie mache ich X“, und er antwortet anhand dieser Dokumentation, bietet Schritt-für-Schritt-Anleitungen, die die tatsächlichen Bedienelemente hervorheben, und kann jede der geführten Touren wiedergeben. Dies ist der schnellste Weg, ein auf dieser Seite erwähntes Bedienelement zu finden. Siehe Den Copiloten in der App fragen.

Alles zusammenführen#