Eingehende Anrufe verarbeiten (API)

End-to-End: Einen Agenten konfigurieren, ihm eine Telefonnummer zuweisen, einen Anruf entgegennehmen und das Transkript prüfen.

Der klassische Ablauf für „ein Telefon mit einer KI beantworten“, direkt in Ihrem Terminal. Sie werden:

1. Einen Agenten mit einem Prompt und einer Stimme erstellen.
2. Eine Telefonnummer bereitstellen (oder mitbringen) und den Agenten als Handler für eingehende Anrufe zuweisen.
3. Die Nummer anrufen. Anrufprotokoll, Transkript und Aufzeichnung prüfen.

API-Aufrufe insgesamt: vier. Gesamtzeit: unter fünf Minuten.

1. Einen Agenten erstellen#

Ein Agent bündelt den Prompt, die Stimme und die Produktstufe, die den Anruf steuern. Sie können für den Agenten auch Anruflimits wie max_call_duration_seconds und ring_duration_seconds festlegen. Agenten unterstützen außerdem intro_clip und intro_ring_count, um eine vorab aufgezeichnete Begrüßung und bis zu zwei Klingeltöne abzuspielen, bevor der Agent spricht. Neue Agenten benötigen außerdem eine Zeitzone. Wenn Ihr Agent mehrsprachig ist, können Sie mit language_switching festlegen, ob er vor dem Sprachwechsel fragt oder der Sprache des Anrufers folgt. Alle Konfigurationsfelder finden Sie unter Agents; das Minimum ist:

curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":    "Acme Support",
    "prompt":  "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
    "voice":   "john",
    "product": "spark"
  }'

Speichern Sie die zurückgegebene id — Sie benötigen sie in Schritt 2.

2. Eine Telefonnummer erhalten#

Wenn Sie lediglich eine Nummer zum Anrufen benötigen, beziehen Sie eine ThunderPhone-Nummer aus dem Pool von ThunderPhone:

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

Die Antwort enthält eine id und eine number im E.164-Format. ThunderPhone- Nummern starten mit status="provisioning" und werden innerhalb weniger Sekunden active — fragen Sie GET /v1/phone-numbers/{id} ab, um den Übergang zu verfolgen, falls Sie ihn beobachten möchten.

3. Den Agenten zuweisen#

Verknüpfen Sie den Agenten aus Schritt 1 mit der Richtung für eingehende Anrufe der Nummer:

curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'

Das war’s — die Nummer ist aktiv. Nachdem ausgehende Anrufe für Ihre Organisation genehmigt wurden, können Sie im selben PATCH auch outbound_agent_id festlegen. Bis dahin lehnt die API diese Zuweisung mit 400 ab.

Wenn Sie eingehende Anrufe über einen Konfigurations-Webhook statt über eine feste inbound_agent_id weiterleiten, kann dieser Webhook nun pro Anruf eine timezone zusammen mit agent_id und variables zurückgeben.

4. Einen Anruf annehmen#

Rufen Sie die Nummer über Ihr Telefon an. Der Agent nimmt ab, stellt sich gemäß Ihrem Prompt vor, und das Gespräch beginnt.

Während der Anruf läuft, wird er in GET /v1/calls mit status="in_progress" angezeigt. Wenn er endet, wird der Datensatz mit end_reason, duration_seconds, billable_minutes und (später) einer Aufzeichnungs-URL und KI-Bewertung aktualisiert.

Eingehende Anrufe werden auf das Limit für gleichzeitige Anrufe Ihrer Organisation angerechnet (standardmäßig 20 Anrufe gleichzeitig, gemeinsam mit ausgehenden, Web- und Testanrufen). Ein Anruf, der eingeht, während das Limit erreicht ist, wird abgelehnt und beendet, bevor der Agent antwortet, nicht abgerechnet und als fehlgeschlagener Anruf mit dem Endgrund concurrent_call_limit_reached erfasst. Senden Sie eine E-Mail an support@thunderphone.com, wenn Sie ein höheres Limit benötigen.

5. Ergebnisse prüfen#

Rufen Sie die Liste der letzten Anrufe ab:

curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Rufen Sie das Transkript ab:

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

Und die Aufzeichnungs-URL (kurzlebig, signiert):

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

Wenn Sie den telephony.complete-Webhook abonniert haben, erhalten Sie dieselben Daten als POST an Ihren Server — siehe call.complete.

Wenn für Ihren Agenten Extraktionsfelder konfiguriert sind, kann die Payload des abgeschlossenen Anrufs auch strukturierte extrahierte Daten enthalten.

Nächste Schritte#