Voice Replies in Telegram and Discord

+15 Mana ✨
Hermes Voice Mode(DOCUMENTATION)Use Voice Mode with Hermes(DOCUMENTATION)

Introduction

Once Hermes runs as a Telegram or Discord bot, it can do more than type back: it can speak. This lesson covers how to turn that on, the three reply modes you choose between, and one trap that catches everyone who learned voice on the CLI first.

Key Concepts

  • Gateway: Started with hermes gateway, the process that connects Hermes to your configured messaging platforms.
  • Reply mode: How the bot decides whether to speak a reply. There are three: off, voice_only, and all.
  • Voice note: A spoken audio message a user sends in a chat, as opposed to typed text.
  • Persisted setting: The reply mode is remembered across gateway restarts.

Real World Context

Someone walking between meetings sends Hermes a voice note from Telegram and wants a spoken answer back, with no typing in either direction. Someone else, in a Discord direct message at their desk, wants every reply spoken so they can listen while their eyes stay on their work. Same feature, two different reply modes. Choosing the right one is the whole skill of this lesson.

Deep Dive

Start the gateway:

bash
hermes gateway

This connects Hermes to whatever messaging platforms you have configured. Spoken replies are then controlled, per conversation, with /voice commands typed into the chat.

There are three reply modes:

  • off: Text only. This is the default.
  • voice_only: The bot speaks its reply only when you sent it a voice note. Type, and it answers in text; send audio, and it answers in audio. The bot mirrors your input.
  • all: The bot speaks every reply, no matter how you sent the message.

The commands that set them:

text
/voice          toggle voice replies on and off
/voice on       voice_only mode
/voice tts      all mode
/voice off      off mode
/voice status   show the current mode

Here is the trap. In the CLI, /voice tts toggled spoken output and /voice on entered voice mode. In the gateway these same commands mean different things: /voice on selects voice_only, and /voice tts selects all. The words are identical, the behavior is not. The reason is that the two environments have different shapes. The CLI is one continuous session you enter and leave. A gateway bot serves many separate chats at once and needs a per-chat setting for how much to speak. Do not carry the CLI reflex across. When unsure, run /voice status.

The mode is persisted. Set it once and it survives gateway restarts, so you are not reconfiguring after every restart of the bot.

Voice travels in both directions. A voice note you send the bot is transcribed automatically by your configured STT provider, the same speech-to-text engine you set up earlier, and reaches the agent as plain text. So voice_only produces a fully spoken loop when you want one: speak and the bot speaks back, type and it types back.

Choosing a mode comes down to one question. voice_only is the natural default, because it matches the bot's output to the user's input and keeps typed conversations fast. Reserve all for when the user genuinely wants a hands-free listening assistant, the same idea as enabling spoken output only when your eyes are busy. Speaking every reply to someone who is typing only adds latency.

Common Pitfalls

  1. Carrying the CLI command meanings across: In the gateway, /voice on is voice_only and /voice tts is all. They do not mean what they meant in the CLI. Confirm with /voice status.
  2. Defaulting to all mode: Speaking every reply to a user who is typing adds latency for no benefit. voice_only matches output to input and is the better default.

Best Practices

  1. Prefer voice_only: It mirrors the user's input modality and keeps typed conversations quick. Move to all only for a deliberate listen-only session.
  2. Trust the persisted setting: Set the mode once per chat. It survives restarts, so there is no need to reset it after the bot restarts.

Summary

  • hermes gateway runs Hermes as a Telegram and Discord bot that can speak its replies.
  • Three reply modes: off (text only), voice_only (speak only when the user sent a voice note), and all (speak every reply).
  • In the gateway, /voice on means voice_only and /voice tts means all, which is not what those commands meant in the CLI.
  • Voice notes you send are transcribed automatically, and the chosen mode persists across restarts.

Code Examples

bash
# Typed inside a Telegram or Discord chat with the bot:
/voice status    # which reply mode is this chat in?
/voice on        # voice_only: speak only when you send a voice note
/voice tts       # all: speak every reply
/voice off       # back to text only

# Reminder: in the CLI, these same commands meant something different.
✓ Completed