For developers
Build voice agents into your own software with the voice agent API
The Belvoy app runs on the same API you get. Managing agents, starting calls and fetching outcomes all work in code too. During the call the agent calls your APIs, and afterwards your system gets a signed webhook. You use your own keys with the AI providers you choose.
The developer documentation goes public soon. Until then, access comes with the pilot.
One API
The app uses the same API you do
There’s no cut-down integration layer in between. A key can do what the app does, within the scopes you give it.
-
REST API
JSON, an OpenAPI 3.1 spec, cursor pagination and an Idempotency-Key on everything that starts a call. Keys per workspace with their own scopes; test keys behave like live keys but are never billed.
-
Outbound calls and batches
One call or a whole list. Per call you pass instructions, context, an opening line and the fields you want back. Belvoy handles calling hours, the opt-out list, voicemail detection and retries.
-
Webhooks
Standard Webhooks, signed with HMAC: conversation.started, conversation.ended, conversation.analyzed, call.failed, batch.completed, task.completed and more. With retries and a delivery log.
-
Tools for the agent
The agent calls your own HTTP endpoints mid-conversation, with bearer, basic, API key or OAuth2 auth, mTLS and signed requests. Or import operations from your OpenAPI spec.
-
MCP, both ways
Connect MCP servers as tools for your agent. And Belvoy has an MCP server of its own, so an AI assistant can start, follow and cancel calls.
-
A connector behind your firewall
For systems that aren’t on the internet. The connector runs in your own network, opens an encrypted connection outwards and only runs the tools you configure. No inbound port needed.
-
Web widget
One script and one element on your page. The publishable key only works for the agents you choose and from the domains you allow.
-
Session grants
When a web call is about one customer, your server creates a session grant with a secret key: instructions, context, variables, metadata and the fields you want back. The widget redeems the single-use token, and the visitor cannot change any of it. To allow only these calls, switch on Only with a session grant.
-
Checklists
Send a list of questions with an outbound call, a batch or a session grant. The agent asks them one at a time and records each answer as it is given, conditions are checked between questions, and required questions keep the call going unless the person wants to stop. Afterwards you get checklist.completed or checklist.incomplete.
-
Workspace privacy profile
One set of rules for every agent: EU providers only, no recordings, transcripts full, redacted or not kept, maximum retention periods, and thin webhooks with ids and statuses only. A call always runs with the stricter of the profile and the agent.
-
Languages and translation
A main language and extra languages in language.primary and language.additional (BCP 47). With extra languages the agent detects the caller’s language and switches, and voice.languageVoices gives each language its own voice. The default model has 74 languages; the API warns when the chosen model doesn’t support one. POST /v1/conversations/{id}/translations translates a whole call, /translations/snippets the turns of a live one.
-
SDKs
Typed SDKs for TypeScript and Python, generated from the OpenAPI spec, with helpers for idempotency, pagination and verifying webhooks.
Sample code
From widget to webhook, in real code
No pseudocode: the routes, fields and events come straight from the API. Only the ids and keys are shortened.
The widget on your website
Make the agent public, add your domain and create a publishable key. Then paste this into your page.
<script src="https://app.dev.belvoy.nl/widget.js" async></script>
<belvoy-agent agent-id="agt_01K6…" publishable-key="bv_pub_…" lang="en"></belvoy-agent> A web call about one customer
Your server creates a session grant with this customer’s details and hands the token to the page. The widget redeems it once, within 5 minutes and only from the origin you named.
# 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 the customer with order 1042. It shipped on Monday.",
"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="en"></belvoy-agent> Start an outbound call
A reminder with one question that comes back as data. Thanks to the Idempotency-Key, the same call is never dialled twice.
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": "Remind {{customer_name}} of Thursday’s 10:00 appointment and ask whether it is still on.",
"dynamicVariables": { "customer_name": "Jan" },
"outcomeFields": [
{ "id": "confirmed", "type": "boolean", "description": "Is the customer coming?" }
],
"metadata": { "appointmentId": "4711" }
}' Receive the outcome
After the analysis Belvoy sends conversation.analyzed. Verify the signature on the raw body with the official Standard Webhooks library.
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) # checks the signature and timestamp
if event["type"] == "conversation.analyzed":
conversation = event["data"]["conversation"]
print(conversation["id"], conversation["analysis"]["summary"]) A tool call to your own endpoint
An HTTP tool ‘check_availability’ with two arguments. Signed requests let you check that the call really comes from Belvoy.
POST /availability HTTP/1.1
Host: api.example.nl
Content-Type: application/json
webhook-id: msg_…
webhook-timestamp: 1791100800
webhook-signature: v1,…
{"date": "2026-10-10", "party_size": 4} How it works
From key to outcome
-
Create an API key
In the app under Settings → API keys, with only the scopes you need.
-
Set up an agent
In the app or through the API, from a template. Connect a number at Telnyx or Twilio.
-
Let it call
One at a time, as a batch or through the widget. Each call with its own brief.
-
Receive the outcome
Transcript, summary and your own fields arrive by webhook, or you fetch them through the API.
Bring your own keys
Use your own AI and telephony providers
Connect your own accounts and pay the providers directly, at their own rates. Per agent you choose the combination, and you can swap one part without rebuilding the rest.
- Speech-to-speech
- ElevenLabs AgentsOpenAI RealtimeGemini Live
- Speech recognition
- DeepgramSonioxElevenLabsOpenAI
- Language models
- OpenAIAnthropic ClaudeGoogle Gemini
- Voices
- ElevenLabsCartesiaAzure AI SpeechOpenAI
- Telephony
- TelnyxTwilio
Tell us what you’re building
Describe what you have in mind and we’ll get in touch about access to the pilot and the API.
Request API accessPrefer email? hello@belvoy.nl