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

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

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

{
  "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
  },
  "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 end_conversation tool.",
    "model": "gpt-realtime",
    "audio": {
      "input": {
        "format": {
          "type": "audio/pcmu"
        },
        "transcription": {
          "model": "whisper-1"
        },
        "turn_detection": {
          "type": "server_vad",
          "threshold": 0.5,
          "prefix_padding_ms": 300,
          "silence_duration_ms": 200,
          "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": "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": "lookup_name_or_phone",
        "description": "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, 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

{
  "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": null,
  "outboundTriggered": false,
  "outboundCallResult": null,
  "customerCallId": "CallId-001",
  "callReferredOut": false,
  "transfers": null,
  "logInformation": null
}

Request Fields

Response Body Example

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