Skip to main content

​
Connecting via SIP

Bluejay supports direct SIP (Session Initiation Protocol) connectivity, allowing you to bypass the traditional PSTN (Public Switched Telephone Network) and establish direct connections to your voice agents. This approach provides enhanced control, reduced latency, and access to rich call metadata through custom headers.

​
What is SIP?

SIP (Session Initiation Protocol) is a signaling protocol used for initiating, maintaining, and terminating real-time communication sessions. Unlike traditional PSTN calls that route through telephone networks, SIP enables direct IP-based communication between endpoints.

​
How SIP Calls Connect

When you configure your agent for SIP connectivity, the call flow works as follows:
  1. SIP Invite: Bluejay sends a SIP INVITE request to the voice agent endpoint
  2. Header Injection: Bluejay automatically injects custom headers, including the X-Simulation-Result-Id
  3. Session Negotiation: SIP protocols negotiate audio codecs, media parameters, and connection details
  4. Media Stream: Direct RTP (Real-time Transport Protocol) audio streams are established
  5. Call Handling: Your agent processes the call with full access to SIP headers and metadata

​
X-Simulation-Result-Id Header

Bluejay automatically injects a critical header into every SIP INVITE request: 
X-Simulation-Result-Id: <unique-simulation-result-id>
This header contains a unique identifier that links the specific call session to Bluejay’s simulation and evaluation system.

​
Header Usage in SIP INVITE

When your SIP system receives an incoming call from Bluejay, the complete SIP INVITE will include: 
INVITE sip:your-endpoint@your-domain.com SIP/2.0
Via: SIP/2.0/UDP bluejay-sip-gateway.com:5060
From: <sip:agent@bluejay.ai>
To: <sip:your-endpoint@your-domain.com>
Call-ID: unique-call-identifier
X-Simulation-Result-Id: 1234
X-Call-Type: SIP
Content-Type: application/sdp
...

​
Extracting the Header

Your SIP infrastructure can extract this header during call setup: 
# Example: Extracting header in Python/SIP library
def handle_sip_invite(invite_message):
    simulation_id = invite_message.headers.get('X-Simulation-Result-Id')
    if simulation_id:
        # Store for later use in updating simulation results
        store_simulation_id(simulation_id)
Using this header, you can now enrich your simulation evaluations by calling the /v1/update-simulation-result endpoint. For more information, see the Tool Calls & Metadata documentation.

​
Integrations Guides

  1. Start by create a SIP URI in VAPI, go to phone numbers and click on the create a new phone number. Click on the Free VAPI SIP option and specify the SIP identifier you want to use in your URI.
VAPI SIP 1VAPI SIP 2
  1. Set up a webhook that accepts messages for everything you want to track from your agent along with the end of call report from VAPI. The webhook format that VAPI sends can be found here. To get started you can set up the webhook (Server URL) under the SIP URI but you can also specify the webhook URL at different levels.
VAPI SIP 3
  1. After your webhook is set up and you track the relevant tool calls and metadata from your agent, you can pull the simulation result ID from the end-of-call-report message that VAPI sends to your webhook.
{
  "message": {
    "timestamp": 1759863299084,
    "type": "end-of-call-report",
    //....
    "assistant": {
      //....
      "variableValues": {
        "cid": "....",
        "account-sid": "....",
        "from-number": "+18888888888",
        "special-item": "Apricots", // other SIP headers that could be sent from Bluejay
        "simulation-run-id": "5678",
        "simulation-result-id": "1234"
      }
    }
  }
}
  1. You can now use this simulation result ID to update the simulation result with the tool calls and metadata you have collected from your agent by calling the /v1/update-simulation-result endpoint.
import requests

url = "https://api.getbluejay.ai/v1/update-simulation-result"
headers = {
    "X-API-Key": "<your-api-key>"
}

# Pass in the simulation result ID, tool calls, and metadata collected from VAPI
def update_simulation_result(simulation_result_id, tool_calls, metadata):
    data = {
        "simulation_result_id": simulation_result_id,
        "tool_calls": tool_calls,
        "metadata": metadata
    }
    response = requests.post(url, headers=headers, json=data)
    return response.json()
For any further technical support with SIP configuration or integration questions, contact the Bluejay team.