---
title: "Soita lähteviä puheluita (API)"
description: "Käynnistä tekoälyohjattu lähtevä puhelu omasta koodistasi – kysely-, seuranta- tai vahvistustyönkulkuja varten."
---
Lähtevien puheluiden avulla voit antaa kohdenumeron ja agentin
määrityksen ThunderPhonelle ja antaa tekoälyn soittaa puhelun
puolestasi. Tyypillisiä käyttötapauksia:
- Tapaamisvahvistukset
- Kyselyjen takaisinsoitot
- Toisen yrityksen seurannat vastaamattoman puhelun jälkeen
- Lähetysluonteiset ilmoitukset
Soitatko kokonaiselle listalle? Hallintapaneelin
[**Kampanjat**](/fi/guides/outbound-campaigns) -ominaisuus
(`/dashboard/campaigns`) vastaanottaa yhteystietojen CSV-tiedoston ja hoitaa
aikavyöhykkeet huomioivat soittoajat, samanaikaisuuden ja
uudelleenyrityskäytännön puolestasi. Tämä opas käsittelee yksittäisiä ohjelmallisia puheluita.
## Vaatimukset
Käytä numeroa, jonka omistat
[VoIP-yhteyden](/api-reference/voip-connections) kautta, tai pyydä lupaa
käyttää ThunderPhone-numeroitasi ulospäin soittamiseen Phone Numbers
-sivulla. ThunderPhone-numerot ovat aluksi vain saapuvia puheluita varten. ThunderPhone tarkistaa jokaisen
pyynnön manuaalisesti; hyväksynnän jälkeen näillä numeroilla voi soittaa puheluita hyväksyttyyn päivittäiseen
enimmäismäärään asti (nollautuu klo 00:00 UTC) ja suorittaa kampanjoita, ja voit
pyytää suurempaa rajaa. Asiakkaan VoIP-numeroilla ei ole päivittäistä rajaa, joten suosittelemme
niitä ulospäin soittamiseen. Katso
[Käytä omia numeroitasi](/fi/guides/bring-your-own-numbers).
Ulospäin soittamiseen suunnattu kehote alkaa yleensä siten, että agentti
kertoo, kuka se on ja mikä on puhelun tarkoitus — "Hei, täällä Acme. Soitan
vahvistaakseni huomisen tapaamisesi klo 15…" Aseta
`outbound_speak_order` arvoon `agent_first` (oletusarvo).
Ulospäin soitetut puhelut palauttavat virheen `402 Payment Required`, jos saldo on ≤
`$0.00`. Lisää saldoa tai ota automaattinen saldon lisäys käyttöön hallintapaneelin kohdassa
**Organisaatio → Laskutusasetukset**. `sk_live_`-avaimesi
voi tarkistaa saldon pyynnöllä
[`GET /v1/billing`](/api-reference/billing#get-billing-account), mutta
sillä ei voi lisätä saldoa tai muuttaa automaattista saldon lisäystä.
## Soita puhelu tallennetulla agentilla
Yksinkertaisin tapa on viitata agenttiin tunnuksella:
```bash
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": "+14155552671",
"agent_id": 12
}'
```
Vastaus:
```json
{ "call_id": 987654321, "status": "initiated" }
```
`status: "initiated"` tarkoittaa vain, että pyyntö hyväksyttiin — puhelu
**ei ole vielä yhdistetty**. Kysy
[`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
saadaksesi reaaliaikaisen tilan (`in_progress` → `completed` / `failed`).
## Soita puhelu upotetulla 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
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": "+14155552671",
"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) —
nopein tapa tietää, että puhelu on päättynyt. Jos et voi vastaanottaa saapuvia
webhookeja, kyselyllä `GET /v1/calls/{call_id}` muutaman sekunnin välein; tietue
sisältää `end_reason`-, `duration_seconds`- ja tallenne-URL:n, kun puhelu päättyy.
Jos agenttisi on määritetty poimimaan jäsenneltyä dataa puhelun jälkeen,
data toimitetaan erikseen viimeistelyn valmistuttua.
### Välitä puhelukohtaisia muuttujia tallennetulle agentille
Tallennetut agentit voivat käyttää kehotetekstissä paikkamerkkejä, kuten `{{name}}` tai `{{name|there}}`.
Kun soitat lähtevän puhelun käyttäen `agent_id`:tä, välitä `variables`, joissa ovat kyseisen puhelun arvot:
```json
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"agent_id": 12,
"variables": {
"name": "Jordan"
}
}
```
Käytä merkkijonoarvoja, joiden avaimena on paikkamerkin nimi. Nämä muuttujat koskevat
tallennettuja agentteja; tämän oppaan upotettu `config`-esimerkki ei käytä niitä.
## Käsittelyn arvoiset virhetilat
| Virhe | Korjaus |
|-------|---------|
| `402 Payment Required` | Lisää saldoa tai ota automaattinen saldon lisäys käyttöön |
| `400` ja `code: destination_not_allowed` | ThunderPhone ei soita tähän numeroon: virheelliset numerot, hätänumerot, lisämaksulliset numerot, lyhytnumerot tai pakotteiden alaisissa maissa olevat numerot. ThunderPhone-numeroista voi soittaa vain tavallisiin yhdysvaltalaisiin ja kanadalaisiin numeroihin (ei lisämaksullisiin numeroihin). `reason` kertoo, mistä on kyse; katso [estetyt kohteet](/api-reference/outbound-calls#blocked-destinations) |
| `409` ja `retryable: false` ThunderPhone-numerolle | Noudata `code`-kentän ohjetta: pyydä lähtevien puhelujen käyttöoikeutta Puhelinnumerot-sivulla, odota käsittelyssä olevaa tarkistusta tai käytä toista kelpoista numeroa |
| `429` ja `code: platform_outbound_daily_limit_reached` | Organisaatio on käyttänyt kaikki tämän päivän ThunderPhone-numeroista soitetut lähtevät puhelut. Odota kohtaan `resets_at` (00:00 UTC), pyydä korkeampaa rajaa Puhelinnumerot-sivulla tai soita oman VoIP-yhteytesi numerosta |
| `429` ja `code: concurrent_call_limit_reached` | Organisaatiolla on yhtä monta puhelua käynnissä kuin sen [samanaikaisten puhelujen raja](/api-reference/introduction#call-limits) sallii (oletuksena 20, mukaan lukien saapuvat, lähtevät, verkko- ja testipuhelut). Yritä uudelleen `Retry-After`-otsakkeen ilmoittaman sekuntimäärän jälkeen tai puhelun päätyttyä; pyydä rajan nostamista lähettämällä sähköpostia osoitteeseen support@thunderphone.com |
| `429` ja `code: same_number_too_soon` | Soitit samaan `to_number`-numeroon alle 10 sekuntia sitten. Yritä uudelleen `Retry-After`-otsakkeen ilmoittaman sekuntimäärän jälkeen |
| `409` ja `retryable: false` asiakkaan VoIP-numerolle | Korjaa `code`-kentän ilmoittama tila; jos vahvistus epäonnistuu, suorita [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| `409`-idempotenssiristiriita | Käytä avainta uudelleen vain alkuperäisen normalisoidun pyynnön kanssa tai lähetä uusi avain |
| `404 from_number is not registered to this organization` | Varmista, että `from_number` vastaa organisaatiosi aktiivista puhelinnumeroa. Tämä vastaus palautetaan myös numerolle, jonka käyttöönotto on jo käynnissä, joka on epäonnistunut, vapautettavana tai vapautettu |
| `500`, jossa on vain `detail`-kenttä | Lähtevää trunk-yhteyttä ei ole määritetty. Ota yhteyttä tukeen; tämä ei ole numeron tilaan liittyvä ongelma, jonka voisit korjata |
| `502 Bad Gateway` | Tilapäinen SIP- tai LiveKit-virhe; uudelleenyritys on turvallinen |
Katso [lähtevien puhelujen viite](/api-reference/outbound-calls#error-responses)
täydellisestä pysyvien kelpoisuuskoodien luettelosta ja molemmista `409`-vastausmuodoista.
Jos aktiivinen numero muuttuu kelpaamattomaksi pyynnön hyväksymisen jälkeen mutta ennen
puhelun soittamista, lopullinen tarkistus palauttaa uudelleenyritykseen kelpaamattoman `409`-vastauksen.
## Pitoajan hallinta
Lähtevien puhelujen kestoa voidaan rajoittaa, jos vastaanottaja vastaa hitaasti
(IVR-valikot, jonot), käyttämällä `max_hold_seconds`-asetusta:
```json
{
"from_number": "+15551234567",
"to_number": "+14155552671",
"agent_id": 12,
"max_hold_seconds": 120
}
```
Agentti katkaisee puhelun, jos ihmisen ääntä ei ole vastaanotettu viimeisten
N sekunnin aikana. Oletusarvo on 900 sekuntia (15 minuuttia).
---
## Seuraavat vaiheet
Kaikki pyyntökentät ja virhekoodit.
Välitä valmistuneet lähtevät puhelut järjestelmääsi.
Ota automaattinen saldon täydennys käyttöön, jotta lähtevät puhelut eivät koskaan epäonnistu saldon vuoksi.
Suorita lähtevälle agentillesi kuivaharjoittelu ennen tuotantoa.