---
title: "Foreta utgående samtaler (API)"
description: "Utløs en KI-drevet utgående samtale fra din egen kode — for spørreundersøkelser, oppfølging eller bekreftelsesflyter."
---
Utgående oppringing lar deg sende et destinasjonsnummer og en
agentkonfigurasjon til ThunderPhone, slik at KI-en ringer på dine
vegne. Vanlige bruksområder:
- Avtalebekreftelser
- Tilbakeoppringinger for undersøkelser
- «Andre forsøk»-oppfølging etter et ubesvart anrop
- Varsler i utsendelsesstil
Ringe en hel liste? Dashbordets funksjon for
[**Kampanjer**](/nb/guides/outbound-campaigns)
(`/dashboard/campaigns`) tar imot en CSV-fil med kontakter og håndterer
tidssonebevisste oppringingsvinduer, samtidighet og policy for
nye forsøk for deg. Denne veiledningen dekker enkeltstående programmatisk oppringing.
## Forutsetninger
Bruk et nummer du eier gjennom en
[VoIP-tilkobling](/api-reference/voip-connections), eller be om tillatelse
til å bruke ThunderPhone-numrene dine til utgående anrop fra siden Phone Numbers.
ThunderPhone-numre starter som kun innkommende. ThunderPhone gjennomgår hver
forespørsel manuelt. Når den er godkjent, kan numrene ringe opp til den
godkjente daglige grensen (som tilbakestilles kl. 00:00 UTC) og kjøre kampanjer,
og du kan be om en høyere grense. Kundens VoIP-numre har ingen daglig grense, så vi anbefaler
dem for utgående anrop. Se
[Bruk dine egne numre](/nb/guides/bring-your-own-numbers).
En prompt tilpasset utgående anrop starter vanligvis med at agenten
identifiserer seg selv og formålet sitt — «Hei, dette er Acme som ringer for å
bekrefte avtalen din i morgen kl. 15 …» Angi
`outbound_speak_order` til `agent_first` (standard).
Utgående anrop returnerer `402 Payment Required` hvis saldoen er ≤
`$0.00`. Fyll på saldoen eller aktiver automatisk påfylling under
**Organisasjon → Faktureringsinnstillinger** i dashbordet. `sk_live_`-
nøkkelen din kan sjekke saldoen med
[`GET /v1/billing`](/api-reference/billing#get-billing-account), men
kan ikke fylle på saldoen eller endre automatisk påfylling.
## Ring med en lagret agent
Den enkleste metoden — referer til en agent med ID:
```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
}'
```
Svar:
```json
{ "call_id": 987654321, "status": "initiated" }
```
`status: "initiated"` betyr bare at forespørselen ble akseptert — anropet
er **ennå ikke tilkoblet**. Poll
[`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
for direkte status (`in_progress` → `completed` / `failed`).
## Ring med innebygd konfigurasjon
Hvis du vil ha en engangsledetekst som ikke er verdt å lagre som en agent,
sender du `config` i stedet. Strukturen samsvarer med svarskjemaet for
[`call.incoming`-webhooken](/nb/webhooks/call-incoming):
```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"
}
}'
```
## Følg samtalen
Abonner parallelt på
[`telephony.complete`-webhooken](/nb/webhooks/events) —
den raskeste måten å vite at en samtale er avsluttet på. Hvis du ikke kan ta imot innkommende
webhooker, spør `GET /v1/calls/{call_id}` hvert par sekunder; oppføringen
inneholder `end_reason`, `duration_seconds` og opptaks-URL-en når samtalen avsluttes.
Hvis agenten din er konfigurert til å hente ut strukturerte data etter samtalen,
leveres disse dataene separat etter at fullføringen er ferdig.
### Send variabler per samtale til en lagret agent
Lagrede agenter kan bruke plassholdere som `{{name}}` eller `{{name|there}}` i
prompttekst. Når du foretar en utgående samtale med `agent_id`, sender du
`variables` med verdiene for den samtalen:
```json
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"agent_id": 12,
"variables": {
"name": "Jordan"
}
}
```
Bruk strengverdier med plassholdernavnet som nøkkel. Disse variablene gjelder
lagrede agenter; denne veiledningens innebygde `config`-eksempel bruker dem ikke.
## Feiltilstander det er verdt å håndtere
| Feil | Løsning |
|-------|-----|
| `402 Payment Required` | Fyll på saldoen eller aktiver automatisk påfylling |
| `400` med `code: destination_not_allowed` | ThunderPhone ringer ikke dette nummeret: ugyldige numre, nødnumre, numre med overtakst, kortnumre eller land underlagt sanksjoner. Fra ThunderPhone-numre kan du bare ringe vanlige amerikanske og canadiske numre (ikke numre med overtakst). `reason` angir hvilket; se [blokkerte destinasjoner](/api-reference/outbound-calls#blocked-destinations) |
| `409` med `retryable: false` for et ThunderPhone-nummer | Følg `code`: be om utgående samtaler på siden Phone Numbers, vent på en pågående gjennomgang, eller bruk et annet kvalifisert nummer |
| `429` med `code: platform_outbound_daily_limit_reached` | Organisasjonen har brukt opp dagens utgående samtaler fra ThunderPhone-numre. Vent til `resets_at` (00:00 UTC), be om en høyere grense på siden Phone Numbers, eller ring fra et nummer på din egen VoIP-tilkobling |
| `429` med `code: concurrent_call_limit_reached` | Organisasjonen har så mange samtaler pågående som [grensen for samtidige samtaler](/api-reference/introduction#call-limits) tillater (20 som standard, inkludert innkommende, utgående, nett- og testsamtaler). Prøv på nytt etter antallet sekunder i `Retry-After`-headeren eller når en samtale avsluttes; send e-post til support@thunderphone.com for å øke grensen |
| `429` med `code: same_number_too_soon` | Du ringte det samme `to_number` for mindre enn 10 sekunder siden. Prøv på nytt etter antallet sekunder i `Retry-After`-headeren |
| `409` med `retryable: false` for et kundes VoIP-nummer | Korriger tilstanden som er angitt av `code`; ved verifiseringsfeil kjører du [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| `409` idempotenskonflikt | Gjenbruk nøkkelen bare med den opprinnelige normaliserte forespørselen, eller send en ny nøkkel |
| `404 from_number is not registered to this organization` | Bekreft at `from_number` samsvarer med et aktivt telefonnummer i organisasjonen din. Et nummer som allerede klargjøres, har feilet, frigjøres eller er frigitt, returnerer også dette svaret |
| `500` med bare et `detail`-felt | Ingen utgående trunk er konfigurert. Kontakt brukerstøtte; dette er ikke et problem med nummerstatus som du kan korrigere |
| `502 Bad Gateway` | Midlertidig SIP-/LiveKit-feil; det er trygt å prøve på nytt |
Se [referansen for utgående samtaler](/api-reference/outbound-calls#error-responses)
for den komplette stabile listen over kvalifiseringskoder og begge `409`-svarformatene.
Hvis et aktivt nummer blir ukvalifisert etter at forespørselen er godtatt, men før
samtalen foretas, returnerer den endelige kontrollen `409`-nyttelasten som ikke kan prøves på nytt.
## Kontrollere ventetid
Utgående samtaler som varer lenge fordi mottakeren er treg til å svare
(IVR-trær, køer), kan begrenses med `max_hold_seconds`:
```json
{
"from_number": "+15551234567",
"to_number": "+14155552671",
"agent_id": 12,
"max_hold_seconds": 120
}
```
Agenten legger på hvis det ikke har blitt mottatt menneskelig lyd de siste
N sekundene. Standardverdien er 900 sekunder (15 minutter).
---
## Neste steg
Alle forespørselsfelt og feilkoder.
Strøm fullførte utgående samtaler til systemet ditt.
Automatisk påfylling slik at utgående samtaler aldri feiler på grunn av saldo.
Testkjør den utgående agenten før produksjon.