Uitgaande oproepen plaatsen (API)

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

Vereisten#

1. Kies een nummer dat uitgaande oproepen ondersteunt

   Gebruik een nummer dat je bezit via een VoIP-verbinding, 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.

2. Maak een spraakagent

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

3. Houd een positief saldo aan

   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, maar kan niet opwaarderen of automatisch opwaarderen wijzigen.

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":   "+14155552671",
    "agent_id":    12
  }'

Reactie:

{ "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 responsschema 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":   "+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 — 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:

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

Zie de referentie voor uitgaande oproepen 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:

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