> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roark.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone network conditions

> Put the simulated caller on a bad phone line, pace a run at a set dial rate, and read what the carrier measured on every call

Real callers are not always on a good line. They ring from the edge of a cell, from a car kit, over Wi-Fi calling that keeps dropping out. Lost audio reaches your agent as holes in what the caller said, and reaches the caller as holes in what your agent said. Agents tested only on clean lines never meet any of this.

Roark can put the simulated caller on a degraded phone line. The line is part of the variant's [environment](https://docs.roark.ai/documentation/simulation-testing/environments.md), next to its background sound, so the same conversation can run on a clear line and a bad one without changing anything else.

## How a bad line works

Roark drops audio from the simulated caller's call in 20 ms packets, separately in each direction:

* **Toward the agent** is what your agent hears from the caller.
* **Toward the caller** is what the caller hears from your agent.

Loss is either **random**, where any packet can be dropped on its own, or **in gaps**, where dropped packets cluster into bursts of audio lost together. Gaps are how real lines usually fail, and they hurt more: a 120 ms gap can swallow a whole syllable.

### Line qualities

| Line | API value | What it loses |
| :- | :- | :- |
| **Clear** | `CLEAR` | Nothing. The default. |
| **Minor loss** | `MINOR_LOSS` | 1% lost at random, both ways |
| **Cell edge** | `CELL_EDGE` | 5% lost in 80 ms gaps, both ways |
| **Poor** | `POOR_CONNECTION` | 10% lost in 120 ms gaps, both ways |
| **One way** | `ONE_WAY_DEGRADED` | 8% lost in 80 ms gaps toward the agent only. The caller hears the agent clearly. |
| **Custom** | `CUSTOM` | Your own numbers, set per direction (see below) |

### Custom lines

A Custom line sets each direction on its own, with two dials:

| Dial | Range | Step |
| :- | :- | :- |
| **Loss** | 0% to 20% of packets | 0.5% |
| **Gap length** | 20 ms (random loss) to 200 ms | 20 ms |

A direction at 0% loss is left clean, so a Custom line can break up one way only, or differently each way.

### Redials lose the same packets

The loss pattern is seeded per simulation, so when Roark dials the same simulation again it drops the same packets at the same points in the audio. A failure you see on a bad line is one you can reproduce, rather than bad luck on one call.

## Ready-made bad-line environments

Alongside the sound presets, every project gets four read-only environments that pair a place with the line a caller there is likely to be on. They are listed under **Bad lines** in the Environment panel.

| Environment | Sound | Line |
| :- | :- | :- |
| **Cell edge** | City street | Cell edge: 5% lost in 80 ms gaps, both ways |
| **Car on Bluetooth** | Driving | Custom: 3% lost in 60 ms gaps, both ways |
| **Spotty Wi-Fi call** | Silent | Poor: 10% lost in 120 ms gaps, both ways |
| **Breaking up one way** | Office | One way: 8% lost in 80 ms gaps toward the agent only |

Like the other [Roark presets](https://docs.roark.ai/documentation/simulation-testing/environments.md#roark-presets), they play their sound at the default level and can't be edited. Change one and save it as your own.

## Setting the line in the flow editor

The line is set in the same Environment panel as the background sound, from the **Environment** chip on any variant of a [customer flow](https://docs.roark.ai/documentation/simulation-testing/customer-flows.md).

**1. Pick an environment**

Open the Environment chip. The panel lists the Roark presets under **Sound** and **Bad lines**, then **Your environments**. Picking one of the bad-line presets is the quickest way to put a variant on a degraded line.

**2. Choose the line**

Under **Phone line** ("Lost audio, in 20 ms packets"), pick **Clear**, **Minor loss**, **Cell edge**, **Poor**, **One way** or **Custom**. Two strips below show the line in each direction: **What the agent hears from the caller** and **What the caller hears from the agent**. Each strip is two seconds of audio, 100 packets, with a gap where one is lost. They illustrate the pattern; they are not the packets a particular call lost.

**3. Tune a Custom line**

Choose **Custom** and each direction gets its own **Loss** and **Gap length** slider, starting from whatever line was on screen. A gap length of 20 ms reads "random".

**4. Save it**

Presets keep their settings, so a changed preset becomes your own environment. Roark suggests a name such as "Office (10% noise, cell edge line)", which you can overwrite. **Use for this variant** saves it and binds the variant to it; **Save as new** saves it without changing the environment you started from. If one of your environments already has the same settings, the panel offers **Use it** instead.

The summary at the bottom of the panel reads the whole environment back as a sentence, for example "Office sound, faint, on a line with 5% lost in 80 ms gaps both ways." Wherever an environment appears afterwards, a signal mark shows its line: four bars for a clear line down to one, with the full description on hover.

## Where a line applies

Line quality only means something for an agent reached on a phone endpoint. An agent reached any other way (WebRTC, WebSocket, LiveKit and so on) has no phone line, so the setting does nothing there. When every agent a run targets is off the phone network, the run builder marks a variant with a bad line "Line ignored: this agent isn't on the phone network."

## Comparing lines with a sweep

To find out what each step down costs your agent, run the [How the agent handles a bad line](https://docs.roark.ai/documentation/simulation-testing/templates/line-quality-handling.md) template. It runs one flow on each line, from Clear to One way, and reports which lines made the agent worse. Pair it with [Background noise robustness](https://docs.roark.ai/documentation/simulation-testing/templates/background-noise-robustness.md): noise hides speech under sound, a bad line removes it.

## Config as code

Environments are not a config resource of their own. A flow in config refers to one by its display name, so a bad-line preset can be used straight away:

```yaml theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
kind: flow
type: improv
name: rebooking-from-the-road
agents: [frontdesk]
happyPath:
  persona: frustrated-caller
  environment: Quiet room
  prompt: You call to rebook the cleaning that was cancelled on you.
edgeCases:
  - name: weak-signal
    environment: Cell edge
  - name: car-kit
    environment: Car on Bluetooth
```

For a line of your own, create the environment in the editor or over the API first, then reference its name. See [Environments: config as code](https://docs.roark.ai/documentation/simulation-testing/environments.md#config-as-code).

## API

An environment carries its line in two fields:

* `lineQuality`: one of `CLEAR`, `MINOR_LOSS`, `CELL_EDGE`, `POOR_CONNECTION`, `ONE_WAY_DEGRADED` or `CUSTOM`. Defaults to `CLEAR`.
* `lineCustom`: the per-direction loss of a `CUSTOM` line, `null` on every other. It has two optional keys, `toAgent` and `fromAgent`. Each takes `packetLossPercent` (0 to 20, in steps of 0.5) and an optional `meanBurstPackets`, the average gap in 20 ms packets (2 to 10, so 40 ms to 200 ms). Leave `meanBurstPackets` out for random loss. Leave a direction out to keep it clean.

Create a car-kit line that is worse toward the agent than back:

```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
curl -X POST https://api.roark.ai/v1/simulation/environment \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Car kit, breaking up",
    "backgroundNoise": "DRIVING",
    "lineQuality": "CUSTOM",
    "lineCustom": {
      "toAgent": { "packetLossPercent": 6, "meanBurstPackets": 4 },
      "fromAgent": { "packetLossPercent": 2 }
    }
  }'
```

The agent hears the caller with 6% lost in 80 ms gaps, and the caller hears the agent with 2% lost at random.

`lineCustom` is required with `lineQuality: CUSTOM` and refused with any other line, including on an update: to change the numbers, send them with `lineQuality: CUSTOM`. Either mistake is a `400`.

## Pacing a run

A bad line is one half of a realistic phone test; the other is how calls arrive. A run plan can start its calls at a set **dial rate**, from 0.01 to 10 calls per second, with an optional linear ramp up to it, instead of starting them all as fast as concurrency allows. See [Pacing calls](https://docs.roark.ai/documentation/simulation-testing/run-plans.md#pacing-calls).

## What the carrier measured

Every simulated phone call also gets scored on what the phone carrier itself measured on the line. These come from the carrier's report, not from listening to the recording:

| Metric | Slug | What it tells you |
| :- | :- | :- |
| **Network MOS** | `network_mos` | The carrier's mean opinion score (1 to 5) for the agent's audio, computed from the packet loss and jitter it measured. The best a standard phone line can score is about 4.4. |
| **Packet Loss** | `packet_loss_rate` | The share of audio packets lost on the line, once for each side: the agent's audio and the simulated caller's. Loss above about 1% is usually audible as gaps or robotic speech. |
| **Max Jitter** | `max_jitter` | The largest variation in when the agent's audio packets arrived, in milliseconds. High jitter sounds choppy or clipped. |

They make up the **Telephony** package in the [system metrics reference](https://docs.roark.ai/documentation/metrics/system-metrics.md#telephony). Use them next to the [Call Quality (DNSMOS)](https://docs.roark.ai/documentation/metrics/system-metrics.md#call-quality-dnsmos) scores: the carrier's figures say how the line carried the audio, DNSMOS says how the audio itself sounds.

> [!NOTE]
>
> These metrics exist only for simulated calls that went over the phone network. A web or WebSocket simulation is marked not applicable, and a phone call the carrier sent no report for is marked as missing data. A figure the carrier did not report is never recorded as zero.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.