Developer Guide

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

Carrier or WebRTC

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

Voice Elements Cloud Platform

Routes the call to Voice Nexus Service.

Voice Nexus Service (VNS)

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

OpenAI Realtime Voice

Handles the live conversational AI session.

Your APIs / Tools / MCP Servers

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

Quick Start

Create or sign in to your account at customer.voiceelements.com.
Navigate to Settings / DIDs to view your phone numbers.
Select the DID to connect to VNS.
Provide your CallStart and CallEnd webhook URLs to the VNS team.
Return per-call instructions from your CallStart endpoint.
Calls to the DID are now routed through VNS into your AI voice flow.

Inbound Calls

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

Outbound Calls

Dial request — Send a request to the VNS Web API containing the destination number, caller ID number, and caller ID name.
Session creation — VNS returns a session token or call ID.
CallStart webhook — VNS sends the CallStart webhook with the session token and marks the call as outbound initiated.
Call placement — VNS dials the phone number and the session proceeds like an inbound AI call.
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": "B7E60598-0729-4410-922F-3A83DF863BFD",
  "calledNumber": "+13035551212",
  "callerId": "+13035559999",
  "callerIdName": "Business Name",
  "outboundTriggered": false,
  "softwareVersion": "1.0.0",
  "callStart": "2026-04-16T03:35:59.8593832Z",
  "customerCallId": null
}

Request Fields

Field	Type	Description
sessionGuid	string	Unique identifier for the voice session.
calledNumber	string	The DID that received the inbound call.
callerId	string	The originating phone number.
callerIdName	string	Caller display name, when available.
outboundTriggered	boolean	Indicates whether the call was initiated as an outbound VNS session.
softwareVersion	string	Voice Nexus software version for the current runtime.
callStart	datetime	UTC timestamp when the call began.
customerCallId	string \| null	Optional 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 a 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."
                        }
                    },
                    "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

{
  "VoiceElements_InvokeTool": {
    "toolName": "lookup_name_or_phone",
    "sessionGuid": "B7E60598-0729-4410-922F-3A83DF863BFD",
    "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.

// null — metadata stays in the request body (default)
"defaultToolsUrlAdapter": null

// Path patterns
"defaultToolsUrlAdapter": "/<<sessionguid>>/<<toolname>>/<<customerCallId>>"
"defaultToolsUrlAdapter": "/<<toolname>>/<<sessionguid>>/<<customerCallId>>"
"defaultToolsUrlAdapter": "/<<toolname>>"
"defaultToolsUrlAdapter": "/<<toolname>>/<<customerCallId>>"

// Query string patterns
"defaultToolsUrlAdapter": "?toolname=<<toolname>>&sessionguid=<<sessionguid>>&customerCallId=<<customerCallId>>"
"defaultToolsUrlAdapter": "?toolname=<<toolname>>&sessionguid=<<sessionguid>>"

Built-in VNS Tools

VNS provides built-in tools that are resolved internally — no webhook endpoint is required on your server. Include them in the tools array of your CallStart response.

vns_end_conversation

Signals that the conversation is complete. VNS gracefully terminates the session. Call this when the caller indicates they want to hang up.

{
  "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."
      }
    },
    "required": ["user_input"]
  }
}

Example instruction to include in your instructions string:

## END CALL
If the caller is finished and indicates he wants to hang up, thank the caller and call vns_end_conversation.

vns_transfer_call

Transfers the active call to another phone number. Supports blind and attended (warm) transfers. The transfer number is never spoken or revealed to the caller.

{
  "name": "vns_transfer_call",
  "description": "Transfer the call.",
  "type": "function",
  "parameters": {
    "type": "object",
    "properties": {
      "transferNumber": {
        "type": "string",
        "description": "Phone number to transfer to, preferably in E.164 format like +13035551212"
      },
      "useVnsNumberAsCallerId": {
        "type": "boolean",
        "description": "When true, the VNS DID is used as the caller ID for the transferred call instead of the original caller's number."
      },
      "attended": {
        "type": "boolean",
        "description": "When true, performs an attended (warm) transfer. When false, performs a blind transfer."
      }
    },
    "required": ["transferNumber"]
  }
}

Example instruction to include in your instructions string:

If the user asks to transfer to a live person, call vns_transfer_call passing +17203333333 as the transferNumber.
Under no circumstances will you give this number +17203333333 to the person you are speaking to.
To end the call, if requested, call vns_end_conversation.

vns_get_call_info

Returns metadata about the current call session without hard-coding it into your instructions.

{
  "name": "vns_get_call_info",
  "description": "Returns information about the current call, including the caller ID, called number, session ID, and call start time.",
  "type": "function",
  "parameters": { "type": "object", "properties": {} }
}

Example response fed back to the AI:

{
  "sessionGuid": "B7E60598-0729-4410-922F-3A83DF863BFD",
  "calledNumber": "+13035551212",
  "callerId": "+13035559999",
  "callerIdName": "Business Name",
  "outboundTriggered": false,
  "callStart": "2026-04-16T03:35:59.8593832Z",
  "customerCallId": "8ADD2CC6-BB94-4C5F-BD1D-DBDF91D39052"
}

vns_get_utc_datetime

Returns the current UTC date and time. Useful when the AI needs the current time for scheduling or logging.

{
  "name": "vns_get_utc_datetime",
  "description": "Returns the current UTC date and time.",
  "type": "function",
  "parameters": { "type": "object", "properties": {} }
}

Example response:

{ "current_time_utc": "2026-04-16T03:35:59.8593832Z" }

Note: vns_end_conversation, vns_get_call_info, vns_get_utc_datetime, and vns_transfer_call are all resolved internally by VNS. No tool webhook call is made to your server for these tools.

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
sessionGuid	string	Unique identifier for the voice session.
callStart	datetime	UTC timestamp when the call began.
callConnected	datetime \| null	UTC timestamp when the call connected, if answered.
callEnd	datetime	UTC timestamp when the call ended.
calledNumber	string	DID used for the call.
callerId	string	Originating or remote party number.
callerIdName	string \| null	Caller display name, when available.
status	integer	Call completion status code.
errorMessage	string \| null	Error detail or status text.
outboundTriggered	boolean	Whether the session originated from an outbound-triggered call.
outboundCallResult	object \| null	Optional outbound call result details.
customerCallId	string \| null	Customer-supplied call identifier carried through the session.
callReferredOut	boolean	Whether the call was referred or transferred out.
transfers	array \| null	Transfer records, if any occurred.
logInformation	array \| null	Optional diagnostic or summary logging data.
transcription	array \| null	Line-by-line call transcription entries (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

POST https://vnsapi.voiceelements.com/api/customer/vnsoutboundcall

{
  "customerCallId": "abc123",
  "calledNumber": "+13032639999",
  "callerId": "+17206999999",
  "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 →

Sign in or create a new account at customer.voiceelements.com.
Navigate to Settings / DIDs to view your phone numbers.
If your account is not yet production-enabled, your DID cannot be pointed to VNS. To convert to production, schedule a meeting.
Email support@inventivelabs.com with:
- The DID to connect to VNS
- The CallStart webhook URL
- The CallEnd webhook URL
- The authentication method for both webhooks
- The required authentication token or credentials
After support completes setup, your service will be enabled for testing and production use.

Overview

Architecture

Quick Start

Inbound Calls

Outbound Calls

CallStart Webhook

Request Body

Request Fields

CallStart Response

Required VoiceElements_Instructions Fields

Response Body Example

Tool Execution

Tool Request Payload

Tool Reply

URL Adapter Patterns

Built-in VNS Tools

vns_end_conversation

vns_transfer_call

vns_get_call_info

vns_get_utc_datetime

CallEnd Webhook

Request Body Example

Request Fields

Acknowledgement Response

Outbound Call API

Request

Response

Initial Setup

Ready to Automate Your Phone Lines?

Required `VoiceElements_Instructions` Fields