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

# Phone Connection

> A reusable telephony connection that lets Galtea dial your AI agent's phone number for voice evaluation.

> [!WARNING]
>
> You are reading the docs of Galtea 5.14. [Read this page in the latest version](https://docs.galtea.ai/concepts/product/phone-connection.md).

## What is a Phone Connection?

A Phone Connection tells Galtea how to reach your AI agent over the phone. Instead of calling an HTTP API, Galtea **dials your agent's phone number** and runs the conversation as a real voice call — this is **Direct Inference over the phone**. You configure the phone number once, and Galtea uses it to drive voice evaluations against your telephony agent automatically. The simulated caller's language is taken from each **test case** (see [below](#how-the-callers-language-is-chosen)), so one connection serves test cases in different languages.

## Use Cases

* **Evaluate voice agents** — Galtea calls your agent's phone number directly for each test case, exercising the full telephony stack
* **Multi-turn conversation evaluation** — For Behavior test cases, Galtea drives a full conversation using the test case's persona, goal, and scenario, with the conversation simulator generating each user turn.
* **Single-turn evaluation** — For Accuracy and Security test cases, Galtea speaks the test case's input line into the call and evaluates the agent's reply — the voice equivalent of a single-turn HTTP run.
* **Standardize call configuration** — Define a reusable phone number and call protocol for repeatable voice evaluations
* **Manage multiple agents** — Create separate phone connections for different agents or environments

## Creating a Phone Connection

To create a Phone Connection:

1. Navigate to your product in the [Galtea Dashboard](https://platform.galtea.ai/)
2. In **Development** view mode, open the **Connections** section in the sidebar (under **Product**), then the **Phone** tab
3. Click "New Phone Connection"
4. Configure the connection properties as described below

## Phone Connection Properties

**Name** `Text` *required*

A unique name for the phone connection within the product. **Example**: "Production Voice Agent" or "Staging IVR".

**Phone Number** `Text` *required*

The phone number Galtea dials to reach your AI agent, in [E.164 format](https://en.wikipedia.org/wiki/E.164) (a leading `+` followed by the country code and number). **Example**: `+14155552671`.

**Agent Speaks First** `Checkbox`

Controls whether the voice agent opens the conversation once the call connects. Leave it **unchecked** (the default) when the simulated caller should speak first, which suits agents that wait for a greeting from the user. **Check** it for interviewer-style agents that greet the caller first.

## How the caller's language is chosen

The simulated caller's spoken language is **not** set on the phone connection — it comes from each [test case](https://docs.galtea.ai/v5.14/concepts/product/dataset/test-case.md)'s language. Because a phone connection is attached to a [Version](https://docs.galtea.ai/v5.14/concepts/product/version.md) and a version runs many test cases, this lets one connection cover test cases in different languages.

With a multilingual text-to-speech provider, the test case's language drives the synthesis language and the voice is selected automatically (e.g. a Spanish test case → the caller speaks Spanish with a natively-accented voice). When a test case has no language set, the provider falls back to its configured default voice.

## Adding background noise to a call

Like language, background noise is **not** set on the phone connection — it comes from each [dataset](https://docs.galtea.ai/v5.14/concepts/product/dataset.md) or [test case](https://docs.galtea.ai/v5.14/concepts/product/dataset/test-case.md). Two optional fields control it:

* **Background Noise Profile** — the kind of noise: clip-backed (`office`, `street`, `car`) or synthetic (`white`, `pink`). Leave unset for a clean recording.
* **Background Noise Level** — how loud the noise is relative to the caller's speech: `light`, `medium`, or `heavy`.

Both must be set together; setting only one is rejected. Galtea mixes the noise into the simulated caller's audio during the call, so it tests how your agent behaves under noisy conditions (e.g. a caller phoning from a busy street). The saved [call recording](https://docs.galtea.ai/v5.14/concepts/product/version/session.md) contains the noise, so what you hear on playback in the dashboard is what your agent heard.

A dataset carries a default background noise setting, and each test case can override it. A test case created without its own setting inherits the dataset's setting at creation time; setting a test case's noise explicitly (including clearing it) overrides that default for that case alone.

> [!NOTE]
>
> Background noise only applies to voice datasets run over a phone connection. It has no effect on datasets run over an [Endpoint Connection](https://docs.galtea.ai/v5.14/concepts/product/endpoint-connection.md).

## Relation to Versions

A Phone Connection becomes the **conversation target** of a [Version](https://docs.galtea.ai/v5.14/concepts/product/version.md): when a version references a phone connection, Galtea dials that number to run each evaluation.

A version's conversation target is **mutually exclusive** — a version connects to your AI product either through an [Endpoint Connection](https://docs.galtea.ai/v5.14/concepts/product/endpoint-connection.md) **or** through a Phone Connection, never both. Choose an endpoint connection when Galtea should call your HTTP API, or a phone connection when Galtea should place a voice call.

## Relation to Voice Evaluation

Phone Connections power **voice evaluation**: because Galtea drives a real phone call, the conversation, transcription, and resulting inferences reflect how your agent behaves over the telephony channel. This makes phone connections the entry point for evaluating voice agents end-to-end.

Phone connections run **any** dataset type — no additional configuration is required beyond attaching the phone connection to the version:

* **Behavior** test cases run multi-turn: the conversation simulator drives each user turn from the test case's persona, goal, and scenario.
* **Accuracy** and **Security** test cases run single-turn: Galtea speaks the test case's input line into the call and evaluates the agent's reply.

> [!NOTE]
>
> For single-turn (Accuracy/Security) datasets scored by **deterministic metrics**, leave **Agent Speaks First** unchecked (the default). When the agent speaks first, the call has two turns (the agent's greeting plus the scripted line), which deterministic metrics — designed for a single turn — cannot score correctly. Multi-turn (Behavior) datasets are unaffected.

The API automatically transcribes the agent's audio responses using speech-to-text, so no manual transcript preparation is required. Each recorded agent turn is transcribed before evaluation runs, and the written transcript is what metrics score — your agent's voice output is evaluated as accurately as any text-based agent.

Both sides of every turn are recorded and stored on the `Trace` for that turn:

* **Agent audio** (what your agent said): stored as a content-parts envelope on `actualOutput`; access the envelope via the SDK's `.actual_output_data` field and the scored transcript via `.actual_output`.
* **Simulated user audio** (what the synthetic caller said): stored as a content-parts envelope on `input`; access the envelope via the SDK's `.input_data` field and the spoken transcript via `.input`.

This means the full phone conversation — both the synthetic user side and the agent side — can be played back turn by turn in the dashboard's audio player and read programmatically via the SDK. See [Trace](https://docs.galtea.ai/v5.14/concepts/product/version/session/trace.md) for the envelope shapes.

When your agent starts to speak while the synthetic caller is talking, the caller stops within about one second, as a person would. It takes about 0.2 seconds of continuous speech-level sound, so an "mm-hm" that long stops the caller, but a click or a cough does not. Sound that began before the caller's line does not stop it. The turn's `input` then holds only the part of the line that played, and what your agent said becomes the reply to it. When your agent made sound but said no recognized words, the turn is stored with no reply and the conversation goes on. On the last turn, words your agent was still saying when the call ends are kept as the reply.

## Best Practices

> [accordion] Use descriptive names
>
> Choose names that clearly identify the agent's purpose and environment, such as "Production Voice Agent" or "Staging IVR".

> [accordion] Always use E.164 format
>
> Provide the phone number with a leading `+` and country code (e.g., `+14155552671`). Numbers in other formats are rejected.

> [accordion] Set the call's language on the test case
>
> Set each test case's language to the language your agent operates in. With a multilingual text-to-speech provider the simulated caller then speaks that language with a natively-accented voice (e.g. Spanish), with no per-connection configuration needed.

> [accordion] Set a default background noise on the dataset
>
> Set the background noise profile and level on the dataset so every generated or CSV-uploaded test case inherits realistic ambient noise automatically. Override it on individual test cases only when you need a specific case to be quieter, louder, or silent.

> [accordion] Set who speaks first
>
> If your agent greets the caller (interviewer-style), check **Agent Speaks First**. Leave it unchecked when your agent waits for the user to initiate the conversation.

## Related

> [card] [Concepts overview](https://docs.galtea.ai/v5.14/concepts/overview.md)
>
> How Galtea's concepts connect — diagram + per-entity quick reference.

> [card] [Endpoint Connection](https://docs.galtea.ai/v5.14/concepts/product/endpoint-connection.md)
>
> Connect to your AI product over an HTTP API instead of the phone.

> [card] [Phone Connection Service SDK](https://docs.galtea.ai/v5.14/sdk/api/phone-connection/service.md)
>
> Manage phone connections programmatically using the Python SDK.

> [card] [Version](https://docs.galtea.ai/v5.14/concepts/product/version.md)
>
> Attach a phone connection to a version for voice evaluation.


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