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

# Voicemail

> Where messages come from, what makes one appear in the inbox, and the difference between reading a message and hearing it.

**Voicemail** is the organisation's inbox. Every message left for an
extension or a queue lands here, with the call it came from and the customer
who left it, so a message is part of that customer's history rather than a
file in a mailbox somewhere.

FireTone takes messages itself rather than handing the job to the switch's
own voicemail. That is what lets a message carry a call, a contact, a
transcript and a place on the call's page.

## The four ways a message is left

| Why                | What happened                               |
| ------------------ | ------------------------------------------- |
| **No answer**      | an extension rang and nobody picked up      |
| **IVR**            | a flow sent the caller to voicemail         |
| **Agent handover** | somebody passed the caller to a mailbox     |
| **Queue timeout**  | the caller waited in a queue and it gave up |

Three of those are on the core call path, which is why voicemail is part of
the product rather than a module to switch on. A tenant who turns everything
else off still has calls nobody answers.

## Turning it on for an extension

**Voicemail is off until somebody asks for it**, per extension. Enabling the
feature must not start answering for phones whose owners never wanted it.

On the extension you also set where a new message is **emailed** (the
recording is attached) and **texted**. Both are optional, and messages are in
the inbox either way.

### What the caller hears

A greeting, then a beep, then recording. The greeting is the first of these
that exists: one you recorded, text you asked to have spoken, a prompt from
the [audio library](/tenant/inbound/audio), and failing all three a stock
prompt — so voicemail works before anybody has recorded anything. The beep is
generated by the switch, so there is no file to install.

|                 |                                                   |
| --------------- | ------------------------------------------------- |
| Longest message | **2 minutes** by default                          |
| Ends early when | the caller stops talking, or presses <kbd>#</kbd> |
| Discarded       | anything under **2 seconds**                      |

That last one matters more than it looks. A caller who hangs up at the beep
leaves a fraction of a second of nothing, and an inbox full of those is how
people stop opening the inbox.

## The inbox

Rows carry who called, whose mailbox it is, why it was left, how long it is,
the transcript's state and the first of what was said.

Search covers the transcript, the summary and the caller's number. That is
the point of having a transcript: *the caller who mentioned a refund* is how
somebody actually looks for a message.

Who sees what: an agent sees messages for their own extension and their
queues. Everyone above sees the organisation's.

## Transcription, and when there is none

A message is **waiting**, then **ready** or **not transcribed**. It is
transcribed with the organisation's own AI credential.

<Note>
  **A failure is a state with a reason, never a missing message.** The
  recording is the product and the text is the convenience, so a message that
  could not be transcribed still appears, still plays, and says why.
</Note>

It is tried three times. A message that has failed three times is failing for
a reason a fourth attempt will not fix — no credential, a file that is not
audio, a provider refusing the account. Fix the cause, then use **Transcribe
again**, which is there because the commonest failure is a credential
somebody corrects afterwards and then wants applied to the messages that
arrived meanwhile.

## Reading, hearing, and changing

| Action                                                | Needs              |
| ----------------------------------------------------- | ------------------ |
| see a message and read its transcript                 | `voicemail:read`   |
| play it                                               | `voicemail:listen` |
| mark it heard, ask for transcription again, delete it | `voicemail:write`  |

Listening is separate from reading because a person's recorded voice and a
transcript of it are different disclosures.

**Heard** is a timestamp rather than a tick: who heard it and when is a
question people ask, and a boolean cannot answer it. Playing a message is
what "heard" means, so it is recorded then rather than by asking somebody to
tick a box about their own attention.

Nothing else about a message can be changed — not the transcript. An editable
record is not a record.

## Where the audio lives, and for how long

Messages are stored per organisation, apart from call recordings and apart
from the audio library, because they have different retention and a customer
asking for their own data should not mean sifting a shared directory.

Deleting a message removes the **file as well as the row**, from the node and
from the organisation's bucket. A recording of somebody's voice that nothing
points at any more is the worst kind of file to leave on a disk.

How long messages are kept is set per organisation, and the default is to
keep them — see [recording and what is
kept](/guides/recording-and-retention).

<Note>
  Voicemail needs somewhere to write. It defaults to a directory on each
  node; a node where `FIRETONE_VOICEMAIL_DIR` has been set to nothing takes no
  messages at all.
</Note>