Getting Started

Grundlegende Konzepte

Eine Übersicht über alles auf der Plattform – welche Aufgabe jedes Objekt hat, 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, das Ihnen begegnet, in einem kurzen Abschnitt, mit der entsprechenden Dashboard-Oberfläche und der zugrunde liegenden API. Überfliegen Sie sie einmal und kehren Sie dann zurück, wenn ein Begriff erklärt 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 mehreren 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 schlank: Sie geben nie eine Organisations-ID in URL-Pfaden an, weil Ihr Schlüssel sie bereits identifiziert.

Im Dashboard: der Organisationswechsler (Fußzeile der Seitenleiste) und die Einstellungen unter Organisation — Registerkarten für Mein Konto, Allgemein, Schlüssel, Benachrichtigungen, 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. Sie umfasst:

• Einen Prompt, der bestimmt, was der Agent sagt und wie er sich verhält — einschließlich Anrufaktionen wie Weiterleitungen, Tastenbetätigungen 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.
• Angebundene Funktionen: verbundene Apps, API-Verbindungen, Wissensdatenbanken, MCP-Server und Inline- Funktions-Tools.
• Verhaltensoptionen: Sprechreihenfolge, Bestätigungsmodus, Hintergrundspur, Warteschleifen-Timeout.

Änderungen im Builder werden automatisch als Entwurf gespeichert; nichts wird veröffentlicht, bis Sie auf Bereitstellen klicken. Jede Bereitstellung wird im Tab Verlauf des Builders als Snapshot gespeichert, sodass Sie jede vorherige 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, Geschlechts- und Akzentgruppen sowie mögliche Aufpreise für Premium-Stimmen oder -Sprachen. Mit einem kostenpflichtigen Sampler können Sie vor der Auswahl Ihre eigene Phrase mit 1–500 Zeichen synthetisieren.

Berechtigte Organisationen können auch eigene Stimmen aus einem kurzen WAV- oder MP3-Beispiel erstellen. Eigene 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 eigene Stimmen.

In der API: /v1/voices, Stimmenbeispiele und eigene 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). Zwei Quellen:

• Demo-Nummern — echte US-Telefonnummern aus dem Pool von ThunderPhone, die innerhalb von Sekunden bereitgestellt werden. Sie unterstützen nur eingehende Anrufe, melden sich mit einer kurzen gesprochenen Ansage, und das Dashboard begrenzt eine Organisation auf 10 davon. Ideal für einen ersten Test, aber nicht für den Produktivbetrieb.
• VoIP-Nummern — werden über eine VoIP-Verbindung von Ihrem eigenen Anbieter eingebracht. Twilio und Telnyx lassen sich direkt verbinden (Telnyx bietet eine geführte Einrichtung); SignalWire und Vonage folgen in Kürze — 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.

In der API: /v1/phone-numbers, /v1/voip-connections, /v1/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 gekennzeichnete Transkript, den strukturierten Verlauf der Gesprächsrunden (einschließlich Werkzeugaufrufen), eine Aufzeichnung, die Abrechnungssumme sowie optionale KI-Bewertungen und Problemmeldungen.

Während ein Anruf live ist, können Sie ihn öffnen und mithören — Sie schalten sich lautlos zu, und niemand im Anruf hört Sie. Sobald Sie mithören, können Sie zuflüstern: Geben Sie eine Anweisung ein, die während des Anrufs direkt an Ihren Agenten gesendet wird; der Anrufer hört sie nie, und der Agent befolgt sie in Echtzeit.

Im Dashboard: Anrufverlauf (/dashboard/call-history) für das Archiv und Details zu einzelnen Anrufen; Live für laufende Anrufe. Siehe Ihre Anrufe prüfen, mithören und anleiten.

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

Kundenportale#

Ein Kundenportal ist eine markengebundene, schreibgeschützte Ansicht des Anrufverlaufs für einen externen Kunden. Organisationsadministratoren wählen die Agenten aus, deren Anrufe angezeigt werden, fügen E-Mail-Adressen autorisierter Betrachter hinzu, laden ein Logo und eine Akzentfarbe hoch und können optional eine eigene Domain verifizieren. Portalbetrachter können Anrufdetails, Transkripte und verfügbare Aufzeichnungen prüfen, ohne Zugang zum 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 eine mikrofonbasierte Unterhaltung mit einem Agenten — keine Telefonnummer erforderlich. Es authentifiziert sich mit einem veröffentlichbaren Schlüssel (pk_live_...), der an die Herkunft Ihrer zugelassenen Domains gebunden ist und daher sicher in clientseitigem Code verwendet werden kann.

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) — Widgets erstellen, Modus und Agenten festlegen, zugelassene Domains verwalten und das Einbettungs-Snippet kopieren. Siehe Ein 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 dann im Builder mit einem Agenten. Der Agent fragt sie mit einem integrierten Suchtool ab, sobald die Unterhaltung dies erfordert.

Im Dashboard: Wissen (/dashboard/knowledge) für die Dokumentbibliothek; der Bereich Wissen im Builder, um eine Wissensdatenbank mit einem Agenten zu verknüpfen. Siehe Geben Sie Ihrem Agenten eine Wissensdatenbank.

Verbindungen#

Über Verbindungen erreichen Agenten 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.
• APIs (/dashboard/api-connections) — jede HTTP-API in eine Agentenaktion umwandeln. Fügen Sie einen cURL-Befehl ein, und der KI-Assistent erstellt einen Entwurf der Tool-Definition, oder erstellen Sie sie manuell; eine Schaltfläche Testanfrage führt einen Sandbox-Aufruf aus, bevor Sie veröffentlichen. 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 von ihm bereitgestellten Tools verwenden. Siehe Einen MCP-Server hinzufügen.
• VoIP (/dashboard/voip-connections) — Anbieteranmeldedaten für die Verwendung eigener Telefonnummern. Siehe Einen VoIP-Anbieter verbinden.

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

In der API: /v1/integrations, /v1/mcp-servers und /v1/voip-connections; siehe auch Eine 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 das Anruffenster (Tage und Stunden unter Berücksichtigung der Zeitzone), Parallelität und Wiederholungsrichtlinie (maximale Anzahl an Versuchen und welche Ergebnisse — keine Antwort, Mailbox, fehlgeschlagen — erneut versucht werden) fest. 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 durchführen.

Für einmalige programmatische Anrufe: die API für ausgehende Anrufe.

Live-Überwachung#

Live zeigt jeden laufenden Anruf in der gesamten Organisation und ermöglicht Ihnen, jeden davon zu öffnen, um live mitzuhören und einzuflüstern. Es ist die Oberfläche für die Überwachung: Beobachten Sie, wie ein neuer Prompt seinen ersten echten Traffic erhält, 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 Agenten führt — derselbe Telefoniepfad, echtes Transkript, echte Bewertung — damit Sie vor (und nach) der Bereitstellung testen können. Richten Sie sie auf einen Agenten oder eine Telefonnummer, schreiben Sie das Anruferszenario selbst oder generieren Sie Szenarien mit KI aus dem Prompt des Agenten (einschließlich Randfälle, wenn Sie danach fragen), und verfolgen Sie den Anruf live.

Szenarien werden in Suiten gruppiert, die eine Mindest-Bestehensquote festlegen und Releases in CI blockieren können; Regressionen gegenüber der akzeptierten Baseline werden pro Szenario gemeldet.

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

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

Validierungssätze#

Ein Validierungssatz verwandelt reale Gesprächsmomente in wiederholbare Regressionstests für einzelne Gesprächsrunden. Jedes Beispiel speichert den Gesprächskontext, relevante Anrufer-Audiodaten, die ursprüngliche Antwort und das erwartete Verhalten. Wiederholungen werden gegen den aktuellen Agentenentwurf 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: Validierungssätze (/dashboard/validation) für den Organisationsdatensatz und die Registerkarte Validierung im Agent-Builder für Durchläufe. Siehe Validierungssätze.

In der API: /v1/validation-sets und die Replay-Endpunkte für Agenten/Beispiele auf derselben Referenzseite.

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 es, statt Bucket-Logik in einem Webhook manuell zu implementieren.

Im Dashboard: Experimente (/dashboard/experiments) und die Registerkarte A/B im Agent-Builder. Siehe Experimente (A/B-Tests).

Probleme#

Ein Problem ist ein markiertes Problem bei einem bestimmten Anruf — erfasst 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 Korrekturen.

Im Dashboard: Probleme (/dashboard/issues) sowie Markierungen 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 („Was waren letzte Woche die drei häufigsten Gründe, aus denen Anrufer nach einem Menschen fragten?“) mit einer KI-generierten Analyse, die auf die von Ihnen gewählten Agenten und den Datumsbereich beschränkt ist.

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

Beobachtbarkeit#

Beobachtbarkeit 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: Beobachtbarkeit (/dashboard/observability). Siehe Beobachtbarkeit.

Warnungen#

Eine Warnregel überwacht eine Metrik (Erfolgsquote, Fehlerquote, Durchschnittswert, 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 eintreten. Zwei Zustellmodelle:

• Webhook-Endpunkte (empfohlen): Verwalten Sie mehrere URLs unter /v1/developer/webhook-endpoints mit endpunktspezifischen Secrets und endpunktspezifischen Ereignisabonnements.
• 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 werden in zwei Klassen unterteilt:

• Blockierende Ereignisse erwarten, dass Ihr Server mit einer Konfiguration antwortet, die den laufenden Anruf steuert — die Ereignisse für eingehende Anrufe (telephony.incoming / web.incoming). Sie haben bis zu 10 Sekunden Zeit zu antworten; bei einem Timeout bearbeitet der statisch zugewiesene Agent den Anruf.
• Nicht blockierende Ereignisse sind Fire-and-Forget-Benachrichtigungen, die mit exponentiellem Backoff wiederholt werden — siehe Zustellsemantik.

Jede Anfrage enthält eine HMAC-SHA256-Signatur in X-ThunderPhone-Signature. Siehe Signaturüberprüfung.

Funktions-Tools#

Ein Funktions-Tool 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 es aufruft, und ThunderPhone führt die signierte HTTP-Anfrage von seinen Servern aus und gibt das Ergebnis an den Agenten zurück.

Agenten bieten außerdem integrierte Anruffunktionen — den Anruf weiterleiten, Tastatureingaben (DTMF) senden, den Anruf beenden und 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 Funktions-Tools.

Team und Rollen#

Jede Organisation verfügt über eine Mitgliederliste mit zwei Rollen: Mitglieder erstellen und betreiben Agenten; Admins 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 Sie Rollen ändern oder Personen entfernen. 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 belasten es zum Minutenpreis des Agenten (Engine-Tier plus Zuschläge — der Builder zeigt den Gesamtpreis live an, wenn Sie Einstellungen ändern, und ausgewählte zusätzliche Sprachen kosten zusätzlich 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 In-App-Copilot#

Das Dashboard bietet einen integrierten Copilot — fragen Sie ihn „Wie mache ich X?“ und er antwortet auf Basis dieser Dokumentation, bietet Schritt-für-Schritt-Anleitungen, die die tatsächlichen Bedienelemente hervorheben, und kann alle geführten Touren erneut abspielen. Er ist der schnellste Weg, ein auf dieser Seite erwähntes Bedienelement zu finden. Siehe Den In-App-Copilot fragen.

Alles zusammenführen#