SIP Calls

Overview

Test your SIP (Session Initiation Protocol) based agents directly through Cekura’s agents, bypassing traditional telephony networks. This 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 Testing Works on Cekura

When you run a SIP test, the flow works as follows:

SIP Invite: Cekura sends a SIP INVITE request to your agent’s SIP endpoint
Header Injection: Cekura automatically injects custom headers with test metadata
Session Negotiation: SIP protocols negotiate audio codecs, media parameters, and connection details
Media Stream: Direct RTP (Real-time Transport Protocol) audio streams are established
Call Handling: Your agent processes the call with full access to SIP headers and metadata
Results Collection: Cekura captures audio, transcripts, and evaluation metrics

Custom Headers

Cekura injects headers into every SIP INVITE request to provide metadata and enable advanced functionality.

Default Headers

Cekura automatically injects critical headers into every SIP INVITE request to link the call session to the test run:

X-Run-Id: <unique-run-id>
X-Scenario-Id: <scenario-id>
X-Result-Id: <result-id>

These headers allow you to:

Track which test scenario triggered the call
Link calls with specific test runs
Extract metadata for debugging and analysis
Enrich simulation evaluations programmatically

User-Defined Custom Headers

You can add additional custom headers through test profiles. When a test profile is attached to a scenario or run, your custom headers are sent alongside the default headers in the SIP INVITE request. Requirements:

Put custom headers in the test profile’s information.main_agent_variables section (these reach the agent under test; values in testing_agent_variables stay on the simulator and are not sent over the wire).
Header keys must start with "X-" (e.g., "X-Auth-Token", "X-Customer-Type")
Only keys with the "X-" prefix from main_agent_variables are included as SIP headers

Example test profile:

{
  "name": "Premium Customer Profile",
  "information": {
    "main_agent_variables": {
      "X-Auth-Token": "abc123xyz",
      "X-Customer-Tier": "premium",
      "X-Account-Type": "business"
    },
    "testing_agent_variables": {
      "customer_name": "Jane Smith"
    }
  }
}

In this example, the SIP INVITE will include:

Default headers: X-Run-Id, X-Scenario-Id, X-Result-Id
Custom headers: X-Auth-Token, X-Customer-Tier, X-Account-Type
Note: customer_name is in testing_agent_variables so it is NOT sent as a SIP header. Keys in testing_agent_variables stay on Cekura’s simulator only.

Use custom headers to pass authentication tokens, routing information, or metadata to your SIP infrastructure.

SIP Originating Region

By default, Cekura’s SIP calls leave Twilio from its North America Virginia region. To choose the region explicitly, set SIP Originating Region under the SIP endpoint in your agent settings:

Option	Twilio region
Provider default	Twilio’s default (Virginia)
US East	North America Virginia (`us1`)
US West	North America Oregon (`us2`)

Through the API, set telephony.sip_originating_region on the agent to "us-east", "us-west", or null for the provider default. The setting applies to every SIP run for that agent.

Firewall Requirements

Unless you select US West above, Cekura places SIP calls through Twilio’s Virginia (us1) region. If your SIP endpoint is behind a firewall, allow:

Traffic	Source	Ports
RTP audio (Twilio global media range)	`168.86.128.0/18`	UDP `10000` – `60000`
SIP signaling (Twilio Virginia)	`54.172.60.0/30`	UDP/TCP `5060`, TLS `5061`

Both are required: if signaling is allowed but the global media range is not, calls connect with no audio. We also recommend allowing Twilio’s Oregon signaling range (54.244.51.0/30) so calls keep working if Twilio fails over from Virginia. If you select US West, the Oregon range is required instead. See IP Whitelisting: SIP Calls for a setup checklist and links to Twilio’s documentation.

No-code
Code

Test your SIP-based agents directly from the frontend without writing code.

Configure SIP endpoint

Go to your agent settings and configure the SIP endpoint:

Required field:

SIP Endpoint: The SIP URI where your agent receives calls (e.g., sip:agent@yourdomain.com or sip:192.168.1.100:5060)

Optional fields (for secure private endpoints):

Username: Digest authentication username (only required if your SIP endpoint uses digest authentication)
Password: Digest authentication password (only required if your SIP endpoint uses digest authentication)

Your SIP endpoint can be either publicly accessible or a private endpoint secured with digest authentication. If using digest authentication, provide the username and password credentials configured on your SIP server.

If your SIP endpoint is behind a firewall, allow Twilio’s global media IP range and its SIP signaling IPs. Cekura places SIP calls through Twilio. See Firewall Requirements.

Run tests from frontend

Select scenarios and run tests using the UI.
Click Run to open the Configure Run dialog. Under Connections, select SIP under the VOICE section.
Confirm your SIP endpoint, then click Run.

Cekura automatically:

Sends SIP INVITE requests to your configured endpoint
Injects custom headers (X-Run-Id, X-Scenario-Id, X-Result-Id)
Executes test scenarios
Captures audio and transcript data
Evaluates metrics in real-time

View results

Results appear in your dashboard. Track test status, metrics, conversation details, and other details.

Use the API to integrate SIP testing into your CI/CD workflow.

Prerequisites

Configure the SIP endpoint in your agent settings:

Required field:

SIP Endpoint: The SIP URI where your agent receives calls (e.g., sip:agent@yourdomain.com or sip:192.168.1.100:5060)

Optional fields (for secure private endpoints):

Username: Digest authentication username (only required if your SIP endpoint uses digest authentication)
Password: Digest authentication password (only required if your SIP endpoint uses digest authentication)

If your SIP endpoint is behind a firewall, allow Twilio’s global media IP range and its SIP signaling IPs. Cekura places SIP calls through Twilio. See Firewall Requirements.

API Endpoint

POST https://api.cekura.ai/test_framework/v1/scenarios/run_scenarios_sip/

Authentication

Include your API key in the request header:

X-CEKURA-API-KEY: <YOUR_API_KEY>

Request Parameters

scenarios (array | integer | string, required): Test scenarios to run

Array format: List of scenario IDs [123, 456, 789]
Integer format: Run first N scenarios for the agent 5
String format: Run all scenarios for the agent "all"

agent_id (integer, optional): Your Agent ID in Cekura. Required when using integer or “all” format for scenariosfrequency (integer, optional): Number of times to run each scenario (default: 1)name (string, optional): Custom name for this test run

Examples

Single Run (cURL)

curl -X POST \
  'https://api.cekura.ai/test_framework/v1/scenarios/run_scenarios_sip/' \
  -H 'X-CEKURA-API-KEY: <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "scenarios": [30]
  }'

Multiple Runs (cURL)

curl -X POST \
  'https://api.cekura.ai/test_framework/v1/scenarios/run_scenarios_sip/' \
  -H 'X-CEKURA-API-KEY: <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "scenarios": [30, 31, 32],
    "frequency": 2,
    "name": "SIP Test Run"
  }'

Response

{
  "id": 16870,
  "name": "SIP Test Run",
  "agent": 5,
  "status": "in_progress",
  "success_rate": 0.0,
  "run_as_text": false,
  "is_cronjob": false,
  "runs": [
    {
      "id": 34625,
      "status": "running",
      "scenario": 11547,
      "scenario_name": "Customer Support Scenario",
      "test_profile_data": {"key": "value"}
    }
  ],
  "created_at": "2025-10-16T09:32:59.484534Z",
  "updated_at": "2025-10-16T09:32:59.484942Z"
}

Error Responses

Missing SIP Endpoint

{
  "sip_endpoint": ["Agent does not have a SIP endpoint configured. Please configure sip_endpoint in the agent settings."]
}

Invalid SIP Endpoint Format

{
  "sip_endpoint": ["Invalid SIP URI format. Expected format: sip:user@host[:port]"]
}

Monitor Results

Poll for results using the List Runs with IDs API.

Extracting Custom Headers

Your SIP infrastructure can extract the custom headers during call setup for tracking and debugging:

# Example: Extracting headers in a SIP application
def handle_sip_invite(invite_message):
    run_id = invite_message.headers.get('X-Run-Id')
    scenario_id = invite_message.headers.get('X-Scenario-Id')
    result_id = invite_message.headers.get('X-Result-Id')

    if run_id and scenario_id and result_id:
        # Store for later use in debugging or enriching evaluations
        log_test_metadata(run_id, scenario_id, result_id)

Use these headers to correlate SIP calls with specific test runs in your own logging and monitoring systems.

Get Started

Key Concepts

Guides

Integrations

Advanced

Overview

What is SIP?

How SIP Testing Works on Cekura

Custom Headers

Default Headers

User-Defined Custom Headers

SIP Originating Region

Firewall Requirements

Prerequisites

API Endpoint

Authentication

Request Parameters

Examples

Single Run (cURL)

Multiple Runs (cURL)

Response

Error Responses

Missing SIP Endpoint

Invalid SIP Endpoint Format

Monitor Results

Extracting Custom Headers

​Overview

​What is SIP?

​How SIP Testing Works on Cekura

​Custom Headers

​Default Headers

​User-Defined Custom Headers

​SIP Originating Region

​Firewall Requirements

​Prerequisites

​API Endpoint

​Authentication

​Request Parameters

​Examples

​Single Run (cURL)

​Multiple Runs (cURL)

​Response

​Error Responses

​Missing SIP Endpoint

​Invalid SIP Endpoint Format

​Monitor Results

​Extracting Custom Headers

Overview

What is SIP?

How SIP Testing Works on Cekura

Custom Headers

Default Headers

User-Defined Custom Headers

SIP Originating Region

Firewall Requirements

Prerequisites

API Endpoint

Authentication

Request Parameters

Examples

Single Run (cURL)

Multiple Runs (cURL)

Response

Error Responses

Missing SIP Endpoint

Invalid SIP Endpoint Format

Monitor Results

Extracting Custom Headers