> ## 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.

# Käsittele saapuvia puheluita (API)

> Alusta loppuun: määritä agentti, liitä se puhelinnumeroon, vastaanota puhelu ja tarkista litterointi.

<Note>
  Rakennatko ensimmäistä agenttiasi käsin? Hallintapaneeli opastaa
  täsmälleen tämän työnkulun läpi — rakenna agentti, lisää numero,
  simuloi, tarkista — ohjatun toiminnon avulla. Aloita
  [hallintapaneelin pikaoppaasta](/fi/quickstart-dashboard).
</Note>

Tavanomainen ”vastaa puhelimeen tekoälyn avulla” -työnkulku päätelaitteeltasi.
Sinä:

1. Luo agentti, jolla on kehote ja ääni.
2. Hanki (tai tuo) puhelinnumero ja määritä agentti sen
   saapuvien puhelujen käsittelijäksi.
3. Soita numeroon. Tarkastele puhelulokia, litterointia ja tallennetta.

API-kutsuja yhteensä: neljä. Kokonaisaika: alle viisi minuuttia.

## 1. Luo agentti

Agentti yhdistää kehotteen, äänen ja tuotetason, jotka ohjaavat
puhelua. Katso kaikki määrityskentät kohdasta [Agentit](/api-reference/agents);
vähimmäismääritys on:

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

Tallenna palautettu `id` — tarvitset sitä vaiheessa 2.

<Tip>
  Valitse `spark` yksinkertaisiin kysymyksiin ja vastauksiin alhaisimmilla
  kustannuksilla, ja `bolt`, kun nopeus on tärkeintä. Päivitä tasolle
  `storm-base-with-ack`, kun kehotteesi tarvitsee syvempää päättelyä
  ja voi sietää puolen sekunnin täyteäänen mallin ajatellessa. Katso
  [tuotetasot](/api-reference/agents#product-tiers-at-a-glance).
</Tip>

## 2. Hanki puhelinnumero

Jos tarvitset vain numeron, johon soittaa, hanki demonumero
ThunderPhonen numerovarannosta:

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

Vastaus sisältää `id`:n ja `number`:n E.164-muodossa. Demonumerot
alkavat tilassa `status="provisioning"` ja muuttuvat tilaan `active`
muutamassa sekunnissa — voit seurata tilan vaihtumista kyselemällä
[`GET /v1/phone-numbers/{id}`](/api-reference/phone-numbers#retrieve-a-phone-number),
jos tarvitset sitä.

<Note>
  Tuotantokäytössä ohita demonumerot ja
  [tuo omat numerosi VoIP:n kautta](/fi/guides/bring-your-own-numbers).
  Demonumerot ovat vain saapuville puheluille, ja niiden käyttömäärää on rajoitettu.
</Note>

## 3. Määritä agentti

Määritä vaiheessa 1 luotu agentti numeron saapuvien puhelujen
käsittelijäksi:

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

Siinä kaikki — numero on käytössä. Voit myös määrittää `outbound_agent_id`:n
samassa PATCH-pyynnössä, jolloin numero on valmis myös lähteviin puheluihin.

## 4. Vastaa puheluun

Soita numeroon puhelimellasi. Agentti vastaa, esittelee itsensä
kehotteesi mukaisesti, ja keskustelu alkaa.

Puhelun ollessa käynnissä se näkyy kohteessa
[`GET /v1/calls`](/api-reference/calls#list-calls) tilalla
`status="in_progress"`. Kun puhelu päättyy, tietue päivittyy kentillä
`end_reason`, `duration_seconds`, `billable_minutes` sekä (myöhemmin)
tallenteen URL-osoitteella ja tekoälyarviolla.

## 5. Tarkista tulokset

Hae viimeisimpien puheluiden luettelo:

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

Hae litterointi:

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

Ja tallenteen URL-osoite (lyhytkestoinen, allekirjoitettu):

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

Jos tilasit
[`telephony.complete`-webhookin](/fi/webhooks/events),
saat samat tiedot POST-pyyntönä palvelimellesi — katso
[call.complete](/fi/webhooks/call-complete).

***

## Seuraavat vaiheet

<CardGroup cols={2}>
  <Card title="Dynaaminen asetusten määritys puhelukohtaisesti" icon="bolt" href="/fi/guides/dynamic-call-config">
    Valitse eri agentti kullekin soittajalle puhelinnumeron tai webhookin mukautetun logiikan perusteella.
  </Card>

  <Card title="Lisää työkalintegraatioita" icon="screwdriver-wrench" href="/fi/guides/build-tool-integration">
    Anna agentin kutsua rajapintojasi kesken keskustelun.
  </Card>

  <Card title="Vastaanota call.complete-webhookit" icon="bolt" href="/fi/webhooks/call-complete">
    Siirrä jokainen päättynyt puhelu CRM- tai analytiikkaputkeesi.
  </Card>

  <Card title="Tekoälyarviointi ja ongelmaraportit" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    Pisteytä jokainen puhelu automaattisesti ja ohjaa merkityt puhelut tarkistettaviksi.
  </Card>
</CardGroup>