Developer Guide

Complete reference for integrating Voice Nexus Service (VNS) into your stack.

Overview

Voice Nexus Service (VNS) allows you to connect a telephone number to an AI voice workflow using OpenAI Realtime voice models such as gpt-realtime and gpt-realtime-mini. VNS sits between the Voice Elements Cloud Platform and your customer-defined AI logic, making it possible to define instructions, invoke functions, and integrate with external systems during an active voice session.

  • Inbound AI voice handling — Connect numbers and WebRTC sessions to realtime AI agents.
  • Webhook-driven call setup — Your endpoint controls per-call instructions and billing context.
  • Function and MCP integration — Allow the AI agent to access scheduling, CRM, and business systems.
  • Outbound session support — Initiate outbound calls using the VNS API and a returned session token.

Architecture

1

Carrier or WebRTC

An inbound call or browser-based session enters the Voice Elements environment.

2

Voice Elements Cloud Platform

Routes the call to Voice Nexus Service.

3

Voice Nexus Service (VNS)

Calls your webhooks, establishes the realtime AI session, and brokers tool execution.

4

OpenAI Realtime Voice

Handles the live conversational AI session.

5

Your APIs / Tools / MCP Servers

Provide business logic such as scheduling, lookups, and human escalation.

Quick Start

  1. Create an account on the Voice Nexus Service Portal.
  2. Create API Tokens for outbound API access and for authenticating your webhooks.
  3. Provision or port a phone number.
  4. Configure your CallStart and CallEnd webhook URLs and authentication.
  5. Test your webhooks, then make a live call.

Inbound Calls

  1. CallStart webhook — VNS sends a CallStart webhook to the endpoint defined for the DID.
  2. Instruction retrieval — Your endpoint returns JSON describing how the call should be handled.
  3. Realtime session — VNS establishes a WebSocket session with OpenAI Realtime and supplies the returned instructions.
  4. Tool execution — During the session the AI agent can invoke tools or MCP-connected systems.
  5. Call control — Transfers and other call control actions can be made available as tools.
  6. CallEnd webhook — At the end of the call VNS sends a CallEnd webhook containing call statistics.

Outbound Calls

  1. Dial request — Send a request to the VNS Web API containing the destination number, caller ID number, and caller ID name.
  2. Session creation — VNS returns a session token or call ID.
  3. CallStart webhook — VNS sends the CallStart webhook with the session token and marks the call as outbound initiated.
  4. Call placement — VNS dials the phone number and the session proceeds like an inbound AI call.
  5. Termination — When the call ends the CallEnd webhook is executed.

CallStart Webhook

VNS performs an HTTP POST to your configured CallStart endpoint at the start of each call.

Request Body

{
  "sessionGuid": "9e6a9d8e-6a92-4b3f-9a2c-1c63c1f3a8f1",
  "calledNumber": "7206999999",
  "callerId": "3032639999",
  "callerIdName": "John Smith",
  "outboundTriggered": false,
  "softwareVersion": "1.0.0.0",
  "callStart": "2026-03-12T10:42:15Z",
  "customerCallId" : "Cust-001-12345"
}

Request Fields

Field Type Description
sessionGuidstringUnique identifier for the voice session.
calledNumberstringThe DID that received the inbound call.
callerIdstringThe originating phone number.
callerIdNamestringCaller display name, when available.
outboundTriggeredbooleanIndicates whether the call was initiated as an outbound VNS session.
softwareVersionstringVoice Nexus software version for the current runtime.
callStartdatetimeUTC timestamp when the call began.
customerCallIdstring | nullOptional customer-supplied call identifier associated with the session.

CallStart Response

Your CallStart endpoint must return the instructions and session configuration that will be applied to the OpenAI Realtime session.

Required VoiceElements_Instructions Fields

  • aiUrl.url — The OpenAI Realtime WebSocket URL, including the model name (e.g., gpt-realtime or gpt-realtime-mini).
  • aiUrl.headers — HTTP headers sent to the OpenAI endpoint. Include Authorization: Bearer YOUR_API_KEY here.
  • maxSeconds — Maximum number of seconds the call may remain connected.
  • customerCallId — Optional identifier your system assigns to the session. Echoed back in all webhooks and tool payloads.
  • defaultToolsUrlBase.url — The endpoint VNS calls when the AI invokes a function.
  • defaultToolsUrlBase.headers — HTTP headers sent with every tool call request (e.g., Token or Authorization).
  • defaultToolsUrlAdapter — Controls how session metadata is injected into tool requests. See URL Adapter Patterns.
  • routeToNumberOnFailure — Phone number to transfer the caller to if the AI session cannot be established. Set to null to hang up instead.
  • messageToPlayOnFailure — Message played to the caller before routing or hanging up on failure.
  • logToolCallRequests — When true, VNS logs each tool invocation request payload. The logs are delivered in the CallEnd Request.
  • logToolCallReplies — When true, VNS logs each tool reply payload. The logs are delivered in the CallEnd Request.
  • logTranscription — When true, VNS logs a full call transcription. The logs are delivered in the CallEnd Request.
  • recordCall — When true, VNS records the call audio. See article under Resources to learn how to retrieve the recording.
  • recordCallFormat — Audio format for the recording (e.g., opus).
  • recordCallPassword — Optional password if you wish the recording to be encrypted.
  • transcriptionToolName — If set, VNS delivers the transcription to this tool endpoint realtime phrase by phrase.

Response Body Example

{
    "VoiceElements_Instructions": {
        "aiUrl": {
            "url": "wss://api.openai.com/v1/realtime?model=gpt-realtime",
            "headers": {
                "Authorization": "Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
            }
        },
        "maxSeconds": 300,
        "customerCallId": "CallId-001",
        "defaultToolsUrlBase": {
            "url": "https://ivlresttest.voiceelements.com/v1/aitool",
            "headers": {
                "Token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
            }
        },
        "defaultToolsUrlAdapter": null,
        "routeToNumberOnFailure": null,
        "messageToPlayOnFailure": "The AI system is currently offline.  Please Call back later",
        "logToolCallRequests": false,
        "logToolCallReplies": false,
        "logTranscription": false,
        "recordCall": false,
        "recordCallFormat" : "opus",
        "recordCallPassword" : "YourPassword",
        "transcriptionToolName" : "your_custom_tool_name_for_transcriptions"
    },
    "event_id": "start_1",
    "type": "session.update",
    "session": {
        "type": "realtime",
        "instructions": "You are a friendly agent. Explain that you can look up a name by a phone number or a phone number by a name.  If the user gives you a phone number or name, call the function lookup_name_or_phone with passing the appropriate parameter.  Read back to the user what was returned and ask them if they wish to look up another or end the call.  The call can be concluded by calling the vns_end_conversation tool.",
        "model": "gpt-realtime",
        "audio": {
            "input": {
                "format": {
                    "type": "audio/pcmu"
                },
                "transcription": {
                    "model": "whisper-1"
                },
                "turn_detection": {
                    "type": "server_vad",
                    "threshold": 0.65,
                    "prefix_padding_ms": 300,
                    "silence_duration_ms": 300,
                    "create_response": true,
                    "interrupt_response": true,
                    "idle_timeout_ms": 30000
                },
                "noise_reduction": null
            },
            "output": {
                "format": {
                    "type": "audio/pcmu"
                },
                "voice": "alloy"
            }
        },
        "tool_choice": "auto",
        "tools": [
			{
				"name": "vns_end_conversation",
				"description": "If the user says something about ending the conversation, like goodbye, call this function to let the application know.",
				"type": "function",
				"parameters": {
				  "type": "object",
				  "properties": {
					"user_input": {
					  "type": "string",
					  "description": "Input from the user indicating they want to end the conversation."
					  },
					"farewell": {
					  "type": "string",
					  "description": "The farewell you would like to say to the caller.  If omitted this defaults to a simple goodbye."
					  }
				  },
				  "required": [ "user_input"  ]
				}
			},		
            {
                "name": "vns_get_call_info",
                "description": "Call this function to get information about the Called Number, Caller Id, Caller Id Name, the Call Start Time (UTC), If the call was inbound or outbound and the SessionGuid and CustomerCall Id.",
                "type": "function",
                "parameters": {
                    "type": "object",
                    "properties": {}
                }
            },
            {
                "name": "vns_get_utc_datetime",
                "description": "Retrieves the current UTC date and time.",
                "type": "function",
                "parameters": {
                    "type": "object",
                    "properties": {}
                }
            },
            {
                "name": "vns_transfer_call",
                "description": "Transfers the current call to another number.",
                "type": "function",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "transferNumber": {
                            "type": "string",
                            "description": "The phone number to transfer the call to, preferably in E.164 format like +13035551212"
                        },
                        "useVnsNumberAsCallerId": {
                            "type": "boolean",
                            "description": "If true, uses the Called Number as the outbound caller ID for the transferred call, otherwise it uses the callers number."
                        },
                        "attended": {
                            "type": "boolean",
                            "description": "If true, performs an attended transfer where the agent speaks to the destination before completing the transfer."
                        }
                    },
                    "required": [
                        "transferNumber"
                    ]
                }
            },
            {
                "name": "lookup_name_or_phone",
                "description": "A example customer specific tool that looks up the name of a person from a phone number or looks up the phone number of a person from a name.",
                "type": "function",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "name": {
                            "type": "string",
                            "description": "Name of the person to search for."
                        },
                        "phoneNumber": {
                            "type": "string",
                            "description": "Phone number to search, preferably in E.164 format like +13035551212"
                        }
                    }
                }
            }
        ]
    }
}

Tool Execution

During an active AI session, when the model triggers a function, VNS augments the payload with metadata before forwarding the request to your webhook.

Tool Request Payload

{
  "name": "Ron"
}

Tool Request Payload with Session Info

When defaultToolsUrlAdapter is null in your CallStart response, VNS includes a VoiceElements_InvokeTool block in the tool payload. Your endpoint can use these fields to maintain state or correlate tool calls back to a specific session.

{
  "VoiceElements_InvokeTool": {
    "toolName": "lookup_name_or_phone",
    "sessionGuid": "SOME SESSION GUID",
    "customerCallId": "CallId-001"
  },
  "name": "Ron"
}

Tool Reply

Your endpoint returns any JSON object. VNS feeds the result directly back into the AI session so the model can use it in the ongoing conversation.

{
  "matchType": "name",
  "contactFound": true,
  "contactName": "Ron Tanner",
  "phoneNumber": "+13035551212"
}

URL Adapter Patterns

Set defaultToolsUrlAdapter in your CallStart response to route metadata via URL path or query string instead of the request body. When set to null, the session ID, tool name, and customer call ID are included in the body.

Variations for the defaultToolsUrlAdapter json

"defaultToolsUrlAdapter" : null
"defaultToolsUrlAdapter" : "/<<sessionguid>>/<<toolname>>/<<customerCallId>>"
"defaultToolsUrlAdapter" : "/<<toolname>>/<<sessionguid>>/<<customerCallId>>"
"defaultToolsUrlAdapter" : "/<<toolname>>"
"defaultToolsUrlAdapter" : "/<<toolname>>/<<customerCallId>>"
"defaultToolsUrlAdapter" : "?toolname=<<toolname>>&sessionguid=<<sessionguid>>&customerCallId=<<customerCallId>>"
"defaultToolsUrlAdapter" : "?toolname=<<toolname>>&sessionguid=<<sessionguid>>"

If the defaultToolsUrlAdapter is null then the session id, tool name and customer call id is include in the body.

Built-in VNS Tools

VNS ships with four built-in tools that are handled entirely inside Voice Nexus Service — no webhook endpoint is required on your server. When the AI model invokes one of these tools, VNS intercepts the call and responds directly. Include any you need in the tools array of your CallStart response.

vns_end_conversation

Gracefully terminates the voice session when the caller is ready to hang up.

vns_transfer_call

Transfers the active call to another phone number via blind or attended transfer.

vns_get_call_info

Returns caller ID, called number, session ID, and call start time.

vns_get_utc_datetime

Returns the current UTC date and time for scheduling and logging.

For complete tool schemas, parameter definitions, and example instructions, see the Built-in VNS Tools reference →

CallEnd Webhook

VNS performs an HTTP POST to your configured CallEnd endpoint after the call completes. Respond with {"status": 0, "errorMessage": "Success"} to acknowledge.

Request Body Example

{
  "sessionGuid": "164ff386-b1b4-4521-97e4-440ca6b3b5c8",
  "callStart": "2026-03-20T02:43:39.6521589Z",
  "callConnected": "2026-03-20T02:43:40.4786233Z",
  "callEnd": "2026-03-20T02:44:45.8626633Z",
  "calledNumber": "7206999209",
  "callerId": "7205551212",
  "callerIdName": "Jane Doe",
  "status": 0,
  "errorMessage": "No Errors",
  "outboundTriggered": false,
  "outboundCallResult": "N/A",
  "customerCallId": "CallId-001",
  "callReferredOut": false,
  "transfers": [
    {
      "transferCalledNumber": "+13035551212",
      "transferCallerId": "+13035559999",
      "transferCallerIdName": "Business Name",
      "transferCallStart": "2026-04-17T16:26:33.2178764Z",
      "transferCallEnd": "2026-04-17T16:26:46.8679023Z",
      "transferCallResult": "Connected"
    }
  ],
  "logInformation": [
    "26/04/17 - 10:26:12.560 - Logging Started.",
  ],
  "transcription": [
    "2026-04-17 10:26:20.046 AI  : Hello! How can I help you today?",
    "2026-04-17 10:26:21.952 User: Bye.",
  ]
}

Request Fields

Field Type Description
sessionGuidstringUnique identifier for the voice session.
callStartdatetimeUTC timestamp when the call began.
callConnecteddatetime | nullUTC timestamp when the call connected, if answered.
callEnddatetimeUTC timestamp when the call ended.
calledNumberstringDID used for the call.
callerIdstringOriginating or remote party number.
callerIdNamestring | nullCaller display name, when available.
statusintegerCall completion status code.
errorMessagestring | nullError detail or status text.
outboundTriggeredbooleanWhether the session originated from an outbound-triggered call.
outboundCallResultstring | nullResult status of the outbound call; "N/A" for inbound sessions.
customerCallIdstring | nullCustomer-supplied call identifier carried through the session.
callReferredOutbooleanWhether the call was referred or transferred out.
transfersarray | nullTransfer records, if any occurred. Each entry includes transferCalledNumber, transferCallerId, transferCallerIdName, transferCallStart, transferCallEnd, and transferCallResult.
logInformationarray | nullArray of formatted diagnostic log strings. Present when call logging is active.
transcriptionarray | nullArray of formatted strings in the form "timestamp Speaker: text". Present when logTranscription is enabled.

Acknowledgement Response

{
  "status": 0,
  "errorMessage": "Success"
}

Outbound Call API

This endpoint allows your system to initiate an outbound call through Voice Nexus Service.

Authentication required: All VNS API requests must include your API key in a Token header. See the API Authentication Guide → for details on obtaining and using your key.

Request

{
    "customerCallId": "abc123",
    "calledNumber": "3032639999",
    "callerId": "7206999999",
    "callerIdName": "John Smith"
}

Response

{
    "status": 0,
    "errorMessage": "Success"
}

Initial Setup

OpenAI Prerequisite: Before testing, ensure you have a properly configured OpenAI API Platform account with billing enabled and access to the Realtime voice models. See the OpenAI Account Setup Guide →
  1. Create an account on the Voice Nexus Service Portal.
  2. Create API Tokens. There are two types:
    • VNS Services Access — tokens used when calling https://vnsapi.voiceelements.com for outbound calls, retrieving recordings, or SMS services.
    • Your API Tokens — tokens that VNS uses when calling your webhooks, such as the CallStart webhook.
  3. Provision a new phone number, or ask us to port an existing number into our system.
  4. Add URLs and authentication to your CallStart and CallEnd webhooks.
  5. Press the Test button on your webhooks to verify they respond correctly.
  6. Test by calling the phone number.

Ready to Automate Your Phone Lines?

See Voice Nexus in action. Book a live demo with our team and we'll walk you through setup, integrations, and pricing.

Book a Demo Contact Sales