Developer cookbook

Obsługa połączeń przychodzących (API)

Kompleksowo: skonfiguruj agenta, przypisz go do numeru telefonu, odbierz połączenie i sprawdź transkrypcję.

Kanoniczny proces „odbierania telefonu przez AI” z poziomu terminala. Wykonasz:

1. Utworzysz agenta z promptem i głosem.
2. Przydzielisz (lub dodasz własny) numer telefonu i przypiszesz agenta jako jego obsługę połączeń przychodzących.
3. Zadzwonisz na numer. Sprawdzisz dziennik połączeń, transkrypcję i nagranie.

Łączna liczba wywołań API: cztery. Łączny czas: mniej niż pięć minut.

1. Utwórz agenta#

Agent łączy prompt, głos i poziom produktu, które będą obsługiwać połączenie. Zobacz Agenci, aby poznać wszystkie pola konfiguracji; minimum to:

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

Zapisz zwrócone id — będzie potrzebne w kroku 2.

2. Uzyskaj numer telefonu#

Jeśli potrzebujesz tylko numeru, na który można zadzwonić, przydziel numer demonstracyjny z puli 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"}'

Odpowiedź zawiera id i number w formacie E.164. Numery demonstracyjne zaczynają ze stanem status="provisioning" i stają się active w ciągu kilku sekund — odpytywanie GET /v1/phone-numbers/{id} pozwala obserwować zmianę stanu, jeśli jest to potrzebne.

3. Przypisz agenta#

Powiąż agenta z kroku 1 z obsługą połączeń przychodzących numeru:

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

To wszystko — numer jest aktywny. Możesz także ustawić outbound_agent_id w tym samym żądaniu PATCH, aby numer był również gotowy do wykonywania połączeń wychodzących.

4. Odbierz połączenie#

Zadzwoń na numer ze swojego telefonu. Agent odbierze, przedstawi się zgodnie z promptem i rozpocznie się rozmowa.

Gdy połączenie trwa, pojawia się w GET /v1/calls ze stanem status="in_progress". Po jego zakończeniu rekord zostanie zaktualizowany o end_reason, duration_seconds, billable_minutes oraz (docelowo) adres URL nagrania i ocenę AI.

5. Sprawdź wyniki#

Pobierz listę ostatnich połączeń:

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

Pobierz transkrypcję:

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

Oraz adres URL nagrania (krótkotrwały, podpisany):

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

Jeśli zasubskrybujesz webhook telephony.complete, otrzymasz te same dane jako żądanie POST na swoim serwerze — zobacz call.complete.

Kolejne kroki#