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

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

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

1. Utworzenie agenta z promptem i głosem.
2. Przydzielenie (lub dodanie własnego) numeru telefonu oraz przypisanie agenta jako jego obsługi połączeń przychodzących.
3. Połączenie na numer. Sprawdzenie dziennika połączeń, transkrypcji i nagrania.

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

1. Utwórz agenta#

Agent obejmuje prompt, głos i wariant produktu używane podczas połączenia. Możesz także ustawić dla agenta limity połączeń, takie jak max_call_duration_seconds i ring_duration_seconds. Agenci obsługują również intro_clip i intro_ring_count, aby odtworzyć wcześniej nagrane wprowadzenie i maksymalnie dwa sygnały dzwonienia, zanim agent zacznie mówić. Nowi agenci wymagają również strefy czasowej. Jeśli Twój agent jest wielojęzyczny, możesz ustawić language_switching, aby określić, czy pyta przed zmianą języka, czy dostosowuje się do języka rozmówcy. Wszystkie pola konfiguracji znajdziesz w sekcji Agenci; minimalna konfiguracja 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ć, uzyskaj numer ThunderPhone 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 oraz number w formacie E.164. Numery ThunderPhone początkowo mają status="provisioning" i w ciągu kilku sekund stają się active — odpytywanie GET /v1/phone-numbers/{id} pozwala obserwować tę zmianę, jeśli jest to potrzebne.

3. Przypisz agenta#

Powiąż agenta z kroku 1 z kierunkiem przychodzącym 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. Po zatwierdzeniu połączeń wychodzących dla Twojej organizacji możesz również ustawić outbound_agent_id w tym samym żądaniu PATCH. Do tego czasu API odrzuca takie przypisanie z kodem 400.

Jeśli kierujesz połączenia przychodzące przez webhook konfiguracji zamiast stałego inbound_agent_id, webhook może teraz zwracać dla każdego połączenia timezone wraz z agent_id i variables.

4. Odbierz połączenie#

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

W trakcie połączenia jest ono widoczne w GET /v1/calls ze statusem status="in_progress". Po zakończeniu rekord zostaje zaktualizowany o end_reason, duration_seconds, billable_minutes oraz (ostatecznie) adres URL nagrania i ocenę AI.

Połączenia przychodzące wliczają się do limitu współbieżnych połączeń w Twojej organizacji (domyślnie 20 połączeń w toku, współdzielonych z połączeniami wychodzącymi, internetowymi i testowymi). Połączenie, które nadejdzie po osiągnięciu limitu, zostanie odrzucone i rozłączone, zanim agent odbierze, nie zostanie naliczone i zostanie zarejestrowane jako nieudane połączenie z powodem zakończenia concurrent_call_limit_reached. Napisz na support@thunderphone.com, jeśli potrzebujesz wyższego limitu.

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 zasubskrybowano webhook telephony.complete, te same dane zostaną wysłane jako żądanie POST na serwer — zobacz call.complete.

Jeśli agent ma skonfigurowane pola ekstrakcji, ładunek zakończonego połączenia może również zawierać ustrukturyzowane wyodrębnione dane.

Kolejne kroki#