> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coval.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Inbound Voice Agent
> Configure agents that receive incoming phone calls from users and simulate inbound calls for testing
## 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.
## 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](#passing-context-to-your-agent-sip).
| | **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
Choose "Inbound Voice" as the connection type.
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 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, or [agent and test-case attributes](/concepts/attributes/overview). 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.
SIP connections also expose a **Wideband Audio (16kHz)** toggle that switches from the default narrowband codec (G.711 at 8kHz) to L16 PCM at 16kHz. In practice it rarely makes a noticeable difference — the PSTN leg is narrowband regardless and many carriers transcode audio — so you can leave it off unless you have a specific reason to enable it.
## 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](/concepts/templates/overview)):
1. Coval's simulated user calls your agent's phone number or SIP address.
2. The conversation follows the test set scenarios you've defined.
3. The simulated user behaves according to the persona you've configured.
4. 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:
```http theme={null}
X-Coval-Simulation-Id:
```
Whether your agent can read this header depends on which connection method you use.
### SIP trunk — read the header
If your agent receives calls via a SIP trunk (e.g., Twilio SIP Trunking, Telnyx SIP Trunking, or your own SBC), the header is preserved end-to-end and your provider surfaces it on the inbound call event. How you access it depends on the provider:
* **Twilio** — exposes 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 documentation](https://www.twilio.com/docs/voice/api/sip-interface).
* **Telnyx** — includes custom SIP headers in the `sip_headers` array on the `call.initiated` webhook; look for `X-Coval-Simulation-Id`. See [Telnyx's SIP documentation](https://developers.telnyx.com/docs/voice/sip-trunking).
### 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](/guides/simulations/twilio-conversationrelay) 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**.
```text theme={null}
36.255.198.128/25
50.114.136.128/25
50.114.144.0/21
64.16.226.0/24
64.16.227.0/24
64.16.228.0/24
64.16.229.0/24
64.16.248.0/24
64.16.249.0/24
103.115.244.128/25
185.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 |