Hermes Agent Voice Not Working: Fix It Step by Step

When voice mode goes silent, the cause is almost never Hermes

You sent a voice note to your bot and got nothing back. Or the agent replied in text when you set it up to reply in audio. Or it worked yesterday and today the file just sits there, unread. Voice mode failing quietly is the most common problem people hit with Hermes Agent, and it is almost always one of eight specific things sitting between your microphone and the model.

Get started with Hermify if you would rather skip the pipeline entirely and use a managed Hermes Agent with voice already wired up. Otherwise, work through this in order - the checks are cheap and each one rules out an entire class of failure.

1. The bot cannot access voice messages on Telegram

If your agent lives on Telegram and voice messages never arrive at all - text works, but voice notes are ignored - the bot's privacy settings are the first place to look. By default a Telegram bot in a group only sees messages that mention it or start with a slash command, which means voice notes get dropped silently.

Fix it in BotFather:

1. Open @BotFather and send /mybots.
2. Pick your bot, then Bot Settings → Group Privacy.
3. Set it to Disabled.

Direct messages to the bot are not affected by this setting - if your bot works in DMs and fails only in groups, group privacy is the reason.

There is a second, subtler case: the sender's account has voice-message privacy set to "contacts only". Telegram then returns a VOICE_MESSAGES_FORBIDDEN error when the bot tries to send audio back, even though the incoming voice worked fine. If your bot receives voice but silently fails to reply with audio, check your own Telegram privacy settings first.

2. There is no speech-to-text provider configured

Hermes needs a speech-to-text (STT) backend to turn incoming audio into a prompt. If none is configured, voice messages are simply not processed - the agent reads text and ignores audio.

Check your config for the STT block:

voice:
  stt:
    provider: openai
    api_key: ${OPENAI_API_KEY}

Common misses:

• The OPENAI_API_KEY (or ELEVENLABS_API_KEY, or the key for whichever provider you picked) is not exported into the process. Confirm with printenv OPENAI_API_KEY inside the same shell that starts Hermes.
• The key exists but is wrong or has been revoked. A revoked key produces a 401 that some Hermes versions log once at start and then swallow on subsequent calls.
• You configured provider: whisper (local Whisper) without installing the extra. Local Whisper needs pip install "hermes-agent[voice]", plus a real model download on first run.

If you are unsure which provider you have, run hermes voice test (or check hermes gateway logs for a stt.provider= line at startup).

3. FFmpeg is missing from the container

This is the single most common voice failure on self-hosted deployments, and it is not obvious from the logs. Telegram delivers voice messages as .ogg files encoded with the OPUS codec, and most STT providers (including local Whisper) need FFmpeg to decode them. If FFmpeg is not on the system path, the audio arrives, fails to decode, and the pipeline exits with a codec error that looks like a network problem.

On a bare-metal or VPS install:

# Debian/Ubuntu
sudo apt update && sudo apt install -y ffmpeg

# Alpine (common on slim Docker images)
apk add --no-cache ffmpeg

Inside a Docker container built from python:3.11-slim, FFmpeg is not included by default. The official Hermes image ships with it; a custom Dockerfile might not. Verify with:

docker exec <container> which ffmpeg

If that returns nothing, add apt-get install -y ffmpeg to your Dockerfile and rebuild.

4. The voice message is too large or the wrong format

Telegram's own limits on voice notes are generous but not infinite. Bots can send voice messages up to 50 MB in size, and files above 20 MB are delivered as regular attachments rather than as playable voice notes. Incoming user voice notes are always OGG/OPUS, but if you have a workflow that pushes recorded audio through the bot from another source (a Whisper-transcribed podcast, for example), the format matters.

If your outbound voice reply is being sent as a file attachment instead of an audio bubble, the file is either too big or not audio/ogg. Re-encode it to OGG/OPUS mono under 1 MB:

ffmpeg -i input.wav -c:a libopus -b:a 32k -ac 1 output.ogg

Whisper additionally requires mono input - stereo files raise a channel-mismatch error that surfaces as "no transcription".

5. The container ran out of memory and killed the STT worker

Local Whisper models are memory-hungry. whisper-base needs about 1 GB of RAM to run, and whisper-large-v3 needs closer to 10 GB. On a 1 GB VPS the container is almost certainly getting OOM-killed the moment a voice note arrives, and Docker restarts it silently.

Check the exit code:

docker inspect <container> --format='{{.State.ExitCode}}'

An exit code of 137 is SIGKILL, which on a memory-constrained host almost always means the OOM killer. Confirm with dmesg -T | grep -i "killed process" on the host.

The fix is either a bigger machine or the hosted API instead of local Whisper. If you are running on a 1 GB droplet and want to keep voice, switch stt.provider to openai or elevenlabs - the STT call happens over the network, so RAM stays free for the reasoning loop.

If the container is restarting for reasons other than OOM, see our Hermes Agent Docker guide for a full checklist.

6. TTS is configured but never returns audio

The reverse failure: the agent transcribes your voice fine and generates a text response, but no audio reply comes back. This is almost always a text-to-speech (TTS) issue, not an STT one.

Three usual culprits:

• The TTS key hit its rate limit. ElevenLabs, in particular, has strict concurrency limits and per-second caps. When the limit is exceeded, the API returns an error rather than a silent response, but if your Hermes version does not surface upstream errors from the TTS worker, you get a text-only reply with no explanation. Check the provider's dashboard for a rate-limit spike.
• The synthesis timed out. For long responses, the standard ElevenLabs endpoint waits until the entire audio file is generated before returning. Responses over roughly 500 words can exceed default HTTP timeouts. Enable streaming synthesis if your Hermes version supports it, or ask the agent to keep replies shorter.
• The audio was generated but failed to upload. Telegram's Bot API has a sendVoice size limit of 1 MB for the audio to render as a playable bubble. Above that, it comes back as a file. If the generated MP3 is larger than 1 MB, either lower the bitrate in your TTS config or split the response.

7. The gateway is connected but the voice pipeline is not started

Hermes runs the STT and TTS pipeline as a separate worker from the main gateway. On some setups, the gateway starts cleanly but the voice worker fails to boot - usually because a Python dependency in the voice extra failed to compile at install time.

Diagnose it:

hermes voice status

If the pipeline is not running, restart it explicitly:

hermes voice start

If start fails with an import error, reinstall the voice extra:

pip install --force-reinstall "hermes-agent[voice]"

On Android/Termux use the Termux-specific extra instead:

pip install "hermes-agent[termux]"

8. Everything works locally but not in production

If voice works on your laptop and fails on the deployed instance, the culprit is nearly always one of: FFmpeg missing from the production image, environment variables not being passed to the container, or the container running as a non-root user without permission to write to the audio temp directory.

For the last case, Hermes writes short-lived WAV files to /tmp (or the configured voice.temp_dir) during transcription. If the container user cannot write there, the STT call fails at file creation. Fix it by mounting a writable volume:

volumes:
  - hermes_tmp:/tmp

Or set voice.temp_dir to a path you know is writable.

When it's cheaper to hand this off

The eight failures above are all fixable, and if you have twenty minutes and enjoy debugging codecs, you will fix them. If you would rather have the pipeline just work, Hermify runs a managed Hermes Agent on Telegram where FFmpeg, STT, TTS, memory, and the gateway are all handled for you. Voice mode is on by default, memory files stay yours, and going live takes about a minute.

For deeper reading, our voice mode setup guide covers the happy path in detail, and our post on TTS providers compares OpenAI, ElevenLabs, and local options if you are picking a stack for the first time.

Sources

• Telegram Bot API - sendVoice reference
• Whisper FFmpeg requirement discussion
• ElevenLabs production concurrency limits
• Graceful handling of ElevenLabs API rate limits