Voice Notes - PraisonAI

Bot platform adapters ship in the praisonai-bot package. praisonai bot serve still works exactly as documented here; for a standalone install see praisonai-bot Migration.

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

For the outbound counterpart — replying in voice — see Voice Reply (Text-to-Speech). It is off by default; set voice.mode: match_inbound for the intuitive “speak in / speak out” symmetry.

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

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

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

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.

Step	What happens
Download	Adapter caches the audio through the SSRF-safe media cache (`kind="audio"`)
Transcribe	`transcribe_media_path` calls `stt_tool` → `AudioAgent.transcribe` (whisper-1 by default)
Success	Transcript passed to `agent.chat(transcript)`; echoed back first when `echo_transcripts: true`
Failure / off	The `[Voice message received]` placeholder reaches the agent — the turn is never silently dropped

Configuration Options

Fields from SttConfigSchema / SttConfig.

Option	Type	Default	Description
`enabled`	`bool`	`true`	Transcribe inbound audio. On by default.
`echo_transcripts`	`bool`	`false`	Echo the recognised text back to the user.
`language`	`str \| None`	`null`	Optional forced language code (`"en"`, `"es"`, …).
`model`	`str \| None`	`null`	Optional STT model override (default: `openai/whisper-1`).

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

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

Set language when you know it

Forcing language: en (or the relevant code) improves transcription accuracy and speed over auto-detection.

stt:
  enabled: true
  language: en

Enable echo_transcripts for accessibility

echo_transcripts: true sends the recognised text back to the user so they can confirm what the bot heard — helpful for accessibility and correcting mis-hearings.

stt:
  enabled: true
  echo_transcripts: true

Opt out on privacy-sensitive channels

Turn STT off where voice content must not leave the device or reach a third-party STT provider.

stt:
  enabled: false

Ship a fallback plan

The [Voice message received] placeholder means the agent still gets the turn when transcription is off or fails. Give the agent instructions to handle that case gracefully.

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

Voice Reply (TTS)

The outbound counterpart — speak the agent’s reply back as a native voice note.

Inbound Media

Forward user photos and documents to your agent’s vision capability

Audio Tools

stt_tool, tts_tool, and AudioAgent.transcribe

Chat Commands

Built-in and custom bot chat commands

Gateway

Unified gateway and control-plane overview

​Quick Start

​How It Works

​Configuration Options

​Choosing a configuration

​Per-Platform YAML

​When STT Is Off or Fails

​Best Practices

​Related

Voice Reply (TTS)

Inbound Media

Audio Tools

Chat Commands

Gateway

Quick Start

How It Works

Configuration Options

Choosing a configuration

Per-Platform YAML

When STT Is Off or Fails

Best Practices

Related