Voice Nexus Service (VNS)

Overview

Voice Nexus Service (VNS) allows a customer 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 the customer-defined AI logic, making it possible to define instructions, invoke functions, and integrate with external systems during an active voice session.

Quick Start

1. Create or sign in to your account
   Use the Voice Elements customer portal to manage your DIDs and service configuration.
2. Identify the DID to connect to VNS
   Select the number that should route to your AI voice agent.
3. Provide your CallStart and CallEnd webhook URLs
   These endpoints will be called by VNS at call start and call completion.
4. Return per-call instructions from CallStart
   Your CallStart response supplies the OpenAI Realtime URL, authentication, time limits, and tool endpoint configuration.
5. Receive live AI calls
   Once enabled, calls to the DID will be routed through VNS into your AI-driven voice flow.

Inbound Calls

The inbound call process is handled in the following sequence:

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 voice and supplies the returned instructions.
4. Tool execution: During the session, the AI agent can invoke tools or MCP-connected systems such as schedulers, CRMs, and business APIs.
5. Call control: Certain call control actions, such as transfer to a human, 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

The outbound call process follows a similar lifecycle, but begins with a customer API request into VNS.

1. Dial request: A request is sent to the VNS Web API containing the destination number, the 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 Example

Loading example from ivlresttest.voiceelements.com…

Request Fields

CallStart Response

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

Required VoiceElements_Instructions Values

• OpenAI URL: includes the realtime model to use, such as gpt-realtime or gpt-realtime-mini.
• OpenAI token: identifies the customer account to be billed for realtime usage.
• Maximum call duration: maximum number of seconds the call may remain connected.
• Default tools URL: endpoint that VNS should call when the AI invokes a function.
• Authorization header: authentication passed to the customer tool endpoint.
• defaultToolsUrlAdapter: may be left null for now.

Response Body Example

Loading example from ivlresttest.voiceelements.com…

Tool Execution

During an active AI session, the model may trigger a function. When that happens, VNS augments the payload with metadata before forwarding the request to your webhook.

Example Tool Request Payload

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

{
"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>>"
}

Tool Reply

The Tool Reply is the JSON returned by your endpoint. VNS feeds that JSON back into the AI session so the model can use the result in the ongoing conversation.

Illustrative Tool Reply Payload

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

How It Works

• The AI-generated tool arguments are preserved in the body.
• VNS adds VoiceElements_InvokeTool metadata.
• toolName identifies which tool the AI requested.
• sessionGuid ties the tool call to the current voice session.
• customerCallId carries your optional customer correlation ID into the tool request when available.
• Your endpoint returns JSON, and that JSON is fed back into the AI session for continued conversation handling.

CallEnd Webhook

VNS performs an HTTP POST to your configured CallEnd endpoint after the call completes. The payload includes the session ID, call timing, caller information, status, and optional customer correlation data.

Request Body Example

Loading example from ivlresttest.voiceelements.com…

Request Fields

Response Body Example

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

Outbound Call Initiation

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

Webhook URL

https://ivlresttest.voiceelements.com/v1/vnsoutboundcall

Request

Example request payload:

{
  "customerCallId": "abc123",
  "calledNumber": "+13032639999",
  "callerId": "+17206999999",
  "callerIdName": "John Smith"
}

Response

Example response payload:

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

Built-in VNS Tools

VNS provides a set of built-in tools that can be included in your session's tools array without any corresponding endpoint on your server. When the AI calls these tools, VNS handles them internally and returns the result directly back into the AI session.

vns_end_conversation

Signals that the conversation is complete. Call this when the caller indicates they want to hang up or the interaction is finished. VNS will gracefully terminate the session.

Tool Definition

{
  "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" ]
  }
}

vns_transfer_call

Transfers the active call to another phone number. Use this to escalate to a live agent or route to another destination. The transfer number is never spoken or revealed to the caller.

Tool Definition

{
  "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 where the transferring party can speak to the destination before completing the transfer. When false, performs a blind transfer."
      }
    },
    "required": [ "transferNumber" ]
  }
}

Example Request

{
  "TransferNumber": "3039999999",
  "UseVnsNumberAsCallerId": false,
  "Attended": false
}

Instruction Example

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

vns_get_call_info

Returns metadata about the current call session. Useful when the AI needs to know the caller's number, the called DID, or the session identifier without hard-coding it into the instructions.

Tool Definition

{
  "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

{
  "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. Use this when the AI needs to know the current time — for example, when scheduling appointments or logging interaction timestamps.

Tool Definition

{
  "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"
}

Initial Setup

1. Sign in or create a new account at customer.voiceelements.com.
2. Navigate to Settings / DIDs to view your phone numbers.
3. If your account is not yet production-enabled, your DID cannot be pointed to VNS. To convert the account to production, schedule a meeting at calendly.com/rontanner/bookmeeting.
4. Until the UI is complete, 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
5. After support completes setup, your service will be enabled for testing and production use.