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

# Custom voicemail greeting

> Replace the default voicemail greeting on a Telnyx phone number with your own recorded audio, using the Mission Control Portal or the Voicemail API.

By default, callers who reach a voicemail-enabled Telnyx number hear a standard system greeting. You can replace it with your own audio — a branded message, business hours, or any recording you like. This guide walks through configuring a custom greeting both in the Mission Control Portal and through the API.

A custom greeting has two parts:

1. An audio file uploaded to your account through the [Media Storage API](/api/media-storage).
2. A voicemail setting on the phone number that points at that file by its `media_name`.

<Note>
  Custom voicemail greetings are configured per phone number. Voicemail must be enabled on the number for the greeting to play.
</Note>

## Prerequisites

* A Telnyx account with a phone number that has voicemail enabled.
* An [API key](https://portal.telnyx.com/#/app/api-keys).
* An audio file for your greeting (for example, a `.mp3` or `.wav` recording).

## Configure a greeting in the Mission Control Portal

<Steps>
  <Step title="Open the phone number's voicemail settings">
    In the [Mission Control Portal](https://portal.telnyx.com), go to **Numbers > My Numbers**, select the number you want to configure, and open its **Voicemail** settings. Make sure voicemail is enabled.
  </Step>

  <Step title="Upload your greeting audio">
    Choose the option to upload a custom greeting and select your audio file. The portal stores the file in your account's media storage and links it to the number as the greeting.
  </Step>

  <Step title="Save">
    Save the settings. New calls that reach voicemail on this number now play your custom greeting instead of the default one.
  </Step>
</Steps>

## Configure a greeting with the API

Configuring a greeting through the API is a two-step process: upload the audio to Media Storage, then point the number's voicemail settings at it.

### Step 1 — Upload the greeting to Media Storage

Upload your audio file with the [Media Storage API](/api/media-storage). The `media_name` you choose (or the one returned to you) is the handle you'll reference from the voicemail settings.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.telnyx.com/v2/media \
    -H "Authorization: Bearer $TELNYX_API_KEY" \
    -F "media_name=my_voicemail_greeting" \
    -F "media=@/path/to/greeting.mp3"
  ```

  ```python Python theme={null}
  import os
  from telnyx import Telnyx

  client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

  with open("/path/to/greeting.mp3", "rb") as audio:
      media = client.media.upload(
          media_name="my_voicemail_greeting",
          media=audio,
      )
  print(media.data.media_name)
  ```
</CodeGroup>

### Step 2 — Point the voicemail settings at your greeting

Update the number's voicemail settings so the greeting `mode` is `custom_greeting` and `media_name` matches the file you uploaded.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH https://api.telnyx.com/v2/phone_numbers/{phone_number_id}/voicemail \
    -H "Authorization: Bearer $TELNYX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "enabled": true,
      "greeting": {
        "mode": "custom_greeting",
        "media_name": "my_voicemail_greeting"
      }
    }'
  ```

  ```python Python theme={null}
  import os
  from telnyx import Telnyx

  client = Telnyx(api_key=os.environ.get("TELNYX_API_KEY"))

  voicemail = client.phone_numbers.voicemail.update(
      phone_number_id="{phone_number_id}",
      enabled=True,
      greeting={"mode": "custom_greeting", "media_name": "my_voicemail_greeting"},
  )
  print(voicemail.data)
  ```
</CodeGroup>

A successful response echoes the stored settings, including the greeting:

```json theme={null}
{
  "data": {
    "enabled": true,
    "pin": "1234",
    "greeting": {
      "mode": "custom_greeting",
      "media_name": "my_voicemail_greeting"
    }
  }
}
```

## The greeting object

The `greeting` object is accepted on both `POST` (create) and `PATCH` (update) of the voicemail settings, and it is returned on `GET`.

| Field        | Type   | Description                                                                                                                                                                    |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `mode`       | string | `default` plays the standard system greeting. `custom_greeting` plays your uploaded audio. Defaults to `default`.                                                              |
| `media_name` | string | The name of the media file to play. **Required when `mode` is `custom_greeting`.** Must match a file uploaded through the Media Storage API. Ignored when `mode` is `default`. |

## Revert to the default greeting

To go back to the standard system greeting, set `mode` to `default`. The `media_name` is ignored in this mode, so you can leave it out.

```bash cURL theme={null}
curl -X PATCH https://api.telnyx.com/v2/phone_numbers/{phone_number_id}/voicemail \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"greeting": {"mode": "default"}}'
```

## Troubleshooting

* **`media_name is required when mode is custom_greeting`** — you set `mode` to `custom_greeting` without a `media_name`. Include the name of an uploaded file.
* **The default greeting still plays** — confirm voicemail is enabled on the number, that the `media_name` exactly matches an existing file in Media Storage, and that the change was saved. Greeting changes apply to new calls that reach voicemail.
* **`mode must be one of: default, custom_greeting`** — `mode` only accepts those two values.

## Related

* [Voicemail API reference](/api/voicemail)
* [Media Storage API reference](/api/media-storage)