Skip to main content
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. 
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.
StepWhat happens
DownloadAdapter caches the audio through the SSRF-safe media cache (kind="audio")
Transcribetranscribe_media_path calls stt_tool → AudioAgent.transcribe (whisper-1 by default)
SuccessTranscript passed to agent.chat(transcript); echoed back first when echo_transcripts: true
Failure / offThe [Voice message received] placeholder reaches the agent — the turn is never silently dropped

​
Configuration Options

Fields from SttConfigSchema / SttConfig.
OptionTypeDefaultDescription
enabledbooltrueTranscribe inbound audio. On by default.
echo_transcriptsboolfalseEcho the recognised text back to the user.
languagestr | NonenullOptional forced language code ("en", "es", …).
modelstr | NonenullOptional 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

Forcing language: en (or the relevant code) improves transcription accuracy and speed over auto-detection.
stt:
  enabled: true
  language: en
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
Turn STT off where voice content must not leave the device or reach a third-party STT provider.
stt:
  enabled: false
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.",
)

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