# Voice lines

Some of what an agent says never changes: the greeting, the menu, "are you still there?", the goodbye. Synthesising those on every call means paying for them on every call and waiting for them on every call. A voice line is one of them rendered once and replayed.

## What becomes a voice line

The fixed text an agent already has. There is nothing to author — the lines exist because the agent has a greeting and a silence prompt, and this is the list of them.

`GET /v1/agents/{id}/voice_lines`

**Shell**

```bash
curl -s https://voice.sphoro.com/v1/agents/$AGENT_ID/voice_lines \
  -H "Authorization: Bearer $SPHORO_API_KEY"
```

**Response200 OK**

```json
{
  "lines": [
    {"line": "greeting",       "language": "en-IN", "state": "ready",   "duration_seconds": 3.2},
    {"line": "silence_prompt", "language": "en-IN", "state": "ready",   "duration_seconds": 1.4},
    {"line": "final_message",  "language": "en-IN", "state": "pending"},
    {"line": "greeting",       "language": "hi",    "state": "ready",   "duration_seconds": 3.6}
  ]
}
```

One line per language, because a greeting in Hindi and a greeting in English are two different recordings. A static [flow node](https://voice.sphoro.com/docs/flows)'s `say` is rendered the same way, which is what makes a static node instant.

## Refreshing them

Change a greeting and the old rendering is stale. Refresh re-renders every line for the agent in its current voice and wording.

`POST /v1/agents/{id}/voice_lines/refresh`

**Shell**

```bash
curl -s -X POST https://voice.sphoro.com/v1/agents/$AGENT_ID/voice_lines/refresh \
  -H "Authorization: Bearer $SPHORO_API_KEY"
```

> **A stale line is not a broken call.** Until the refresh lands the agent synthesises that line live, exactly as it would with no voice line at all. So a refresh is a cost and latency optimisation, never a correctness step — you cannot leave callers hearing last month's greeting by forgetting one.

## Uploading your own recording

The other reason to reach for this page: a line you want in a *human* voice. A professionally recorded greeting, a jingle, a legally worded disclaimer that has to be spoken exactly as approved.

`PUT /v1/agents/{id}/voice_lines/{line}`

**Shell**

```bash
curl -s -X PUT https://voice.sphoro.com/v1/agents/$AGENT_ID/voice_lines/greeting \
  -H "Authorization: Bearer $SPHORO_API_KEY" \
  -H "Content-Type: audio/wav" \
  --data-binary @greeting-en.wav
```

`DELETE /v1/agents/{id}/voice_lines/{line}`

**Shell**

```bash
# Back to the synthesised version.
curl -s -X DELETE https://voice.sphoro.com/v1/agents/$AGENT_ID/voice_lines/greeting \
  -H "Authorization: Bearer $SPHORO_API_KEY"
```

> **An uploaded line does not follow a text change.** Edit the greeting on the agent and the recording keeps saying the old words, because nothing here can re-record a human. That is the trade for using one: the text and the audio are yours to keep in step. Delete the upload to go back to the synthesised line, which always matches.

## Why cached audio has to be paced

A pre-rendered line is already in memory, so it *could* be written to the carrier instantly. It is not: it is written at the rate speech actually plays.

Writing a nine-second menu in three milliseconds ends the agent's speaking state nine seconds early, and the call thinks it has finished talking while the caller is still hearing option two. Everything that depends on the agent holding the floor breaks silently — barge-in most of all, because a caller pressing a key during the menu is interrupting something the platform believes already ended.

## What this is worth

|  | Synthesised live | Voice line |
| --- | --- | --- |
| Cost, per call | Paid every time | Paid once |
| Time to first audio | 100–150ms, plus the vendor's own variance | Effectively none |
| Behaviour when the vendor is down | The chain falls through to another vendor | Unaffected — nothing is called |
| Follows a text edit | Immediately | After a refresh, or never for an upload |

On a high-volume inbound line the greeting is the single most-spoken sentence in the account, so this is usually the largest synthesis saving available and the easiest to take. See [latency](https://voice.sphoro.com/docs/latency) for where the rest of the time goes.