---
title: "Inkomende oproepen afhandelen (API)"
description: "Van begin tot eind: configureer een agent, wijs deze toe aan een telefoonnummer, neem een oproep aan en bekijk het transcript."
---
Bouw je je eerste agent handmatig? Het dashboard doorloopt precies deze
flow — bouw de agent, voeg een nummer toe, simuleer, beoordeel — met een
begeleide wizard. Begin bij de
[dashboard-snelstart](/nl/quickstart-dashboard).
De standaardflow voor "een telefoon beantwoorden met AI", vanuit je terminal.
Je gaat:
1. Een agent maken met een prompt en stem.
2. Een telefoonnummer provisionen (of meebrengen) en de agent toewijzen als inkomende handler.
3. Het nummer bellen. Het oproeplogboek, transcript en de opname bekijken.
Totaal aantal API-aanroepen: vier. Totale tijd: minder dan vijf minuten.
## 1. Een agent maken
Een agent bundelt de prompt, stem en het productpakket die het gesprek
aansturen. Je kunt op de agent ook oproeplimieten instellen, zoals `max_call_duration_seconds`
en `ring_duration_seconds`. Agents ondersteunen ook een `intro_clip`
en `intro_ring_count` om een vooraf opgenomen intro en maximaal twee beltonen af te spelen voordat
de agent spreekt. Nieuwe agents hebben ook een tijdzone nodig.
Zie [Agents](/api-reference/agents) voor elk configuratieveld; het
minimum is:
```bash
curl -X POST https://api.thunderphone.com/v1/agents \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Support",
"prompt": "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
"voice": "john",
"product": "spark"
}'
```
Sla de geretourneerde `id` op — je hebt die nodig in stap 2.
Kies `spark` voor eenvoudige vraag-en-antwoordgesprekken tegen de laagste kosten, en `bolt` wanneer snelheid
het belangrijkst is. Upgrade naar `storm-base-with-ack` wanneer je prompt
diepgaander redeneren nodig heeft en een halve seconde opvultijd kan verdragen terwijl
het model nadenkt. Zie
[productpakketten](/api-reference/agents#product-tiers-at-a-glance).
## 2. Een telefoonnummer krijgen
Als je alleen iets nodig hebt om naartoe te bellen, haal dan een ThunderPhone-nummer
uit de pool van ThunderPhone:
```bash
curl -X POST https://api.thunderphone.com/v1/phone-numbers \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"area_code": "415"}'
```
Het antwoord bevat een `id` en een `number` in E.164. ThunderPhone-
nummers beginnen met `status="provisioning"` en worden binnen enkele
seconden `active` — voer periodiek
[`GET /v1/phone-numbers/{id}`](/api-reference/phone-numbers#retrieve-a-phone-number)
uit om de overgang te volgen als dat relevant is.
ThunderPhone-nummers starten alleen voor inkomende oproepen. Een organisatiebeheerder kan
uitgaande oproepen aanvragen via de pagina Telefoonnummers. ThunderPhone beoordeelt elke
aanvraag handmatig; na goedkeuring kunnen de nummers oproepen plaatsen en
campagnes uitvoeren. VoIP-nummers van klanten blijven ongewijzigd.
## 3. De agent toewijzen
Koppel de agent uit stap 1 aan de inkomende richting van het nummer:
```bash
curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"inbound_agent_id": 12}'
```
Dat is alles — het nummer is actief. Nadat uitgaand bellen is goedgekeurd voor je
organisatie, kun je ook `outbound_agent_id` instellen in dezelfde PATCH. Tot
die tijd wijst de API die toewijzing af met `400`.
Als je inkomende oproepen via een configuratiewebhook routeert in plaats van via een vaste
`inbound_agent_id`, kan die webhook nu per oproep een `timezone` retourneren,
samen met `agent_id` en `variables`.
## 4. Een oproep aannemen
Bel het nummer vanaf je telefoon. De agent neemt op, stelt zich voor
volgens je prompt en het gesprek begint.
Terwijl het gesprek bezig is, verschijnt het in
[`GET /v1/calls`](/api-reference/calls#list-calls) met
`status="in_progress"`. Wanneer het eindigt, wordt het record bijgewerkt met
`end_reason`, `duration_seconds`, `billable_minutes` en (uiteindelijk)
een opname-URL en AI-beoordeling.
Inkomende oproepen tellen mee voor de
[limiet voor gelijktijdige oproepen](/api-reference/introduction#call-limits) van je organisatie (standaard 20
oproepen tegelijk, gedeeld met uitgaande, web- en testoproepen). Een oproep die binnenkomt wanneer de limiet is bereikt, wordt geweigerd en opgehangen voordat de agent antwoordt, wordt niet gefactureerd en wordt geregistreerd als een mislukte oproep met als eindreden `concurrent_call_limit_reached`. Stuur een e-mail naar support@thunderphone.com als je
een hogere limiet nodig hebt.
## 5. Inspecteer de resultaten
Haal de lijst met recente oproepen op:
```bash
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Haal het transcript op:
```bash
curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
En de opname-URL (tijdelijk geldig, ondertekend):
```bash
curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Als je bent geabonneerd op de
[`telephony.complete`-webhook](/nl/webhooks/events),
ontvang je dezelfde gegevens als een POST naar je server — zie
[call.complete](/nl/webhooks/call-complete).
Als voor je agent extractievelden zijn geconfigureerd, kan de payload van de
voltooide oproep ook gestructureerde geëxtraheerde gegevens bevatten.
---
## Volgende stappen
Kies op basis van het telefoonnummer of aangepaste logica in een webhook
een andere agent per beller.
Laat de agent tijdens een gesprek je API's aanroepen.
Verbind bellers rechtstreeks door of doe een voorselectie van de bestemming voordat je ze verbindt.
Stream elke afgeronde oproep naar je CRM- of analysepipeline.
Beoordeel elke oproep automatisch en stuur gemarkeerde oproepen door voor beoordeling.