Inbound Voice Agent

Overview

An inbound voice agent answers incoming phone calls. To test one, Coval calls your agent, plays the role of the user, and runs the conversation against your test set and persona. Connect Agent Demo

Choose how to connect

Most inbound voice agents just use a phone number. Use a SIP address or SIP trunk if your agent needs to receive extra context with each call — see Passing context to your agent.

	Phone number (PSTN)	SIP address / SIP trunk
What you enter	An E.164 number, e.g. `+12345678901`	A SIP URI, e.g. `sip:agent@example.com`
Identifying simulation calls	By caller number or timestamp (the SIP header is stripped)	Read the `X-Coval-Simulation-Id` SIP header
Pass extra context to your agent	Not available	Yes — e.g. a pre-configured `user_id` or attributes, via SIP headers
Firewall / IP allowlist	Not needed — your carrier handles routing	May be required for your SBC/trunk

Start with a phone number unless you specifically need to pass per-call context to your agent — that’s the main reason to choose a SIP address or trunk.

Configure

Select Inbound Voice

Choose “Inbound Voice” as the connection type.

Enter your phone number or SIP address

Set the phone_number field to either an E.164 number (+12345678901) or a SIP URI (sip:agent@example.com). It must be a valid phone number or SIP URI.

Save and test

Save the configuration and run a test call.

Passing context to your agent (SIP)

The main reason to use a SIP connection is that Coval can include custom SIP headers on each call, carrying values your agent needs to set up the right context — for example a pre-configured user_id, account ID, routing target, or agent and test-case attributes. Your agent reads these headers when the call arrives and resolves the correct account, customer, or configuration for that simulated call. This isn’t possible over a plain PSTN phone number, where carriers strip custom headers. Configure custom headers on the agent. Header values can be static or use these customer-facing template variables:

Template	Source	Example
`{{simulation_output_id}}`	The current simulation output ID	`{{simulation_output_id}}`
`{{agent.<attribute>}}`	An attribute configured on the agent	`{{agent.region}}`
`{{test_case.<attribute>}}`	An attribute from the current test case	`{{test_case.account_id}}`
`{{run_metadata.<key>}}`	Customer metadata supplied when launching the run	`{{run_metadata.preflight_job_id}}`

Run metadata is useful when every launch needs fresh connection context, such as a temporary routing destination or a job ID. Configure the header template once on the agent:

{
  "custom_sip_headers": {
    "X-Preflight-Job-Id": "{{run_metadata.preflight_job_id}}",
    "X-Routing-Target": "{{run_metadata.routing.target}}"
  }
}

Then provide the values in metadata.customer when you launch the run:

{
  "agent_id": "<agent-id>",
  "persona_id": "<persona-id>",
  "test_set_id": "<test-set-id>",
  "metadata": {
    "customer": {
      "preflight_job_id": "job-123",
      "routing": {
        "target": "wss://voice.example.com"
      }
    }
  }
}

Coval resolves the headers separately for each run before placing the call. Run-metadata templates support nested paths and array indexes, but the resolved value must be a string, number, or boolean. If a referenced key is missing or resolves to an object, array, or null, the simulation fails before dialing instead of sending an unresolved header. Coval also rejects any resolved header value that contains a carriage return or line feed.

Run metadata is visible through the Runs API. Do not put passwords, API keys, or other secrets in run metadata or SIP headers.

When a Twilio Programmable Voice SIP Domain receives the call, Twilio exposes custom headers whose names start with X- as incoming webhook parameters prefixed with SipHeader_. For example, X-Preflight-Job-Id arrives as SipHeader_X-Preflight-Job-Id. See Twilio’s SIP custom-header documentation.

SIP connections also expose a Wideband Audio (16kHz) toggle. When enabled, Coval asks its telephony provider to prefer wideband codecs such as G.722 and AMR-WB on the SIP leg, while retaining G.711 and G.729 as fallbacks. Your SIP endpoint must support at least one of the offered wideband codecs to negotiate wideband audio.L16 PCM is used for the internal 16kHz media stream between Coval and its telephony provider; it is not the codec offered to your SIP endpoint. An intermediary SBC or carrier may still transcode the call, so confirm the codec selected in the SIP answer if audio remains narrowband.

How simulations work

When you launch an evaluation with an inbound voice agent (with your agent’s phone number or SIP address set in a Coval template):

Coval’s simulated user calls your agent’s phone number or SIP address.
The conversation follows the test set scenarios you’ve defined.
The simulated user behaves according to the persona you’ve configured.
Metrics are automatically evaluated after the call completes.

Identifying simulation calls

Coval includes a custom SIP header in every outgoing call so you can correlate incoming calls with their simulation runs:

X-Coval-Simulation-Id: <simulation-id>

Whether your agent can read this header depends on which connection method you use.

SIP connection — read the header

If your agent receives calls at a SIP endpoint (for example, a Twilio Programmable Voice SIP Domain, a Telnyx SIP connection, or your own SBC), the SIP path can preserve the header end to end. Read it from the incoming SIP request or a provider webhook, depending on the provider:

Twilio Programmable Voice SIP Domains — expose X- custom SIP headers as parameters prefixed with SipHeader_ on incoming call webhooks, so the value arrives as SipHeader_X-Coval-Simulation-Id. See Twilio’s SIP custom-header documentation.
Telnyx — carries custom_headers on the outbound SIP INVITE; read X-Coval-Simulation-Id from the request at your SIP endpoint. See Telnyx’s Dial API documentation.

Phone number (PSTN) — the header is stripped

If your agent receives calls on a standard phone number, the call routes through the public telephone network, which strips non-standard SIP headers — X-Coval-Simulation-Id will not reach your application. Identify simulation calls instead by the calling phone number or by matching timestamps in the Coval dashboard.

Using Twilio Programmable Voice over a regular phone number (PSTN)? Use the pre_call_webhook_url approach instead: Coval notifies your agent of the simulation ID before each call. See the Twilio ConversationRelay guide for setup instructions.

Firewall & IP allowlist (SIP infrastructure only)

This applies only if you receive calls on your own SIP infrastructure (SBC, IP-PBX, or SIP trunk endpoint) and restrict inbound traffic by IP. If your agent receives calls on a regular phone number through a cloud provider like Twilio or Telnyx, calls arrive through your provider’s normal flow and no allowlisting is needed.

When Coval places a simulation call to your SIP infrastructure, the call arrives from specific IPs. If your firewall, ACLs, or security groups restrict which IPs can send SIP traffic, you must allowlist the IPs below — otherwise simulation calls are silently dropped before they reach your agent. Two types of traffic need to be allowed.

Signaling IPs (SIP)

SIP signaling initiates calls (the SIP INVITE plus responses). Allow these IPs on ports UDP/TCP 5060 and TLS 5061.

Region	Primary	Secondary
US	192.76.120.10	64.16.250.10
Europe	185.246.41.140	185.246.41.141
Australia	103.115.244.145	103.115.244.146
Canada	192.76.120.31	64.16.250.13
Asia (Beta)	103.115.244.158	103.115.244.159

Media IP subnets (RTP)

RTP carries the audio once the call connects. Allow these subnets on UDP ports 16384–32768.

255.198.128/25
114.136.128/25
114.144.0/21
16.226.0/24
16.227.0/24
16.228.0/24
16.229.0/24
16.248.0/24
16.249.0/24
115.244.128/25
246.41.128/25

If simulation calls are failing with no audio or immediate hangups, a missing IP allowlist entry is a common cause. Verify that both the signaling IPs and media subnets are allowed in your firewall.

Troubleshooting

Symptom	Likely cause
Invalid phone number	Use E.164 format with a country code, or a valid `sip:` URI
Call connection failures	Verify the number/SIP address is active and reachable
Poor audio quality	Check your telephony provider settings
Calls dropped with no audio / immediate hangup	Missing firewall allowlist entry (SIP infrastructure) — see above
Timeout issues	Adjust agent response-timing configuration

Simulate

Evaluate

Observe

Review

Cookbooks

Sofia

Reference

Overview

Choose how to connect

Configure

Passing context to your agent (SIP)

How simulations work

Identifying simulation calls

SIP connection — read the header

Phone number (PSTN) — the header is stripped

Firewall & IP allowlist (SIP infrastructure only)

Signaling IPs (SIP)

Media IP subnets (RTP)

Troubleshooting

​Overview

​Choose how to connect

​Configure

​Passing context to your agent (SIP)

​How simulations work

​Identifying simulation calls

​SIP connection — read the header

​Phone number (PSTN) — the header is stripped

​Firewall & IP allowlist (SIP infrastructure only)

​Signaling IPs (SIP)

​Media IP subnets (RTP)

​Troubleshooting

Overview

Choose how to connect

Configure

Passing context to your agent (SIP)

How simulations work

Identifying simulation calls

SIP connection — read the header

Phone number (PSTN) — the header is stripped

Firewall & IP allowlist (SIP infrastructure only)

Signaling IPs (SIP)

Media IP subnets (RTP)

Troubleshooting