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.
2. 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

1. 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.

2. 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.

3. 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

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"

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

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

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.

Related

• Voicemail API reference
• Media Storage API reference