Voice Notes

Transcribe inbound voice messages on Telegram, Slack, WhatsApp, Discord, and Signal automatically

Voice notes sent to your bot on Telegram, Slack, WhatsApp, Discord, or Signal are transcribed and handed to the agent as plain text — on by default, with a visible placeholder when transcription is off or fails.

from praisonaiagents import Agent
from praisonai.bots import TelegramBot

agent = Agent(name="assistant", instructions="Be helpful.")
bot = TelegramBot(token="YOUR_TOKEN", agent=agent)

# STT is on by default — send a voice note to the bot,
# the agent replies to the transcribed text.
import asyncio
asyncio.run(bot.start())

The user taps the microphone and sends a voice note; the bot transcribes it with whisper-1 and the agent replies to the recognised text.

Quick Start

1. Level 1 — Bool shorthand

   STT is on by default. Turn it off per channel with stt: false.

   channels:
     telegram:
       platform: telegram
       token: ${TELEGRAM_BOT_TOKEN}
       stt: true    # default; set false to opt out

2. Level 2 — Dict

   Tune behaviour with a dict — echo the transcript, force a language, or override the model.

   channels:
     telegram:
       platform: telegram
       token: ${TELEGRAM_BOT_TOKEN}
       stt:
         enabled: true
         echo_transcripts: true
         language: en
         model: openai/whisper-1

3. Level 3 — SttConfigSchema

   Build the channel config in Python with the validated schema.

   from praisonai_bot.bots._config_schema import (
       ChannelConfigSchema,
       SttConfigSchema,
   )
   
   channel = ChannelConfigSchema(
       platform="telegram",
       token="${TELEGRAM_BOT_TOKEN}",
       stt=SttConfigSchema(
           enabled=True,
           echo_transcripts=True,
           language="en",
           model="openai/whisper-1",
       ),
   )

How It Works

The adapter downloads the voice note, transcribes it, and forwards the transcript — never dropping the turn.

Configuration Options

Fields from SttConfigSchema / SttConfig.

The bare shorthand stt: true / stt: false is accepted as {"enabled": <bool>}.

Choosing a configuration

Per-Platform YAML

channels:
  telegram:
    platform: telegram
    token: ${TELEGRAM_BOT_TOKEN}
    stt:
      enabled: true
      echo_transcripts: true
      language: en
      model: openai/whisper-1

channels:
  slack:
    platform: slack
    token: ${SLACK_BOT_TOKEN}
    app_token: ${SLACK_APP_TOKEN}
    stt:
      enabled: true
      language: en

channels:
  whatsapp:
    platform: whatsapp
    token: ${WHATSAPP_TOKEN}
    stt:
      enabled: true
      echo_transcripts: true

channels:
  discord:
    platform: discord
    token: ${DISCORD_BOT_TOKEN}
    stt:
      enabled: true
      language: en

channels:
  signal:
    platform: signal
    account: ${SIGNAL_ACCOUNT}
    bridge_url: ${SIGNAL_BRIDGE_URL}   # optional; default http://localhost:8080
    stt:
      enabled: true
      language: en

Discord and Signal specifics

Both adapters transcribe the first audio/* attachment of a message that has no text, after the access gates run.

• Discord — if a message carries both text and audio, the text wins; voice is only transcribed for empty-text messages.
• Signal — audio is fetched from the operator-configured signal-cli-rest-api bridge. Keep the bridge on localhost or a private network, as in the Signal Bot setup.

When STT Is Off or Fails

Voice notes were previously dropped silently when transcription was unavailable. Now the adapter substitutes the [Voice message received] placeholder so the agent always gets the turn — it can ask the user to retype, fall back to another channel, or acknowledge the message.

User: [voice note]  (STT disabled)
Agent: receives "[Voice message received]" and can reply
       "I got your voice note but can't transcribe it here —
        could you type it out?"

See fixed issue #2721 for context.

Best Practices

stt:
  enabled: true
  language: en

stt:
  enabled: true
  echo_transcripts: true

stt:
  enabled: false

agent = Agent(
    name="assistant",
    instructions="If a voice note can't be transcribed, ask the user to type it.",
)

Related