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

# Foreta utgående samtaler (API)

> Start en utgående samtale drevet av AI fra din egen kode — for spørreundersøkelser, oppfølging eller bekreftelser.

Utgående anrop lar deg gi et destinasjonsnummer og en agent-
konfigurasjon til ThunderPhone og la stemmeagenten foreta anropet på
dine vegne. Vanlige bruksområder:

* Avtalebekreftelser
* Tilbakeoppringinger for undersøkelser
* Oppfølging ved «andre forsøk» etter et tapt anrop
* Varsler i dispatch-stil

<Note>
  Ringer du en hel liste? Dashbordets
  [**Kampanjer**](/nb/guides/outbound-campaigns)-funksjon
  (`/dashboard/campaigns`) tar imot en CSV med kontakter og håndterer
  tidssonetilpassede ringevinduer, samtidighet og policy for nye forsøk
  for deg. Denne veiledningen dekker enkeltstående programatiske anrop.
</Note>

## Forutsetninger

<Steps>
  <Step title="Bruk et VoIP-nummer">
    Utgående anrop krever at du eier `from_number` via en
    [VoIP-tilkobling](/api-reference/voip-connections). Demo-numre er
    kun for innkommende anrop. Se
    [Bruk dine egne numre](/nb/guides/bring-your-own-numbers).
  </Step>

  <Step title="Opprett en agent">
    En prompt for utgående anrop starter gjerne 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` (standardverdien).
  </Step>

  <Step title="Ha en positiv saldo">
    Utgående anrop returnerer `402 Payment Required` hvis saldoen er ≤
    `$0.00`. Fyll på via
    [`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)
    eller aktiver [automatisk påfylling](/api-reference/billing#update-auto-reload).
  </Step>
</Steps>

## Foreta et anrop med en lagret agent

Den enkleste måten — referer til en agent etter id:

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

Svar:

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

<Warning>
  `status: "initiated"` betyr bare at forespørselen ble godtatt — anropet
  er **ennå ikke tilkoblet**. Poll
  [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
  for sanntidsstatus (`in_progress` → `completed` / `failed`).
</Warning>

## Foreta et anrop med innebygd konfigurasjon

Hvis du vil ha en engangsprompt 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 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"
    }
  }'
```

## Følg anropet

Abonner parallelt på
[`telephony.complete`-webhooken](/nb/webhooks/events) —
den raskeste måten å vite at et anrop er fullført på. Hvis du ikke kan
motta innkommende webhooks, poll `GET /v1/calls/{call_id}` hvert par
sekund. Oppføringen inkluderer `end_reason`, `duration_seconds` og
opptaks-URL-en når anropet avsluttes.

## Feiltilstander som er verdt å håndtere

| Feil                                                     | Løsning                                                                                                     |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `402 Payment Required`                                   | Fyll på saldoen eller aktiver automatisk påfylling                                                          |
| `403` utgående anrop blokkert (demo-nummer)              | Bruk et VoIP-nummer i stedet                                                                                |
| `403` utgående anrop blokkert (ubekreftet VoIP)          | Kjør [`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` | Bekreft at `from_number` samsvarer med et telefonnummer du eier                                             |
| `502 Bad Gateway`                                        | Forbigående SIP- / LiveKit-feil; det er trygt å prøve på nytt                                               |

## Kontrollere ventetid

Utgående samtaler som varer lenge fordi den som ringes opp svarer sent
(IVR-trær, køer), kan begrenses med `max_hold_seconds`:

```json theme={null}
{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "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 (15 minutter).

***

## Neste trinn

<CardGroup cols={2}>
  <Card title="Referanse for utgående samtaler" icon="phone-arrow-up-right" href="/api-reference/outbound-calls">
    Alle forespørselsfelt og feilkoder.
  </Card>

  <Card title="Motta call.complete" icon="bolt" href="/nb/webhooks/call-complete">
    Strømfør fullførte utgående samtaler til systemet ditt.
  </Card>

  <Card title="Fakturering" icon="credit-card" href="/api-reference/billing">
    Automatisk påfylling slik at utgående samtaler aldri mislykkes på grunn av saldo.
  </Card>

  <Card title="Test utgående agenter" icon="flask" href="/nb/guides/test-agents">
    Kjør en tørrkjøring av den utgående agenten din før produksjon.
  </Card>
</CardGroup>