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

# Ring utgående samtal (API)

> Utlös ett AI-drivet utgående samtal från din egen kod – för enkäter, uppföljningar eller bekräftelseflöden.

Med utgående samtal kan du ge ThunderPhone ett destinationsnummer och en agentkonfiguration och låta AI:n ringa samtalet åt dig. Vanliga användningsområden:

* Bekräftelser av bokade tider
* Återuppringningar för enkäter
* Uppföljningar med ett andra försök efter ett missat samtal
* Aviseringar i dispatch-stil

<Note>
  Ringer du en hel lista? Instrumentpanelens funktion
  [**Kampanjer**](/sv/guides/outbound-campaigns)
  (`/dashboard/campaigns`) tar emot en CSV-fil med kontakter och hanterar
  tidszonsanpassade samtalsfönster, samtidighet och återuppringningspolicy åt
  dig. Den här guiden handlar om enskilda programmatiska samtal.
</Note>

## Förutsättningar

<Steps>
  <Step title="Skaffa ett VoIP-nummer">
    Utgående samtal kräver att du äger `from_number` via en
    [VoIP-anslutning](/api-reference/voip-connections). Demnummer är
    endast för inkommande samtal. Se
    [Ta med egna nummer](/sv/guides/bring-your-own-numbers).
  </Step>

  <Step title="Skapa en röstagent">
    En prompt för utgående samtal börjar ofta med att röstagenten
    identifierar sig själv och sitt syfte — "Hej, det här är Acme som ringer för att
    bekräfta din tid i morgon klockan 15…" Ange
    `outbound_speak_order` till `agent_first` (standardvärdet).
  </Step>

  <Step title="Ha ett positivt saldo">
    Utgående samtal returnerar `402 Payment Required` om saldot är ≤
    `$0.00`. Fyll på via
    [`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)
    eller aktivera [automatisk påfyllning](/api-reference/billing#update-auto-reload).
  </Step>
</Steps>

## Ring med en sparad röstagent

Det enklaste sättet — referera till en röstagent med 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"` betyder bara att begäran accepterades — samtalet
  är **inte uppkopplat ännu**. Hämta
  [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
  för aktuell status (`in_progress` → `completed` / `failed`).
</Warning>

## Ring med inline-konfiguration

Om du vill ha en engångsprompt som inte är värd att spara som en röstagent
kan du skicka `config` i stället. Strukturen matchar svarsformatet för
[`call.incoming`-webhooken](/sv/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ölj samtalet

Prenumerera parallellt på
[`telephony.complete`-webhooken](/sv/webhooks/events) —
det snabbaste sättet att få veta att ett samtal har avslutats. Om du inte kan ta emot inkommande
webhooks kan du hämta `GET /v1/calls/{call_id}` med några sekunders mellanrum; posten innehåller
`end_reason`, `duration_seconds` och inspelnings-URL:en när samtalet
avslutas.

## Fel som är värda att hantera

| Fel                                                      | Åtgärd                                                                                                     |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `402 Payment Required`                                   | Fyll på saldot eller aktivera automatisk påfyllning                                                        |
| `403` utgående samtal blockerat (demnummer)              | Skaffa ett VoIP-nummer i stället                                                                           |
| `403` utgående samtal blockerat (ej verifierat VoIP)     | Kö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` | Bekräfta att `from_number` matchar ett telefonnummer som du äger                                           |
| `502 Bad Gateway`                                        | Tillfälligt SIP-/LiveKit-fel; det är säkert att försöka igen                                               |

## Styra väntetid

Utgående samtal som drar ut på tiden eftersom den uppringda parten svarar långsamt
(IVR-träd, köer) kan begränsas med `max_hold_seconds`:

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

Röstag­enten lägger på om inget mänskligt ljud har tagits emot under de senaste
N sekunderna. Standardvärdet är 900 (15 minuter).

***

## Nästa steg

<CardGroup cols={2}>
  <Card title="Referens för utgående samtal" icon="phone-arrow-up-right" href="/api-reference/outbound-calls">
    Alla förfrågningsfält och felkoder.
  </Card>

  <Card title="Ta emot call.complete" icon="bolt" href="/sv/webhooks/call-complete">
    Strömma avslutade utgående samtal till ditt system.
  </Card>

  <Card title="Fakturering" icon="credit-card" href="/api-reference/billing">
    Automatisk påfyllning så att utgående samtal aldrig misslyckas på grund av saldo.
  </Card>

  <Card title="Testa utgående agenter" icon="flask" href="/sv/guides/test-agents">
    Testkör din utgående agent före produktion.
  </Card>
</CardGroup>