Custom voicemail greeting

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:

An audio file uploaded to your account through the Media Storage API.
A voicemail setting on the phone number that points at that file by its media_name.

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

Prerequisites

A Telnyx account with a phone number that has voicemail enabled.
An API key.
An audio file for your greeting (for example, a .mp3 or .wav recording).

Configure a greeting in the Mission Control Portal

Open the phone number's voicemail settings

In the Mission Control Portal, go to Numbers > My Numbers, select the number you want to configure, and open its Voicemail settings. Make sure voicemail is enabled.

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.

Save

Save the settings. New calls that reach voicemail on this number now play your custom greeting instead of the default one.

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. The media_name you choose (or the one returned to you) is the handle you’ll reference from the voicemail settings.

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"

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)

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.

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"
    }
  }'

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)

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

{
  "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.

cURL

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.

Voice API Fundamentals

Voice Features

AI Capabilities

Tutorials

Regional & Restrictions

API Reference

For AI Agents

Custom voicemail greeting

Prerequisites

Configure a greeting in the Mission Control Portal

Configure a greeting with the API

Step 1 — Upload the greeting to Media Storage

Step 2 — Point the voicemail settings at your greeting

The greeting object

Revert to the default greeting

Troubleshooting

​Prerequisites

​Configure a greeting in the Mission Control Portal

​Configure a greeting with the API

​Step 1 — Upload the greeting to Media Storage

​Step 2 — Point the voicemail settings at your greeting

​The greeting object

​Revert to the default greeting

​Troubleshooting

​Related

Prerequisites

Configure a greeting in the Mission Control Portal

Configure a greeting with the API

Step 1 — Upload the greeting to Media Storage

Step 2 — Point the voicemail settings at your greeting

The greeting object

Revert to the default greeting

Troubleshooting

Related