--- title: "Uitgaande oproepen plaatsen (API)" description: "Start vanuit je eigen code een uitgaande oproep met spraak-AI — voor enquêtes, opvolgingen of bevestigingsflows." --- Met uitgaand bellen kun je ThunderPhone een bestemmingsnummer en een agentconfiguratie geven, waarna de AI namens jou belt. Typische toepassingen: - Afspraakbevestigingen - Terugbellen voor enquêtes - Follow-ups bij een "tweede poging" na een gemiste oproep - Meldingen in dispatchstijl Bel je een hele lijst? De functie [**Campagnes**](/nl/guides/outbound-campaigns) van het dashboard (`/dashboard/campaigns`) verwerkt een CSV met contactpersonen en regelt tijdzonebewuste belvensters, gelijktijdigheid en een beleid voor nieuwe pogingen voor je. Deze gids behandelt afzonderlijke programmatische oproepen. ## Vereisten Gebruik een nummer dat je bezit via een [VoIP-verbinding](/api-reference/voip-connections), of vraag toestemming om je ThunderPhone-nummers voor uitgaande oproepen te gebruiken vanaf de pagina Phone Numbers. ThunderPhone-nummers starten alleen voor inkomende oproepen. ThunderPhone beoordeelt elk verzoek handmatig; na goedkeuring kunnen die nummers oproepen plaatsen tot de goedgekeurde dagelijkse limiet (die om 00:00 UTC wordt gereset) en campagnes uitvoeren, en je kunt om een hogere limiet vragen. VoIP-nummers van klanten hebben geen dagelijkse limiet, dus we raden ze aan voor uitgaand bellen. Zie [Gebruik je eigen nummers](/nl/guides/bring-your-own-numbers). Een prompt voor uitgaande oproepen 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 standaardinstelling). Uitgaande oproepen retourneren `402 Payment Required` als het saldo ≤ `$0.00` is. Waardeer op of schakel automatisch opwaarderen in onder **Organisatie → Factureringsinstellingen** in het dashboard. Je `sk_live_` sleutel kan het saldo controleren met [`GET /v1/billing`](/api-reference/billing#get-billing-account), maar kan niet opwaarderen of automatisch opwaarderen wijzigen. ## Plaats een oproep met een opgeslagen agent De eenvoudigste manier — verwijs naar een agent op 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 }' ``` Reactie: ```json { "call_id": 987654321, "status": "initiated" } ``` `status: "initiated"` betekent alleen dat het verzoek 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`). ## 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 responsschema van de [`call.incoming`-webhook](/nl/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" } }' ``` ## Volg de oproep Abonneer je parallel 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, vraag dan elke paar seconden `GET /v1/calls/{call_id}` op; het record bevat `end_reason`, `duration_seconds` en de opname-URL zodra de oproep eindigt. Als je agent is ingesteld om na de oproep gestructureerde gegevens te extraheren, worden die gegevens afzonderlijk geleverd nadat de afronding is voltooid. ### Variabelen per oproep doorgeven aan een opgeslagen agent Opgeslagen agents kunnen placeholders zoals `{{name}}` of `{{name|there}}` gebruiken in prompttekst. Wanneer je een uitgaande oproep plaatst met `agent_id`, geef je `variables` door met de waarden voor die oproep: ```json { "from_number": "+[REDACTED_PHONE]", "to_number": "+[REDACTED_PHONE]", "agent_id": 12, "variables": { "name": "Jordan" } } ``` Gebruik tekenreekswaarden met de placeholdernaam als sleutel. Deze variabelen gelden voor opgeslagen agents; het inline `config`-voorbeeld in deze handleiding gebruikt ze niet. ## Storingsmodi die je moet afhandelen | Fout | Oplossing | |-------|-----| | `402 Payment Required` | Waardeer het saldo op of schakel automatisch herladen in | | `400` met `code: destination_not_allowed` | ThunderPhone belt dat nummer niet: ongeldige nummers, alarmnummers, nummers met verhoogd tarief, korte nummers of landen waarop sancties van toepassing zijn. Vanaf ThunderPhone-nummers zijn alleen gewone Amerikaanse en Canadese nummers toegestaan (geen nummers met verhoogd tarief). `reason` geeft aan welke; zie [geblokkeerde bestemmingen](/api-reference/outbound-calls#blocked-destinations) | | `409` met `retryable: false` voor een ThunderPhone-nummer | Volg de `code`: vraag uitgaand bellen aan op de pagina Telefoonnummers, wacht op een lopende beoordeling of gebruik een ander geschikt nummer | | `429` met `code: platform_outbound_daily_limit_reached` | De organisatie heeft de uitgaande oproepen van vandaag vanaf ThunderPhone-nummers verbruikt. Wacht op `resets_at` (00:00 UTC), vraag een hogere limiet aan op de pagina Telefoonnummers of bel vanaf een nummer op je eigen VoIP-verbinding | | `429` met `code: concurrent_call_limit_reached` | De organisatie heeft evenveel oproepen bezig als de [limiet voor gelijktijdige oproepen](/api-reference/introduction#call-limits) (standaard 20, inclusief inkomende, uitgaande, web- en testoproepen). Probeer opnieuw na het aantal seconden in de header `Retry-After` of wanneer een oproep eindigt; stuur een e-mail naar support@thunderphone.com om de limiet te verhogen | | `429` met `code: same_number_too_soon` | Je hebt minder dan 10 seconden geleden hetzelfde `to_number` gebeld. Probeer opnieuw na het aantal seconden in de header `Retry-After` | | `409` met `retryable: false` voor een VoIP-nummer van een klant | Corrigeer de status die door `code` wordt aangegeven; voer bij verificatiefouten [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) uit | | `409` idempotentieconflict | Hergebruik de sleutel alleen met het oorspronkelijke genormaliseerde verzoek, of stuur een nieuwe sleutel | | `404 from_number is not registered to this organization` | Controleer of `from_number` overeenkomt met een actief telefoonnummer in je organisatie. Een nummer dat al wordt ingericht, is mislukt, wordt vrijgegeven of is vrijgegeven, retourneert ook deze respons | | `500` met alleen een veld `detail` | Er is geen uitgaande trunk geconfigureerd. Neem contact op met support; dit is geen probleem met de nummerstatus dat je kunt corrigeren | | `502 Bad Gateway` | Tijdelijke SIP-/LiveKit-fout; opnieuw proberen is veilig | Zie de [referentie voor uitgaande oproepen](/api-reference/outbound-calls#error-responses) voor de volledige stabiele lijst met geschiktheidscodes en beide `409`-responsvormen. Als een actief nummer ongeschikt wordt nadat het verzoek is geaccepteerd maar voordat de oproep wordt geplaatst, retourneert de laatste controle de niet-opnieuw-probeerbare `409`-payload. ## Wachttijd beheren Uitgaande oproepen die lang duren doordat de gebelde partij traag reageert (IVR-bomen, wachtrijen) kunnen worden begrensd met `max_hold_seconds`: ```json { "from_number": "+15551234567", "to_number": "+14155552671", "agent_id": 12, "max_hold_seconds": 120 } ``` De agent verbreekt de verbinding als er in de afgelopen N seconden geen menselijke audio is ontvangen. De standaardwaarde is 900 seconden (15 minuten). --- ## Volgende stappen Elk verzoekveld en elke foutcode. Stream voltooide uitgaande oproepen naar je systeem. Automatisch opwaarderen zodat uitgaand bellen nooit mislukt door onvoldoende saldo. Test je uitgaande agent zonder uitvoering vóór productie.