Getting Started

Kernconcepten

Een overzicht van alles op het platform — wat elk object doet, waar het zich in het dashboard bevindt en welke API ermee werkt.

ThunderPhone is een volledig platform voor het bouwen, uitvoeren en verbeteren van AI-spraakagenten. Deze pagina is de kaart: elk concept dat je tegenkomt, één korte sectie per concept, met het dashboardonderdeel en de API erachter. Lees hem één keer vluchtig door en kom terug wanneer een term uitleg nodig heeft.

De zijbalk van het dashboard weerspiegelt deze structuur:

Organisaties#

Een organisatie is de eenheid voor tenantbeheer. Elke andere resource — agenten, telefoonnummers, oproepen, sleutels — behoort tot precies één organisatie. Je account kan bij meerdere organisaties horen; elke organisatie heeft een eigen saldo, eigen sleutels en eigen ledenlijst.

De sk_live_-API-sleutel die je maakt onder Organisatie → Sleutels is gekoppeld aan één organisatie. Die koppeling maakt de REST API zo plat: je plaatst nooit een organisatie-ID in URL-paden, omdat je sleutel deze al identificeert.

In het dashboard: de organisatiewisselaar (onderaan de zijbalk) en instellingen voor Organisatie — tabbladen voor Mijn account, Algemeen, Sleutels, Meldingen, Factureringsinstellingen en Factureringsgeschiedenis. Zie de referentie voor organisatie-instellingen.

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

Agenten#

Een agent is de AI-configuratie die een oproep uitvoert. Deze bundelt:

• Een prompt die bepaalt wat de agent zegt en hoe deze zich gedraagt — inclusief gespreksacties zoals doorschakelingen, toetsaanslagen en ophangen, die gewone promptregels zijn in plaats van afzonderlijke configuratie.
• Een enginepakket (spark, bolt, storm-*): Spark is geoptimaliseerd voor kosten, Bolt voor snelheid en Storm voor intelligentie bij complexe prompts.
• Een stem plus een primaire taal en optionele aanvullende talen — de agent schakelt automatisch wanneer een beller van taal wisselt. Zie Ondersteunde talen.
• Gekoppelde mogelijkheden: verbonden apps, API-koppelingen, kennisbanken, MCP-servers en inline functietools.
• Gedragsinstellingen: spreekvolgorde, bevestigingsmodus, achtergrondtrack, wachttijdlimiet.

Wijzigingen in de builder worden automatisch opgeslagen als concept; niets wordt actief totdat je op Implementeren klikt. Elke implementatie wordt vastgelegd in het tabblad Geschiedenis van de builder, zodat je elke vorige versie kunt bekijken en herstellen.

In het dashboard: Spraakagenten → de agentbuilder (/dashboard/agents). Zie Bouw je eerste spraakagent.

In de API: /v1/agents — CRUD, dupliceren, doorschakelen, versiegeschiedenis en prompthulpmiddelen.

Stemmen#

De stemmenbibliotheek bevat de stemmen die een agent kan gebruiken, afspeelbare voorbeelden, compatibele talen, groeperingen op geslacht en accent, en eventuele toeslagen voor premium stemmen of talen. Met een betaalde voorbeeldfunctie kun je je eigen zin van 1–500 tekens laten synthetiseren voordat je kiest.

In aanmerking komende organisaties kunnen ook aangepaste stemmen maken op basis van een kort WAV- of MP3-voorbeeld. Aangepaste stemmen hebben een quotum en een asynchrone aanmaakstatus; zodra ze klaar zijn, verschijnen ze in dezelfde agentkiezer als stemmen uit de bibliotheek.

In het dashboard: Stemmen (/dashboard/voices). Zie Stemmenbibliotheek en aangepaste stemmen.

In de API: /v1/voices, stemvoorbeelden en aangepaste stemmen.

Telefoonnummers#

Een telefoonnummer hoort bij een organisatie en routeert inkomende oproepen naar een agent (en kan uitgaande oproepen verwerken). Twee bronnen:

• Demonummers — echte Amerikaanse nummers uit de pool van ThunderPhone, binnen enkele seconden actief. Alleen voor inkomende oproepen; ze nemen op met een korte gesproken disclaimer en het dashboard beperkt een organisatie tot 10 van deze nummers. Ideaal voor een eerste test, niet voor productie.
• VoIP-nummers — meegebracht van je eigen provider via een VoIP-verbinding. Twilio en Telnyx verbinden rechtstreeks (Telnyx heeft een begeleide configuratie); SignalWire en Vonage komen binnenkort — momenteel bereik je ze via handmatige SIP-configuratie, die elke SIP-trunk accepteert. Zodra VoIP-nummers zijn geïmporteerd en geverifieerd, ondersteunen ze inkomende en uitgaande oproepen.

In elke nummerregel kun je een routeringsmodus instellen, de agent voor inkomende oproepen kiezen en het nummer een label geven.

In het dashboard: Telefoonnummers (/dashboard/phone-numbers). Zie Een telefoonnummer verkrijgen.

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

Oproepen#

Elke inkomende oproep, uitgaande oproep, simulatie en widgetsessie wordt een oproepregistratie. Een oproep bevat het volledige transcript met roltags, de gestructureerde beurtgeschiedenis (inclusief toolaanroepen), een opname, het factuurtotaal en optionele AI-beoordelingen en probleemrapporten.

Terwijl een oproep live is, kun je deze openen en meeluisteren — je neemt stil deel en niemand in de oproep hoort je. Zodra je meeluistert, kun je influisteren: typ een instructie die tijdens de oproep rechtstreeks naar je agent gaat; de beller hoort deze nooit en de agent volgt hem direct op.

In het dashboard: Oproepgeschiedenis (/dashboard/call-history) voor het archief en details per oproep; Live voor lopende oproepen. Zie Je oproepen beoordelen, meeluisteren en begeleiden.

In de API: /v1/calls — lijst, transcript, geschiedenis, audio, beoordeling, export; /v1/issue-reports.

Klantportalen#

Een klantportaal is een aangepaste, alleen-lezenweergave van de oproepgeschiedenis voor een externe klant. Organisatiebeheerders kiezen de agenten waarvan de oproepen worden weergegeven, voegen goedgekeurde kijker-e-mailadressen toe, uploaden een logo en accentkleur en verifiëren optioneel een aangepast domein. Portalgebruikers kunnen oproepdetails, transcripten en beschikbare opnamen bekijken zonder toegang tot het dashboard te krijgen.

In het dashboard: Klantportalen (/dashboard/client-portals). Zie Klantportalen.

In de API: /v1/client-portals voor het beheeroppervlak voor beheerders.

Webwidgets#

Met de webwidget kunnen bezoekers van je site via een microfoon met een agent praten — geen telefoonnummer nodig. De widget verifieert met een publiceerbare sleutel (pk_live_...) die aan de oorsprong van je toegestane domeinen is gekoppeld, zodat deze veilig is in client-side code.

Sleutels werken in een van twee modi: agent (statisch gekoppeld aan één agent) of webhook (je server kiest de configuratie per bezoeker — zie Dynamische configuratie per oproep). Widgetsessies verlopen via dezelfde oproepinfrastructuur als telefoongesprekken.

In het dashboard: Webwidgets (/dashboard/web-widgets) — maak widgets, stel de modus en agent in, beheer toegestane domeinen en kopieer het embedfragment. Zie Een webwidget maken.

In de API: /v1/publishable-key, /v1/mic-session en de Widget SDK-documentatie.

Kennisbanken#

Een kennisbank is een verzameling documenten die je agent tijdens een gesprek kan doorzoeken om antwoorden te onderbouwen — upload bestanden, plak tekst of importeer webpagina's via URL en koppel de kennisbank vervolgens in de builder aan een agent. De agent doorzoekt deze met een ingebouwde zoektool wanneer het gesprek daarom vraagt.

In het dashboard: Kennis (/dashboard/knowledge) voor de documentbibliotheek; de sectie Kennis van de builder om er een aan een agent te koppelen. Zie Je agent een kennisbank geven.

Verbindingen#

Via verbindingen bereiken agents de buitenwereld. Vier soorten, één zijbalkgroep:

• Apps (/dashboard/app-connections) — OAuth-verbindingen met Slack, HubSpot, Salesforce, Google Calendar, Google Sheets en Cal.com. Maak één keer verbinding en schakel vervolgens tools per bewerking in voor elke agent (een Slack-bericht plaatsen, een HubSpot-contact bijwerken of toevoegen, een Cal.com-tijdslot boeken…). Zie Apps verbinden.
• API's (/dashboard/api-connections) — zet elke HTTP-API om in een agentactie. Plak een cURL-opdracht en de AI-wizard maakt een concept voor de tooldefinitie, of bouw deze handmatig; met de knop Testverzoek voer je een sandboxoproep uit voordat je deze uitbrengt. Zie API-verbindingen — de dashboardweergave van /v1/integrations.
• MCP (/dashboard/mcp-connections) — voeg een Model Context Protocol-server toe via URL en laat de agent de tools gebruiken die deze beschikbaar stelt. Zie Een MCP-server toevoegen.
• VoIP (/dashboard/voip-connections) — providerreferenties voor je eigen telefoonnummers gebruiken. Zie Een VoIP-provider verbinden.

ThunderPhone biedt ook een eigen MCP-eindpunt, zodat een externe MCP-client agents kan weergeven, oproepen en transcripties kan inspecteren en oproepen kan plaatsen. Zie ThunderPhone als MCP-server gebruiken.

In de API: /v1/integrations, /v1/mcp-servers en /v1/voip-connections; zie ook Een toolintegratie bouwen.

Campagnes#

Met een campagne plaats je op grote schaal uitgaande oproepen: upload een CSV met contacten, kies de agent en het uitgaande nummer, en stel het belvenster in (dagen en uren, rekening houdend met tijdzones), evenals gelijktijdigheid en het beleid voor opnieuw proberen (maximaal aantal pogingen en welke uitkomsten — geen antwoord, voicemail, mislukt — opnieuw worden geprobeerd). De campagne werkt de lijst af en registreert elke oproep in Oproepgeschiedenis.

In het dashboard: Campagnes (/dashboard/campaigns). Zie Een campagne voor uitgaande oproepen uitvoeren.

Voor eenmalige programmatische oproepen: de API voor uitgaande oproepen.

Live monitoring#

Live toont elk gesprek dat binnen de organisatie in uitvoering is en laat je elk gesprek openen om mee te luisteren en in te fluisteren in realtime. Het is het toezichtsoverzicht: volg hoe een nieuwe prompt zijn eerste echte verkeer verwerkt, of houd een lopende campagne in de gaten.

In het dashboard: Live (/dashboard/live). Zie Live gesprekken bekijken en begeleiden.

Simulaties#

Een simulatie is een AI-beller die een echt gesprek voert met je agent — hetzelfde telefoniepad, echt transcript, echte beoordeling — zodat je kunt testen voordat (en nadat) je uitrolt. Richt deze op een agent of een telefoonnummer, schrijf het bellerscenario zelf of genereer scenario's met AI op basis van de prompt van de agent (inclusief randgevallen, als je daarom vraagt), en bekijk het gesprek live.

Scenario's worden gegroepeerd in suites die een minimaal slagingspercentage vastleggen en releases in CI kunnen blokkeren; regressies ten opzichte van de geaccepteerde basislijn worden per scenario gerapporteerd.

In het dashboard: Simulaties (/dashboard/simulations), plus de knop Simulatie in de agentbuilder. Zie Een gesprek simuleren.

In de API: /v1/test-calls en de suiterunner — zie Een agent end-to-end testen.

Validatiesets#

Een validatieset zet echte momenten uit gesprekken om in herhaalbare regressiecontroles met één beurt. Elk voorbeeld legt de gesprekscontext, relevante audio van de beller, het oorspronkelijke antwoord en het verwachte gedrag vast. Herhalingen worden uitgevoerd tegen het huidige agentconcept zonder nog een gesprek te plaatsen, en het implementatievenster kan tonen of de meest recente uitvoering nog steeds met dat concept overeenkomt.

In het dashboard: Validatiesets (/dashboard/validation) voor de organisatiegegevensset en het tabblad Validatie van de agentbuilder voor uitvoeringen. Zie Validatiesets.

In de API: /v1/validation-sets en de replay-eindpunten voor agenten en voorbeelden op dezelfde referentiepagina.

Experimenten#

Een experiment voert A/B-tests uit op agentconfiguraties met live verkeer: definieer varianten (verschillende prompts, engines of instellingen), verdeel het verkeer ertussen en vergelijk de resultaten per variant. Gebruik dit in plaats van zelf bucketlogica in een webhook te bouwen.

In het dashboard: Experimenten (/dashboard/experiments) en het tabblad A/B in de agentbuilder. Zie Experimenten (A/B-testen).

Problemen#

Een probleem is een gemarkeerd probleem bij een specifiek gesprek — gemeld door een menselijke beoordelaar of gedetecteerd door AI-beoordeling. Problemen bevatten ernst, bron en status, en de pagina Problemen is de triagewachtrij: filter, inspecteer het betreffende gesprek en volg oplossingen.

In het dashboard: Problemen (/dashboard/issues), plus markeringen per gesprek in Oproepgeschiedenis. Zie Problementriage.

In de API: /v1/issue-reports.

Rapporten#

Een rapport beantwoordt een vraag in natuurlijke taal over je gespreksgegevens ("Wat waren vorige week de drie belangrijkste redenen waarom bellers om een medewerker vroegen?") met een door AI geschreven analyse, afgestemd op de agenten en het datumbereik die je kiest.

In het dashboard: Rapporten (/dashboard/reports). Zie Rapporten.

Observeerbaarheid#

Observeerbaarheid is het metriekoverzicht: gespreksvolume, resultaten en kwaliteit in de tijd, filterbaar op agent en tijdsvenster, met export voor vervolgonderzoek.

In het dashboard: Observeerbaarheid (/dashboard/observability). Zie Observeerbaarheid.

Waarschuwingen#

Een waarschuwingsregel bewaakt een metriek (succespercentage, foutpercentage, gemiddelde score, gespreksvolume, regressies in suites) binnen een tijdsvenster en wordt geactiveerd wanneer deze je drempelwaarde overschrijdt. Meldingen gaan naar e-mail en Slack en activeren een alert.triggered-event voor je webhook-eindpunten.

In het dashboard: Organisatie → Waarschuwingen. Zie Waarschuwingen.

Webhooks#

ThunderPhone stuurt HTTP POST-webhooks naar je server wanneer er tijdens en na een oproep gebeurtenissen plaatsvinden. Twee bezorgmodellen:

• Webhook-eindpunten (aanbevolen): beheer meerdere URL's via /v1/developer/webhook-endpoints met geheimen per eindpunt en gebeurtenisabonnementen per eindpunt.
• Verouderde webhook met één URL: één URL per organisatie. Beheerd via /v1/webhook of onder Organisatie → Algemeen. Behouden voor achterwaartse compatibiliteit.

Gebeurtenissen zijn verdeeld in twee klassen:

• Blokkerende gebeurtenissen verwachten dat je server reageert met configuratie die de actieve oproep vormgeeft — de gebeurtenissen voor inkomende oproepen (telephony.incoming / web.incoming). Je hebt maximaal 10 seconden om te reageren; bij een time-out handelt de statisch toegewezen agent de oproep af.
• Niet-blokkerende gebeurtenissen zijn fire-and-forgetmeldingen, opnieuw geprobeerd met exponentiële backoff — zie bezorgsemantiek.

Elk verzoek bevat een HMAC-SHA256-handtekening in X-ThunderPhone-Signature. Zie Handtekeningverificatie.

Functietools#

Een functietool is een HTTP-eindpunt dat je agent tijdens een gesprek kan aanroepen. Je geeft ThunderPhone een functieschema in OpenAI-stijl plus een eindpunt-URL; de agent bepaalt wanneer deze wordt aangeroepen, en ThunderPhone doet het ondertekende HTTP-verzoek vanaf zijn servers en geeft het resultaat terug aan de agent.

Agents beschikken ook over ingebouwde oproepmogelijkheden — de oproep doorverbinden, invoer via het toetsenblok (DTMF) versturen, de oproep beëindigen, in de wacht staan — die je inschakelt met eenvoudige promptregels in plaats van tooldefinities.

In het dashboard: het gedeelte API-verbindingen van de builder (zie Verbindingen).

In de API: /v1/integrations en de specificatie voor Function Tools.

Team en rollen#

Elke organisatie heeft een ledenlijst met twee rollen: Leden bouwen en beheren agents; Beheerders beheren daarnaast het team en de facturering. Nodig uit via e-mail — uitnodigingen verlopen na 7 dagen en kunnen worden ingetrokken; via het menu ⋯ op een ledenrij kun je rollen wijzigen of iemand verwijderen. Eenmalig inloggen kan organisatiebreed worden geconfigureerd — zie SSO.

In het dashboard: Organisatie → Algemeen. Zie Nodig je team uit.

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

Facturering#

ThunderPhone is prepaid. Elke organisatie heeft een saldo in USD; oproepen worden hiervan afgeschreven tegen het tarief per minuut van de agent (enginepakket plus toeslagen — de builder toont het totale tarief live terwijl je instellingen wijzigt, en geselecteerde aanvullende talen voegen 3¢/min toe). Wanneer het saldo nul bereikt, worden inkomende oproepen geweigerd en geven uitgaande oproepen 402 Payment Required terug.

Waardeer handmatig op, of schakel automatisch opwaarderen in met een saldodrempel, een opwaardeerbedrag en een optionele maandelijkse bestedingslimiet — zodat een oproep nooit midden in een zin wordt afgebroken.

In het dashboard: Organisatie → Factureringsinstellingen en Factureringsgeschiedenis. Zie Saldo toevoegen en automatisch opwaarderen inschakelen, plus de volledige prijsreferentie.

In de API: /v1/billing.

De Copilot in de app#

Het dashboard bevat een ingebouwde Copilot — vraag "hoe doe ik X" en deze antwoordt op basis van deze documentatie, biedt stapsgewijze rondleidingen die de daadwerkelijke bedieningselementen uitlichten, en kan alle begeleide rondleidingen opnieuw afspelen. Dit is de snelste manier om een bedieningselement te vinden dat op deze pagina wordt genoemd. Zie Vraag de Copilot in de app.

Alles samenbrengen#