Bot Status Reactions

Show agent run progress as an emoji reaction on the user’s message

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

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

1. Enable with one flag

   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()
   
2. Customise emoji via dict

   bot = TelegramBot(
       token="...",
       agent=agent,
       status_reactions={
           "thinking_emoji": "💭",
           "tool_emoji": "⚙️",
           "done_emoji": "🎉",
           "debounce_delay": 1.0,
       },
   )
   
3. Full control with StatusConfig

   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

Reactions auto-skip on channels where capabilities["reactions"] is False (WhatsApp, Email). On Slack, Unicode emoji map to Slack :text_name: form (e.g. 🤔 → thinking_face).

Telegram’s reaction API is set-based — remove_reaction clears all bot reactions on the message rather than a specific emoji. This is a Telegram API limitation.

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.

Related

Channel Capabilities

Which channels support reactions

Typing Indicators

Complementary typing feedback

Streaming Replies

Live token-by-token responses