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

# Agent voice lines

> What a caller hears when they ring a provisioned agent line, and what Apostra keeps

# Agent voice lines

<Warning>
  Agent voice lines are in limited rollout, and the line does not hold a
  conversation yet. Apostra enables the account before anything answers. There
  is no self-service number picker: a line is either provisioned by Apostra or
  comes with a text line a seller administrator requests where Apostra has
  prepared agent calling.
</Warning>

An agent voice line gives a storefront agent a real telephone number that
answers inbound calls. Today the line answers, tells the caller they have
reached an automated agent, and ends the call. The spoken conversation itself
is a later step.

## What a caller hears

When someone rings the assigned number, Apostra:

1. verifies that the call event was signed by the carrier and that the number
   dialed belongs to the line;
2. answers the call;
3. speaks the automated-agent disclosure — the caller is told, before anything
   else, that the call is answered by software rather than a person; and
4. ends the call, because the line cannot carry the conversation further yet.

If step 3 fails, Apostra goes straight to step 4.

There are two rare exceptions. Controlling a live call needs a handle the
carrier issues for it, which Apostra stores encrypted. If that stored copy
cannot be read back, the call cannot be ended automatically and stays connected
until the caller hangs up or the carrier drops it. This does not affect a call
Apostra is still handling live, where the handle is in hand and the call is
ended normally. And if the carrier refuses the request to end the call, or
Apostra cannot confirm that it was received, the call can also stay connected.
In both cases Apostra raises an alert so someone can end it.

The disclosure always comes first. Nothing else is spoken on the call, and no
conversation follows it.

Answering and speaking are two separate steps, so there is one failure a
caller can notice. If the line cannot answer at all, the call simply rings
out, and nothing is billed. If the line answers but the disclosure then fails,
the caller hears the call connect and end a moment later without hearing
anything. That still counts as an answered call with your carrier and is
billed as one. Apostra ends such a call immediately rather than leaving the
caller on a silent line, and raises an alert — but the caller does experience
a connected call with no explanation. This is rare; it is not invisible.

Each step is recorded as durable work before it is attempted, so a restart or
a network failure part-way through does not abandon a caller mid-call: the
step is retried, and a caller is never answered or spoken to twice because of
a retry. If Apostra cannot confirm what happened to a step, it stops retrying
and raises it for a person rather than guessing.

## What the caller can and cannot do

A telephone number identifies a route. It does not prove who is holding the
phone. Caller ID, spoken words, and keypad tones are treated as untrusted
input, exactly like an inbound fax or text message. That boundary already
holds for the conversational line this is building toward: a call will be able
to raise a question or start a piece of work, but it will never approve spend,
change who has access to an account, publish a campaign, or reveal private
data. Those continue to require your existing authenticated confirmation
path.

## What Apostra keeps

Apostra records that a call arrived on the line, that it was answered, and
that the disclosure was spoken. That record exists so a repeated carrier
delivery cannot answer or speak twice, and so the line's behavior can be
audited.

Controlling a live call needs a handle the carrier issues for that one call.
Apostra stores it encrypted, tied to the single call it belongs to, and it is
never written to a log, returned by the API, or made visible to an agent.

Neither the caller's number nor the number they dialed is stored in that
record or written to logs. The number dialed is checked against the line it
arrived on and then discarded. Call recording and transcription are a separate
decision with their own consent and retention rules; neither is switched on by
this behavior.

## If your line is turned off

If Apostra turns agent phone lines off for your account, the line stops
answering immediately. A call already in progress is not left hanging: it is
ended rather than held on a silent line, and nothing further is spoken on it.

## Provision a line

Contact Apostra to request a voice line during the limited rollout. Choose the
account, the storefront agent, and the country or region. Apostra assigns the
carrier number, verifies that it belongs to the voice application pointed at
Apostra, and activates its route to the selected agent.

Where Apostra has prepared agent calling, a
[text-message line](/v2/storefront/agents/overview#provision-a-text-message-line)
that a signed-in seller administrator requests is also a voice line. Apostra
buys a number that can carry calls, and once the carrier confirms the number is
assigned to Apostra's voice application, calls to it reach the same storefront
agent as its texts. A number bought for texting only never answers calls.

API keys cannot create or move a line, and naming an existing number does not
claim it. One number can carry voice, text, and fax at the same time. Each is
routed separately, but always to the same account and storefront agent: a
number that texts one agent cannot answer calls for another.


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