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

# Soita lähteviä puheluita (API)

> Käynnistä tekoälypohjainen lähtevä puhelu omasta koodistasi – kysely-, seuranta- tai vahvistustyönkulkuja varten.

Lähtevissä puheluissa voit antaa ThunderPhonelle kohdenumeron ja agentin
määrityksen, jolloin tekoäly soittaa puhelun puolestasi. Tyypillisiä
käyttötapauksia:

* Ajanvarausten vahvistukset
* Kyselyjen takaisinsoitot
* "Toinen yritys" -seurannat vastaamattoman puhelun jälkeen
* Välitystyyliset ilmoitukset

<Note>
  Soitatko kokonaiselle listalle? Hallintapaneelin
  [**Kampanjat**](/fi/guides/outbound-campaigns) -toiminto
  (`/dashboard/campaigns`) vastaanottaa CSV-tiedoston yhteystiedoista ja hoitaa
  aikavyöhykkeet huomioivat soittoajat, samanaikaisuuden ja uudelleenyrityskäytännön
  puolestasi. Tämä opas käsittelee yksittäisiä ohjelmallisia puheluita.
</Note>

## Vaatimukset

<Steps>
  <Step title="Ota käyttöön VoIP-numero">
    Lähtevät puhelut edellyttävät, että omistat `from_number`-numeron
    [VoIP-yhteyden](/api-reference/voip-connections) kautta. Demonumerot
    ovat vain saapuvia puheluita varten. Katso
    [Käytä omia numeroitasi](/fi/guides/bring-your-own-numbers).
  </Step>

  <Step title="Luo agentti">
    Lähteviin puheluihin suunnattu kehote alkaa yleensä siten, että agentti
    esittelee itsensä ja tarkoituksensa — "Hei, tässä Acme. Soitan
    vahvistaakseni huomisen klo 15 ajanvarauksesi…" Aseta
    `outbound_speak_order` arvoon `agent_first` (oletus).
  </Step>

  <Step title="Pidä saldo positiivisena">
    Lähtevät puhelut palauttavat virheen `402 Payment Required`, jos saldo on ≤
    `$0.00`. Lataa saldoa käyttämällä
    [`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)
    tai ota käyttöön [automaattinen saldon täydennys](/api-reference/billing#update-auto-reload).
  </Step>
</Steps>

## Soita puhelu tallennetulla agentilla

Yksinkertaisin tapa on viitata agenttiin sen tunnuksella:

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "agent_id":    12
  }'
```

Vastaus:

```json theme={null}
{ "call_id": 987654321, "status": "initiated" }
```

<Warning>
  `status: "initiated"` tarkoittaa vain, että pyyntö hyväksyttiin — puhelua
  **ei ole vielä yhdistetty**. Tarkista
  [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
  reaaliaikaisen tilan varalta (`in_progress` → `completed` / `failed`).
</Warning>

## Soita puhelu sisäisellä määrityksellä

Jos haluat kertaluonteisen kehotteen, jota ei kannata tallentaa agentiksi,
välitä sen sijaan `config`. Sen rakenne vastaa
[`call.incoming`-webhookin](/fi/webhooks/call-incoming) vastausskeemaa:

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'
```

## Seuraa puhelua

Tilaa samanaikaisesti
[`telephony.complete`-webhook](/fi/webhooks/events) —
se on nopein tapa saada tieto puhelun päättymisestä. Jos et voi vastaanottaa
saapuvia webhookeja, kysy `GET /v1/calls/{call_id}` muutaman sekunnin välein;
tietue sisältää puhelun päätyttyä `end_reason`-, `duration_seconds`- ja tallenteen
URL-osoitteen.

## Käsittelyn arvoiset virhetilanteet

| Virhe                                                    | Korjaus                                                                                                        |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `402 Payment Required`                                   | Lataa saldoa tai ota automaattinen saldon täydennys käyttöön                                                   |
| `403` lähtevät puhelut estetty (demonumero)              | Ota sen sijaan käyttöön VoIP-numero                                                                            |
| `403` lähtevät puhelut estetty (vahvistamaton VoIP)      | Suorita [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| `404 from_number is not registered to this organization` | Varmista, että `from_number` vastaa omistamaasi puhelinnumeroa                                                 |
| `502 Bad Gateway`                                        | Tilapäinen SIP- / LiveKit-virhe; uudelleenyritys on turvallinen                                                |

## Puhelun pidossaoloajan hallinta

Lähtevät puhelut, jotka kestävät pitkään, koska vastaanottaja reagoi hitaasti
(IVR-valikot, jonot), voidaan rajoittaa `max_hold_seconds`-asetuksella:

```json theme={null}
{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "agent_id":    12,
  "max_hold_seconds": 120
}
```

Agentti katkaisee puhelun, jos ihmisen ääntä ei ole vastaanotettu viimeisten
N sekunnin aikana. Oletusarvo on 900 (15 minuuttia).

***

## Seuraavat vaiheet

<CardGroup cols={2}>
  <Card title="Lähtevien puhelujen viite" icon="phone-arrow-up-right" href="/api-reference/outbound-calls">
    Kaikki pyyntökentät ja virhekoodit.
  </Card>

  <Card title="Vastaanota call.complete" icon="bolt" href="/fi/webhooks/call-complete">
    Välitä valmistuneet lähtevät puhelut järjestelmääsi.
  </Card>

  <Card title="Laskutus" icon="credit-card" href="/api-reference/billing">
    Automaattinen saldojen lisäys, jotta lähtevät puhelut eivät epäonnistu saldon vuoksi.
  </Card>

  <Card title="Testaa lähteviä agentteja" icon="flask" href="/fi/guides/test-agents">
    Tee lähtevästä agentistasi kuivaharjoitus ennen tuotantoa.
  </Card>
</CardGroup>