Voor ontwikkelaars
Bouw spraakagenten in je eigen software met de voice agent API
De Belvoy-app draait op dezelfde API die jij krijgt. Agents beheren, gesprekken starten en uitkomsten ophalen doe je net zo goed in code. Tijdens het gesprek roept de agent jouw API’s aan, en erna krijgt je systeem een ondertekende webhook. Je gebruikt je eigen sleutels bij de AI-aanbieders die je kiest.
De ontwikkelaarsdocumentatie gaat binnenkort openbaar. Tot dan krijg je toegang via de pilot.
Eén API
De app gebruikt dezelfde API als jij
Er zit geen afgeslankte integratielaag tussen. Een sleutel kan wat de app kan, binnen de scopes die je hem geeft.
-
REST-API
JSON, een OpenAPI 3.1-specificatie, cursor-paginering en een Idempotency-Key op alles wat een gesprek start. Sleutels per werkruimte met eigen scopes; testsleutels werken als live sleutels, maar worden niet gefactureerd.
-
Uitgaande gesprekken en batches
Eén gesprek of een hele lijst. Per gesprek geef je instructies, context, een openingszin en de velden die je terug wilt. Beltijden, opt-outlijst, voicemaildetectie en herhaalpogingen regelt Belvoy.
-
Webhooks
Volgens Standard Webhooks, ondertekend met HMAC: conversation.started, conversation.ended, conversation.analyzed, call.failed, batch.completed, task.completed en meer. Met herhaalpogingen en een afleverlog.
-
Tools voor de agent
De agent roept tijdens het gesprek je eigen HTTP-endpoints aan, met bearer-, basic-, API-key- of OAuth2-authenticatie, mTLS en ondertekende requests. Of importeer operaties uit je OpenAPI-specificatie.
-
MCP, beide kanten op
Koppel MCP-servers als tools voor je agent. En Belvoy heeft een eigen MCP-server, zodat een AI-assistent gesprekken kan starten, volgen en annuleren.
-
Connector achter je firewall
Voor systemen die niet aan het internet hangen. De connector draait in je eigen netwerk, legt zelf een versleutelde verbinding naar buiten en voert alleen de tools uit die jij configureert. Er hoeft geen poort open.
-
Webwidget
Eén script en één element op je pagina. De publiceerbare sleutel werkt alleen voor de agents die je kiest en vanaf de domeinen die je toestaat.
-
Session grants
Gaat het webgesprek over één klant, dan maakt je server met een geheime sleutel een session grant: instructies, context, variabelen, metadata en de velden die je terug wilt. De widget wisselt het eenmalige token in; de bezoeker kan niets aanpassen. Wil je alleen zulke gesprekken, zet dan Only with a session grant aan.
-
Checklists
Stuur een vragenlijst mee met een uitgaand gesprek, een batch of een session grant. De agent stelt de vragen één voor één en legt elk antwoord meteen vast, voorwaarden worden tussen de vragen gecontroleerd, en verplichte vragen houden het gesprek open, tenzij de ander wil stoppen. Daarna volgt checklist.completed of checklist.incomplete.
-
Privacyprofiel per werkruimte
Eén set regels voor alle agents: alleen aanbieders in de EU, geen opnames, transcripten volledig, gemaskeerd of niet bewaard, maximale bewaartermijnen en thin webhooks met alleen id’s en statussen. Een gesprek loopt altijd met de strengste instelling van profiel en agent.
-
Talen en vertalen
Een hoofdtaal en extra talen in language.primary en language.additional (BCP 47). Met extra talen detecteert de agent de taal van de beller en schakelt hij mee, en voice.languageVoices geeft elke taal een eigen stem. Met het standaardmodel zijn er 74 talen; de API waarschuwt als het gekozen model een taal niet ondersteunt. POST /v1/conversations/{id}/translations vertaalt een heel gesprek, /translations/snippets de beurten van een live gesprek.
-
SDK’s
Getypeerde SDK’s voor TypeScript en Python, gegenereerd uit de OpenAPI-specificatie, met helpers voor idempotency, paginering en het controleren van webhooks.
Voorbeeldcode
Van widget tot webhook, in echte code
Geen pseudocode: de routes, velden en events komen zo uit de API. Alleen de id’s en sleutels zijn ingekort.
De widget op je website
Maak de agent publiek, voeg je domein toe en maak een publiceerbare sleutel. Daarna plak je dit in je pagina.
<script src="https://app.dev.belvoy.nl/widget.js" async></script>
<belvoy-agent agent-id="agt_01K6…" publishable-key="bv_pub_…" lang="nl"></belvoy-agent> Een webgesprek over één klant
Je server maakt een session grant met de gegevens van deze klant en geeft het token aan de pagina. De widget wisselt het één keer in, binnen 5 minuten en alleen vanaf het opgegeven domein.
# On your server, with a secret key
curl https://app.dev.belvoy.nl/v1/session-grants \
-H "Authorization: Bearer $BELVOY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agentId": "agt_01K6…",
"allowedOrigins": ["https://www.example.nl"],
"instructions": "Help de klant met bestelling 1042. Die is maandag verzonden.",
"dynamicVariables": { "customer_name": "Sanne" },
"metadata": { "orderId": "1042" }
}'
# → { "id": "sgr_…", "token": "bv_grant_…", "expiresAt": "…" }
# On your page (the browser's own variables are ignored)
<belvoy-agent agent-id="agt_01K6…" publishable-key="bv_pub_…" session-grant="bv_grant_…" lang="nl"></belvoy-agent> Een uitgaand gesprek starten
Een herinnering met één vraag die terugkomt als gegevens. Dankzij de Idempotency-Key wordt hetzelfde gesprek nooit twee keer gebeld.
curl https://app.dev.belvoy.nl/v1/calls/outbound \
-H "Authorization: Bearer $BELVOY_API_KEY" \
-H "Idempotency-Key: reminder-4711" \
-H "Content-Type: application/json" \
-d '{
"agentId": "agt_01K6…",
"phoneNumberId": "pn_01K6…",
"to": "+31612345678",
"instructions": "Herinner {{customer_name}} aan de afspraak van donderdag 10:00 en vraag of die doorgaat.",
"dynamicVariables": { "customer_name": "Jan" },
"outcomeFields": [
{ "id": "confirmed", "type": "boolean", "description": "Komt de klant?" }
],
"metadata": { "appointmentId": "4711" }
}' De uitkomst ontvangen
Na de analyse stuurt Belvoy conversation.analyzed. Controleer de handtekening op de ruwe body, met de officiële Standard Webhooks-bibliotheek.
import os
from standardwebhooks import Webhook
wh = Webhook(os.environ["BELVOY_WEBHOOK_SECRET"]) # whsec_…
def handle(raw_body: bytes, headers: dict) -> None:
event = wh.verify(raw_body, headers) # controleert handtekening en tijdstempel
if event["type"] == "conversation.analyzed":
conversation = event["data"]["conversation"]
print(conversation["id"], conversation["analysis"]["summary"]) Een tool-aanroep naar je eigen endpoint
Een HTTP-tool ‘beschikbaarheid_controleren’ met twee argumenten. Met ondertekende requests controleer je dat de aanroep echt van Belvoy komt.
POST /beschikbaarheid HTTP/1.1
Host: api.example.nl
Content-Type: application/json
webhook-id: msg_…
webhook-timestamp: 1791100800
webhook-signature: v1,…
{"datum": "2026-10-10", "personen": 4} Zo werkt het
Van sleutel tot uitkomst
-
Maak een API-sleutel
In de app onder Settings → API keys, met alleen de scopes die je nodig hebt.
-
Zet een agent neer
In de app of via de API, vanuit een sjabloon. Koppel een nummer bij Telnyx of Twilio.
-
Laat hem bellen
Eén voor één, als batch of via de widget. Elk gesprek met een eigen opdracht.
-
Ontvang de uitkomst
Transcript, samenvatting en je eigen velden komen via een webhook binnen, of je haalt ze op met de API.
Eigen sleutels
Gebruik je eigen AI- en telefonieaanbieders
Koppel je eigen accounts en betaal de aanbieders rechtstreeks, tegen hun eigen tarief. Per agent kies je de combinatie, en wissel je één onderdeel zonder de rest om te bouwen.
- Spraak-naar-spraak
- ElevenLabs AgentsOpenAI RealtimeGemini Live
- Spraakherkenning
- DeepgramSonioxElevenLabsOpenAI
- Taalmodellen
- OpenAIAnthropic ClaudeGoogle Gemini
- Stemmen
- ElevenLabsCartesiaAzure AI SpeechOpenAI
- Telefonie
- TelnyxTwilio
Vertel wat je bouwt
Beschrijf wat je wilt maken. We nemen contact op over toegang tot de pilot en de API.
Vraag API-toegang aanMailen mag ook: hello@belvoy.nl