Developer cookbook

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

Vereisten#

1. Zorg voor een VoIP-nummer

   Voor uitgaand bellen moet je eigenaar zijn van het from_number via een VoIP-verbinding. Demonummers zijn alleen voor inkomende gesprekken. Zie Gebruik je eigen nummers.

2. 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).

3. 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 of schakel automatisch opwaarderen in.

Plaats een oproep met een opgeslagen agent#

De eenvoudigste manier — verwijs naar een agent op id:

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:

{ "call_id": 987654321, "status": "initiated" }

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:

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

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:

{
  "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#