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

# Uitgaande oproepen plaatsen (API)

> Start vanuit je eigen code een uitgaande oproep met AI voor enquêtes, follow-ups of bevestigingsflows.

Met uitgaand bellen kun je ThunderPhone een bestemmingsnummer en een
agentconfiguratie geven, waarna de AI namens jou het gesprek voert.
Veelvoorkomende toepassingen:

* Afspraakbevestigingen
* Terugbellen voor enquêtes
* Opvolging bij een "tweede poging" na een gemiste oproep
* Meldingen in dispatchstijl

<Note>
  Een hele lijst bellen? De functie
  [**Campagnes**](/nl/guides/outbound-campaigns) van het dashboard
  (`/dashboard/campaigns`) verwerkt een CSV met contacten en regelt
  tijdzonebewuste belvensters, gelijktijdigheid en het beleid voor
  opnieuw proberen voor je. Deze gids behandelt afzonderlijke programmatische oproepen.
</Note>

## Vereisten

<Steps>
  <Step title="Zorg voor een VoIP-nummer">
    Voor uitgaand bellen moet je eigenaar zijn van het `from_number` via een
    [VoIP-verbinding](/api-reference/voip-connections). Demonummers zijn
    alleen voor inkomende gesprekken. Zie
    [Gebruik je eigen nummers](/nl/guides/bring-your-own-numbers).
  </Step>

  <Step title="Maak een agent">
    Een prompt voor uitgaande gesprekken begint meestal met de agent die
    zichzelf en het doel identificeert — "Hallo, je spreekt met Acme om
    je afspraak voor morgen om 15.00 uur te bevestigen…" Stel
    `outbound_speak_order` in op `agent_first` (de standaardwaarde).
  </Step>

  <Step title="Houd een positief saldo aan">
    Uitgaande oproepen retourneren `402 Payment Required` als het saldo ≤
    `$0.00` is. Waardeer op via
    [`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)
    of schakel [automatisch opwaarderen](/api-reference/billing#update-auto-reload) in.
  </Step>
</Steps>

## Plaats een oproep met een opgeslagen agent

De eenvoudigste manier — verwijs naar een agent op 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
  }'
```

Antwoord:

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

<Warning>
  `status: "initiated"` betekent alleen dat de aanvraag is geaccepteerd — de oproep
  is **nog niet verbonden**. Poll
  [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
  voor de actuele status (`in_progress` → `completed` / `failed`).
</Warning>

## Plaats een oproep met inlineconfiguratie

Als je een eenmalige prompt wilt die het niet waard is om als agent op te slaan,
geef dan `config` door. De structuur komt overeen met het antwoordschema van de
[`call.incoming`-webhook](/nl/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"
    }
  }'
```

## Volg de oproep

Abonneer je parallel hierop op de
[`telephony.complete`-webhook](/nl/webhooks/events) —
de snelste manier om te weten dat een oproep is beëindigd. Als je geen inkomende
webhooks kunt ontvangen, poll dan elke paar seconden `GET /v1/calls/{call_id}`; het
record bevat `end_reason`, `duration_seconds` en de opname-URL zodra de oproep eindigt.

## Foutmodi die je moet afhandelen

| Fout                                                     | Oplossing                                                                                                       |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `402 Payment Required`                                   | Waardeer het saldo op of schakel automatisch opwaarderen in                                                     |
| `403` uitgaand geblokkeerd (demonummer)                  | Gebruik in plaats daarvan een VoIP-nummer                                                                       |
| `403` uitgaand geblokkeerd (niet-geverifieerde VoIP)     | Voer [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) uit |
| `404 from_number is not registered to this organization` | Controleer of `from_number` overeenkomt met een telefoonnummer waarvan je eigenaar bent                         |
| `502 Bad Gateway`                                        | Tijdelijke SIP- / LiveKit-fout; je kunt veilig opnieuw proberen                                                 |

## De wachttijd beheren

Uitgaande oproepen die lang duren doordat de gebelde partij traag reageert
(IVR-menu's, wachtrijen) kun je beperken met `max_hold_seconds`:

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

De agent verbreekt de oproep als er in de afgelopen
N seconden geen menselijke audio is ontvangen. De standaardwaarde is 900 (15 minuten).

***

## Volgende stappen

<CardGroup cols={2}>
  <Card title="Referentie voor uitgaande oproepen" icon="phone-arrow-up-right" href="/api-reference/outbound-calls">
    Elk aanvraagveld en elke foutcode.
  </Card>

  <Card title="call.complete ontvangen" icon="bolt" href="/nl/webhooks/call-complete">
    Stream voltooide uitgaande oproepen naar je systeem.
  </Card>

  <Card title="Facturering" icon="credit-card" href="/api-reference/billing">
    Automatisch opwaarderen zodat uitgaande oproepen nooit mislukken door onvoldoende saldo.
  </Card>

  <Card title="Uitgaande agenten testen" icon="flask" href="/nl/guides/test-agents">
    Test je uitgaande agent droog voordat je naar productie gaat.
  </Card>
</CardGroup>