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

# Voicemail and call screening

> How Callers detects voicemail and call-screening assistants on outbound calls, and how to leave a personalized voicemail message.

On outbound calls, many calls reach voicemail or an automated call-screening assistant instead of a person. Callers detects both, so your agent doesn't pitch to a machine, and can leave a voicemail message for the contact.

## How voicemail detection works

Callers checks for voicemail in two ways:

1. **During the call.** Callers listens for answering-machine greetings and beeps in real time. When it detects voicemail, the agent stops the conversation and either leaves your message or hangs up.
2. **After the call.** Post-call analysis reviews the transcript and marks calls that reached voicemail even if they weren't caught live.

A call that reaches voicemail is marked with the **Voicemail** outcome. If the contact has dial attempts left, they move to **Pending Retry** and are called again according to your [retry schedule](https://docs.callers.ai/documentation/contacts/scheduling-and-retries.md). See [Statuses and outcomes](https://docs.callers.ai/documentation/using-callers/call-statuses.md).

Voicemail detection is on by default for outbound agents. Contact [support@callers.ai](mailto:support@callers.ai) if you need to tune detection timing for your market.

## Leave a voicemail message

**1. Open the agent's voice settings**

Open the agent and click **Agent** in the editor header (see [Agent settings](https://docs.callers.ai/documentation/build-your-agent/agent-setup.md#agent-voice-and-conversation)).

**2. Turn on Leave message if reaching voicemail**

The section expands when the toggle is on.

**3. Write the message**

Type the message in **Voicemail message**. Use [variables](https://docs.callers.ai/documentation/build-your-agent/agent-variables.md) to personalize it, for example `{{name}}`. Click the speaker icon to preview it in the agent's voice.

**4. Choose when to leave it**

Pick an option in **When to leave a voicemail** (see below).

**5. Optional: vary the wording**

With **Whenever voicemail is detected** selected, turn on **Rephrase message with AI** so each message is worded slightly differently.

When voicemail is detected, the agent waits for the beep (up to about 5 seconds), speaks the message, and hangs up.

### When to leave a voicemail

| Option | Behavior | Best for |
| - | - | - |
| **Whenever voicemail is detected** (default) | Leaves a message on every call that reaches voicemail. | Short runs with few attempts per contact. |
| **First detected voicemail only** | Leaves a message the first time voicemail is reached for the contact in this agent, then hangs up silently on later voicemails. | Most outbound agents. Contacts hear from you once, without a full mailbox. |
| **On the final scheduled call (if voicemail is detected)** | Leaves a message only on the contact's last dial attempt. | Agents where you want to try live contact first and leave a message as a last resort. |

The final attempt is calculated from the agent's total dial attempts multiplied by the number of valid phone numbers the contact has.

### AI rephrasing

**Rephrase message with AI** rewrites the message slightly each time, so contacts who get several voicemails don't hear an identical recording. It's available only with **Whenever voicemail is detected**. The meaning of your message stays the same.

You can also click the rephrase button next to the message to get an AI-suggested rewording while you edit.

### Write an effective voicemail

* **Keep it under 20 seconds.** Say who you are, why you called, and what to do next.
* **Give one clear call to action**, such as a number to call back or a link you'll send by SMS.
* **Personalize it** with `{{name}}` and one relevant detail.
* **Don't include sensitive information.** Someone else may listen to the mailbox.
* **Say numbers slowly**, or spell them out in the message (for example "five five five, zero one two three").

```text Example theme={"dark"}
Hi {{name}}, this is Alex from Acme Solar about the quote you requested. I'll send you a text with a link to pick a time that works for you. Talk soon!
```

## AI call-screening detection

Phone platforms increasingly answer unknown callers with an AI assistant that asks who's calling and why before ringing the person. With call-screening detection on, the agent recognizes the screener, answers its questions briefly, then waits for the real person to pick up and starts the conversation.

If the person doesn't pick up in time, the agent ends the call.

> [!NOTE]
>
> AI call-screening detection is off by default. Contact [support@callers.ai](mailto:support@callers.ai) to turn it on for an agent and to set what the agent says to screeners.

> [!TIP]
>
> Screeners often ask for your name and the reason for the call. Make sure the agent's script makes both clear in one short sentence, for example in the agent's [instructions](https://docs.callers.ai/documentation/build-your-agent/instructions-and-guardrails.md).

## Troubleshooting

> **A real person was treated as voicemail**
>
> Short greetings like "Hello?" followed by silence can look like a machine. Use **Report issue** on the call and choose **Incorrect/Missed Voicemail Detection** so the team can review it. See [Reporting call issues](https://docs.callers.ai/documentation/using-callers/reporting-call-issues.md).

> **The agent talked to a voicemail greeting**
>
> Report the call with **Incorrect/Missed Voicemail Detection**. Post-call analysis usually still marks these calls as **Voicemail**, so the contact is retried.

> **The voicemail message is cut off at the start**
>
> The message starts after the beep or after a short timeout if no beep is heard. Start the message with a brief greeting so nothing important is lost.

> **No voicemail was left on a later attempt**
>
> Check **When to leave a voicemail**. With **First detected voicemail only**, the agent leaves one message per contact.

## Related

> **[Statuses and outcomes](https://docs.callers.ai/documentation/using-callers/call-statuses.md)**
>
> How voicemail affects contact status.

> **[Scheduling and retries](https://docs.callers.ai/documentation/contacts/scheduling-and-retries.md)**
>
> Control when contacts are called again.

> **[Webhook events](https://docs.callers.ai/documentation/webhook/webhook-events.md)**
>
> `POST_PROCESSING_FINISHED:VOICE_MAIL` and other events.

> **[Variables](https://docs.callers.ai/documentation/build-your-agent/agent-variables.md)**
>
> Personalize the voicemail message.


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