> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

<Note>
  Tworzysz pierwszego agenta ręcznie? Panel prowadzi przez dokładnie
  ten proces — utwórz agenta, dodaj numer, zasymuluj, sprawdź — za pomocą
  kreatora z przewodnikiem. Zacznij od
  [szybkiego startu w panelu](/pl/quickstart-dashboard).
</Note>

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](/api-reference/agents), aby poznać wszystkie pola konfiguracji;
minimum to:

```bash theme={null}
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.

<Tip>
  Wybierz `spark` do prostych pytań i odpowiedzi przy najniższym koszcie, a `bolt`, gdy
  najważniejsza jest szybkość. Przejdź na `storm-base-with-ack`, gdy prompt
  wymaga głębszego rozumowania i może tolerować półsekundowe wypełnienie, podczas gdy
  model analizuje. Zobacz
  [poziomy produktu](/api-reference/agents#product-tiers-at-a-glance).
</Tip>

## 2. Uzyskaj numer telefonu

Jeśli potrzebujesz tylko numeru, na który można zadzwonić, przydziel numer demonstracyjny
z puli ThunderPhone:

```bash theme={null}
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}`](/api-reference/phone-numbers#retrieve-a-phone-number)
pozwala obserwować zmianę stanu, jeśli jest to potrzebne.

<Note>
  W środowisku produkcyjnym pomiń numery demonstracyjne i
  [dodaj własne numery przez VoIP](/pl/guides/bring-your-own-numbers).
  Numery demonstracyjne obsługują wyłącznie połączenia przychodzące i mają ograniczony wolumen.
</Note>

## 3. Przypisz agenta

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

```bash theme={null}
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`](/api-reference/calls#list-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ń:

```bash theme={null}
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

Pobierz transkrypcję:

```bash theme={null}
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):

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

Jeśli zasubskrybujesz
[webhook `telephony.complete`](/pl/webhooks/events),
otrzymasz te same dane jako żądanie POST na swoim serwerze — zobacz
[call.complete](/pl/webhooks/call-complete).

***

## Kolejne kroki

<CardGroup cols={2}>
  <Card title="Dynamiczna konfiguracja dla każdego połączenia" icon="bolt" href="/pl/guides/dynamic-call-config">
    Wybierz innego agenta dla każdego rozmówcy na podstawie numeru telefonu lub
    niestandardowej logiki w webhooku.
  </Card>

  <Card title="Dodaj integracje z narzędziami" icon="screwdriver-wrench" href="/pl/guides/build-tool-integration">
    Pozwól agentowi wywoływać Twoje interfejsy API w trakcie rozmowy.
  </Card>

  <Card title="Odbieraj webhooki call.complete" icon="bolt" href="/pl/webhooks/call-complete">
    Przesyłaj każdą zakończoną rozmowę do swojego CRM / potoku analitycznego.
  </Card>

  <Card title="Ocena AI i raporty problemów" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    Automatycznie oceniaj każde połączenie i kieruj oznaczone do weryfikacji.
  </Card>
</CardGroup>