ThunderPhone 2.0 ist live.Direkt im Self-Service – ab 2 ¢/Min..Ankündigung lesen
Jetzt starten

Getting Started

View as Markdown
Open in
ClaudeChatGPTCursor

Schnellstart (API)

Beantworten Sie Ihren ersten Anruf mit einem KI-Agenten: API-Schlüssel abrufen, Agenten erstellen, eine Telefonnummer bereitstellen und einen Live-Testanruf durchführen – alles über die REST-API.

Diese Anleitung führt Sie durch die vier REST-Aufrufe, die Sie benötigen, um Ihren ersten Anruf mit einem Sprachagenten zu beantworten.

Schritt 1: API-Schlüssel abrufen

  1. Anmelden
  2. Zu Schlüsseln navigieren

    Gehen Sie im Dashboard zu Organisation → Schlüssel.

  3. Schlüssel erstellen

    Klicken Sie auf Schlüssel erstellen, geben Sie ihm einen Namen und kopieren Sie den Wert sk_live_.... Der vollständige Schlüssel wird nur einmal angezeigt — speichern Sie ihn sofort in Ihrem Secret Manager.

Ersetzen Sie in dieser Anleitung sk_live_YOUR_API_KEY durch den Wert, den Sie gerade kopiert haben. Der Schlüssel identifiziert Ihre Organisation automatisch, sodass Sie niemals eine Organisations-ID in URLs angeben müssen.

Schritt 2: Agenten erstellen

Ein Agent definiert, wie die KI Gespräche führt — Prompt, Stimme, Produktstufe, Tools und Widget-Berechtigung.

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);

Schritt 3: Eine Telefonnummer bereitstellen

Dieser Aufruf fordert bei ThunderPhone eine Nummer an und weist Ihren neuen Agenten als Handler für eingehende Anrufe zu. (Wenn Sie Ihre eigene Nummer von einem VoIP- Anbieter mitbringen möchten, lesen Sie stattdessen VoIP-Verbindungen.)

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"])

Ihre neue Nummer startet mit status="provisioning" und wechselt innerhalb weniger Sekunden zu active; bis Sie Ihren Browser schließen, ist die Nummer bereit, Anrufe entgegenzunehmen.

Schritt 4 (optional): Einen Webhook einrichten

Fügen Sie für Echtzeitereignisse (dynamische Anrufweiterleitung, Verarbeitung nach dem Anruf) einen Webhook-Endpunkt hinzu. Abonnieren Sie nur die Ereignisse, die Sie benötigen.

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"]
  }'

Die Antwort enthält ein einmaliges secret — kopieren Sie es in Ihren Secret-Manager. Verwenden Sie dieses Secret, um den Header X-ThunderPhone-Signature-V2 bei eingehenden Anfragen zu verifizieren (siehe Webhooks-Übersicht).

Schritt 5: Ihren Agenten testen

Rufen Sie die gerade bereitgestellte Nummer an. Der Agent nimmt ab, stellt sich vor und folgt Ihrem Prompt.

Prüfen Sie den Anruf nach seinem Ende:

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

Rufen Sie einen bestimmten Anruf ab, um das Transkript und die Aufnahme-URL zu erhalten:

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"

Nächste Schritte

Funktions-Tools hinzufügen

Lassen Sie Ihren Agenten während eines Gesprächs Ihre APIs aufrufen.

Ausgehende Anrufe tätigen

Lösen Sie Anrufe aus Ihrem eigenen Code aus.

Webhooks verarbeiten

Reagieren Sie in Echtzeit auf Anrufereignisse.

Vollständige API-Referenz

Jeder öffentliche Endpunkt, dokumentiert.