So you’ve read about Voice Nexus Service (VNS) and you’re ready to build. This article gives you a technical overview of how VNS works under the hood — the webhook lifecycle, the CallStart response structure, tool integration, and how outbound calls are initiated. Think of this as your orientation before diving into the full Developer Guide.
For an introductory overview of the Voice Nexus Service, please see Introducing Voice Nexus Service.
Voice Nexus Service — Developer Overview
How VNS Fits Into Your Stack
VNS sits between the Voice Elements Cloud Platform and your own application logic. Here’s the call flow from end to end:
- An inbound call (or browser-based WebRTC session) enters the Voice Elements environment
- Voice Elements routes the call to Voice Nexus Service
- VNS calls your CallStart webhook to retrieve per-call instructions
- VNS establishes a WebSocket session with OpenAI Realtime using those instructions
- During the call, the AI can invoke your tools or MCP-connected systems in real time
- When the call ends, VNS calls your CallEnd webhook with call statistics, logs, and optional transcription
Your webhook endpoints are the control center. You define what the AI knows, what it can do, and how it handles edge cases — on a per-call basis, without redeployment.
The CallStart Webhook
When a call arrives, VNS performs an HTTP POST to your configured CallStart endpoint. The request body includes key session data:
- sessionGuid — unique identifier for the voice session
- calledNumber — the DID that received the call
- callerId and callerIdName — the originating number and display name
- outboundTriggered — indicates whether the session was initiated as an outbound VNS call
- customerCallId — an optional identifier your system can supply to track the session across your own records
Your endpoint must respond with a JSON object containing a VoiceElements_Instructions block and a session block that defines the OpenAI Realtime session configuration.
The CallStart Response
The CallStart response is the heart of how you configure each AI session. Key fields include:
- aiUrl — the OpenAI Realtime WebSocket URL and your API key in the Authorization header
- maxSeconds — the maximum call duration in seconds
- defaultToolsUrlBase — the endpoint VNS calls when the AI invokes a function, along with any authentication headers
- defaultToolsUrlAdapter — controls how session metadata (session GUID, tool name, customer call ID) is injected into tool requests — either in the request body or via URL path and query string patterns
- routeToNumberOnFailure — a fallback number to transfer the caller to if the AI session can’t be established
- logToolCallRequests / logToolCallReplies / logTranscription — optional logging flags; logs are delivered in the CallEnd webhook payload
- recordCall — enables call recording; see the VNS Resources section for how to retrieve recordings
The session block passes directly to OpenAI and defines the AI model, voice, audio format, turn detection settings, and the instructions string that drives the agent’s personality and behavior. This is also where you define the tools array — the functions the AI is permitted to call during the conversation.
Built-in VNS Tools
VNS ships with four built-in tools that are resolved internally — no server endpoint required on your side. Simply include them in your tools array:
- vns_end_conversation — gracefully terminates the session when the caller indicates they want to hang up
- vns_transfer_call — transfers the active call to another number; supports both blind and attended (warm) transfers. The transfer number is never spoken or revealed to the caller
- vns_get_call_info — returns session metadata (caller ID, called number, session GUID, call start time) without requiring you to hard-code it into your instructions
- vns_get_utc_datetime — returns the current UTC date and time; useful for scheduling or logging scenarios
Tool Execution — Your Custom Functions
When the AI triggers one of your custom functions during a live call, VNS augments the payload with session metadata and POSTs it to your tool endpoint. Your endpoint returns any JSON object, and VNS feeds the result directly back into the AI session so the model can use it in the ongoing conversation — all without interrupting the call.
Outbound Calls
To initiate an outbound AI call, POST to the VNS Outbound Call API at https://vnsapi.voiceelements.com/api/customer/vnsoutboundcall with the destination number, caller ID number, caller ID name, and an optional customer call ID. VNS returns a session token, then fires the CallStart webhook and proceeds exactly like an inbound call from that point forward.
All VNS API requests require your API key in a Token header. See the API Authentication Guide for details.
The CallEnd Webhook
When the call ends, VNS POSTs a summary to your CallEnd endpoint. The payload includes call timestamps, status, transfer records, and — if enabled — tool call logs and a full line-by-line transcription with timestamps and speaker identification. Respond with {“status”: 0, “errorMessage”: “Success”} to acknowledge receipt.
Getting Set Up
Before you start testing:
- Make sure you have an OpenAI API Platform account with billing enabled and access to the Realtime voice models — see the OpenAI Account Setup Guide
- Sign in or create your account at vnsportal.voiceelements.com and confirm your account is production-enabled
- Email support@inventivelabs.com with the DID you want to connect to VNS, your CallStart and CallEnd webhook URLs, and your authentication method and credentials
From there, the team will complete the setup on the VNS side and you’ll be ready to test.
Ready to Go Deeper?
The full VNS Developer Guide includes complete field references, JSON examples for every webhook, all URL adapter patterns, and the full built-in tool definitions with example instruction strings. That’s your go-to reference once you’re building.