Bot Status Reactions
Show agent run progress as an emoji reaction on the user's message
Status reactions update an emoji on the user’s message to reflect run state — queued, thinking, tool execution, done, or error — and add a “still working…” ⏳ / “taking longer than expected” ⚠️ signal when a run goes quiet, all without reading reply text.
from praisonaiagents import Agent
from praisonai.bots import TelegramBot
agent = Agent(name="assistant", instructions="Helpful assistant")
bot = TelegramBot(token="...", agent=agent, status_reactions=True)
bot.start()The user sends a message on Telegram; emoji reactions update through queued, thinking, tool, done, or error states.
Quick Start
- Enable with one flag
python from praisonaiagents import Agent from praisonai.bots import TelegramBot agent = Agent(name="assistant", instructions="Helpful assistant") bot = TelegramBot(token="...", agent=agent, status_reactions=True) bot.start() - Customise emoji via dict
python bot = TelegramBot( token="...", agent=agent, status_reactions={ "thinking_emoji": "💭", "tool_emoji": "⚙️", "done_emoji": "🎉", "debounce_delay": 1.0, }, ) - Full control with StatusConfig
python from praisonai.bots import TelegramBot, StatusConfig bot = TelegramBot( token="...", agent=agent, status_reactions=StatusConfig( thinking_emoji="💭", immediate_terminal=True, ), )
How It Works
The user sends a message and watches a single emoji on that message move through each run stage.
Stall Signals
When the agent falls quiet for too long — a slow LLM or a stuck tool — the same reaction slot switches to ⏳ after stall_soft_s (default 20 s) and ⚠️ after stall_hard_s (default 60 s), and any real progress clears the signal immediately.
from praisonaiagents import Agent
from praisonai.bots import TelegramBot
agent = Agent(name="assistant", instructions="Helpful assistant")
bot = TelegramBot(
token="...",
agent=agent,
status_reactions={
"stall_soft_s": 15, # ⏳ after 15s of silence
"stall_hard_s": 45, # ⚠️ after 45s
},
)
bot.start()Label Fallback (channels without reactions)
On channels where capabilities["reactions"] is False — WhatsApp, Email, and Slack in “label” mode — the same phase state machine renders as a single status label the bot edits in place (queued → thinking… → using a tool… → done) instead of an emoji reaction, and the adapter picks the mode automatically from the channel’s capabilities with no extra config.
Configuration Options
| Option | Type | Default | Description |
|---|---|---|---|
queued_emoji | str | "⏳" | Shown when the run is queued |
thinking_emoji | str | "🤔" | Shown while the LLM is generating |
tool_emoji | str | "🔧" | Shown during tool execution |
done_emoji | str | "✅" | Terminal: success |
error_emoji | str | "❌" | Terminal: failure |
debounce_delay | float | 0.5 | Seconds before applying intermediate states |
immediate_terminal | bool | True | Apply done/error immediately |
stall_soft_s | float | 20.0 | Seconds without progress before ⏳ “still working…” |
stall_hard_s | float | 60.0 | Seconds without progress before ⚠️ “taking longer than expected” |
enabled | bool | False | Master switch — off by default; the bot adapter opts in when you pass status_reactions=True |
Best Practices
Keep debounce_delay at 0.3s or higher on shared channels
Avoids hitting reaction rate limits on busy Telegram groups.
Use distinct emoji for tool vs thinking
Helps users tell when an external API call is in progress.
Leave immediate_terminal enabled
Users see done/error states instantly without debounce delay.
Tune stall thresholds to your longest reasonable tool call
If a legitimate tool takes 40 s (web scraping, image generation), raise stall_soft_s to 45–60 s so users don’t see ⏳ while everything is still healthy.
Trust the automatic fallback on Email / WhatsApp
Reactions silently degrade to a status label edit — no per-channel code required.
Custom integrators: use RunStatusController directly
See Run Status Controller for the low-level API.