Built-in VNS Tools

Overview

VNS ships with four built-in tools that are handled entirely inside Voice Nexus Service. When the AI model invokes one of these tools, VNS intercepts the call and responds directly — your server is never contacted. To make a built-in tool available to the AI, include its definition in the tools array of your CallStart response.

Because VNS resolves these tools internally, you can use them without standing up any extra endpoints. They cover the most common session-management operations: ending a call gracefully, transferring to a live agent, reading call metadata, and fetching the current time.

Note: All four tools are resolved internally by VNS. No tool webhook call is made to your server when the AI invokes them.

vns_end_conversation

Signals that the conversation is complete. VNS gracefully terminates the session. Pass a farewell message so the AI speaks a custom goodbye before the session ends.

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."
            },
            "farewell": {
                "type": "string",
                "description": "The farewell you would like to say to the caller."
            }
        },
        "required": [
            "user_input",
            "farewell"
        ]
    }
}

Example Instruction

Add something like this to your instructions string in the CallStart response:

## 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.

Tool Definition

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

Example Instruction

Add something like this to your instructions string in the CallStart response:

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. Provides the session GUID, customer call ID, called number, caller ID, caller ID name, call start time (UTC), and a flag indicating whether the call is inbound or outbound.

Tool Definition

{
    "name": "vns_get_call_info",
    "description": "Call this function to get information about the SessionGuid, CustomerCallId, Called Number, Caller Id, Caller Id Name, the Call Start Time (UTC) and a flag indicating if the call was inbound or outbound.",
    "type": "function",
    "parameters": null
}

Example Response

VNS feeds this payload back to the AI model:

{
    "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, appointment booking, or logging — without embedding a timestamp in your static instructions.

Tool Definition

{
    "name": "vns_get_utc_datetime",
    "description": "If the actual date and time is needed call this function to get it.",
    "type": "function",
    "parameters": null
}

Example Response

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

Overview

vns_end_conversation

Tool Definition

Example Instruction

vns_transfer_call

Tool Definition

Example Instruction

vns_get_call_info

Tool Definition

Example Response

vns_get_utc_datetime

Tool Definition

Example Response

Ready to Automate Your Phone Lines?