Naar de inhoud
belvoy
English
Menu
Vraag toegang aan

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.

Vraag API-toegang aan Bekijk de code

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.

  • 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 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

  1. Maak een API-sleutel

    In de app onder Settings → API keys, met alleen de scopes die je nodig hebt.

  2. Zet een agent neer

    In de app of via de API, vanuit een sjabloon. Koppel een nummer bij Telnyx of Twilio.

  3. Laat hem bellen

    Eén voor één, als batch of via de widget. Elk gesprek met een eigen opdracht.

  4. 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 aan

Mailen mag ook: hello@belvoy.nl