ThunderPhone 2.0 is live.Direct zelf aan de slag, vanaf 2¢/min.Lees de aankondiging
Aan de slag

Getting Started

View as Markdown
Open in
ClaudeChatGPTCursor

Snelstartgids (API)

Beantwoord je eerste telefoongesprek met een AI-agent: verkrijg een API-sleutel, maak een agent, richt een telefoonnummer in en voer een live testgesprek — allemaal via de REST API.

Deze handleiding leidt je door de vier REST-aanroepen die nodig zijn om je eerste telefoongesprek met een AI-agent te beantwoorden.

Stap 1: Een API-sleutel ophalen

  1. Inloggen
  2. Naar Sleutels gaan

    Ga in het dashboard naar Organisatie → Sleutels.

  3. Een sleutel maken

    Klik op Sleutel maken, geef de sleutel een naam en kopieer de waarde sk_live_.... De onbewerkte sleutel wordt slechts één keer weergegeven — sla deze direct op in je secretmanager.

Vervang in deze handleiding sk_live_YOUR_API_KEY door de waarde die je zojuist hebt gekopieerd. De sleutel identificeert je organisatie automatisch, dus je hoeft nooit een organisatie-id in URL's op te nemen.

Stap 2: Een agent maken

Een agent bepaalt hoe de AI gesprekken afhandelt — prompt, stem, productpakket, tools en geschiktheid voor widgets.

cURL
curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":   "Customer Support",
    "prompt": "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
    "voice":  "john",
    "product": "spark"
  }'
Python
import os, requests
 
agent = requests.post(
    "https://api.thunderphone.com/v1/agents",
    headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
    json={
        "name":   "Customer Support",
        "prompt": "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
        "voice":  "john",
        "product": "spark",
    },
).json()
print("Agent id:", agent["id"])
Node.js
const agent = await fetch("https://api.thunderphone.com/v1/agents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.THUNDERPHONE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name:    "Customer Support",
    prompt:  "You are a friendly support agent for Acme Corp. Help with orders, returns, and product info. Be concise and helpful.",
    voice:   "john",
    product: "spark",
  }),
}).then((r) => r.json());
console.log("Agent id:", agent.id);

Stap 3: Een telefoonnummer inrichten

Met deze aanroep vraag je ThunderPhone om een nummer en wijs je je nieuwe agent toe als afhandelaar voor inkomende oproepen. (Zie VoIP-verbindingen als je je eigen nummer van een VoIP-provider wilt gebruiken.)

cURL
# First provision
curl -X POST https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415"}'
 
# Then assign the agent you created in Step 2
curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/<id-from-previous> \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'
Python
number = requests.post(
    "https://api.thunderphone.com/v1/phone-numbers",
    headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
    json={"area_code": "415"},
).json()
requests.patch(
    f"https://api.thunderphone.com/v1/phone-numbers/{number['id']}",
    headers={"Authorization": f"Bearer {os.environ['THUNDERPHONE_API_KEY']}"},
    json={"inbound_agent_id": agent["id"]},
)
print("Your ThunderPhone number:", number["number"])

Je nieuwe nummer begint met status="provisioning" en gaat binnen enkele seconden over naar active; tegen de tijd dat je je browser afsluit, is het nummer klaar om oproepen aan te nemen.

Stap 4 (optioneel): Een webhook instellen

Voeg een webhook-eindpunt toe voor realtime gebeurtenissen (dynamische oproeproutering, verwerking na een oproep). Abonneer je alleen op de gebeurtenissen die je nodig hebt.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Prod webhook",
    "url":    "https://your-server.com/thunderphone-webhook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'

Het antwoord bevat een eenmalig secret — kopieer dit naar je secretmanager. Gebruik dat secret om de header X-ThunderPhone-Signature-V2 bij binnenkomende verzoeken te verifiëren (zie Overzicht van webhooks).

Stap 5: Test je agent

Bel het nummer dat je zojuist hebt ingericht. De agent neemt op, stelt zich voor en volgt je prompt.

Controleer de oproep nadat deze is beëindigd:

curl https://api.thunderphone.com/v1/calls \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Bekijk een specifieke oproep om de transcriptie en opname-URL op te halen:

curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Volgende stappen

Functietools toevoegen

Laat je agent tijdens een gesprek je API's aanroepen.

Uitgaande oproepen plaatsen

Start oproepen vanuit je eigen code.

Webhooks afhandelen

Reageer realtime op oproepgebeurtenissen.

Volledige API-referentie

Elk openbaar eindpunt, gedocumenteerd.