Connect Telegram chats to your Osaurus agents. Messages sent to your bot get a streaming conversational response by default. Use the /work command to dispatch background multi-step tasks when you need the full agent runtime.
All private chat messages use streaming inference for fast, conversational responses.
- Token-by-token streaming — Calls the host's
complete_streaminference API. Draft updates are pushed to Telegram so the user sees the response being typed out progressively. - Conversation context — The last 20 messages from the chat history are included, giving the model awareness of the ongoing conversation.
- Immediate feedback — A "Thinking..." draft appears instantly while the model generates its response.
Use /work <prompt> for complex, multi-step tasks that benefit from full agent capabilities (tool use, research, file access).
- Background agent dispatch — Your prompt becomes a task that runs asynchronously on the Osaurus agent runtime.
- Real-time progress — In private chats, a real message is created and updated with streaming output. In group chats, typing indicators and status messages show progress.
- Clarification flow — If the agent needs more information, an inline keyboard appears with options the user can tap. The selected answer is forwarded back to the agent automatically.
- Long message splitting — Responses that exceed Telegram's 4096-character limit are split into multiple messages.
Task lifecycle: started -> activity -> progress -> completed / failed / cancelled
Group chat messages always use work mode dispatch since Telegram drafts are only available in private chats. The /work command also works in groups.
- User allowlisting — Restrict which Telegram users can interact with your agent by configuring a comma-separated list of usernames (e.g.
@alice, @bob). Leave blank to allow everyone. - Message history — Every inbound and outbound message is logged to a local SQLite database. Agents can query this history via the
telegram_get_chat_historytool. - Automatic webhook management — The plugin registers and deregisters its Telegram webhook automatically when you configure or change the bot token.
- Secure webhook verification — A random secret token is generated and verified on every incoming webhook request.
You: What's the difference between TCP and UDP?
Bot: TCP is a connection-oriented protocol that... (streams in progressively)
You: Can you give me a simple analogy?
Bot: Think of TCP like a phone call — you dial,... (streams in progressively)
You: /work summarize the top 5 Hacker News stories today
Bot: ⏳ Working on it... (status update)
Bot: ⏳ Fetching HN front page... (status update)
Bot: Here are today's top 5 HN stories:
1. ...
2. ...
You: /work deploy the latest build
Bot: ❓ Which environment should I deploy to?
[ Staging ] [ Production ] [ Dev ]
You: (taps "Staging")
Bot: ✅ Staging
Bot: Deploying to staging... done! Build v2.3.1 is live.
- Open Telegram and message @BotFather
- Send
/newbotand follow the prompts to choose a name and username - Copy the bot token (e.g.
123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)
- Open Osaurus and go to Agents settings (Cmd+Shift+M)
- Create or choose your Agent
- Find the Telegram plugin (make sure it's installed)
- Paste your bot token into the Bot Token field
- The plugin will automatically validate the token and register a webhook with Telegram
Send a message to your bot in Telegram. In private chats, you get a streaming conversational response. Use /work <prompt> to dispatch a background agent task for complex multi-step work.
| Command | Description |
|---|---|
/start |
Start the bot and show a welcome message |
/clear |
Clear conversation history and start fresh |
/work <prompt> |
Dispatch a background agent task for multi-step work |
To make these appear in Telegram's command menu, send /setcommands to @BotFather and enter:
start - Start the bot
clear - Clear conversation history
work - Dispatch a background agent task
The plugin exposes two tools that agents can call during task execution:
| Tool | Description |
|---|---|
telegram_send |
Send a message to a Telegram chat. Supports reply threading and inline keyboard markup. |
telegram_get_chat_history |
Retrieve recent messages from the local message log for a given chat. Returns up to 200 messages with sender info, timestamps, and media metadata. |
| Route | Method | Auth | Description |
|---|---|---|---|
/webhook |
POST | verify |
Telegram Bot API webhook endpoint. Validates the secret token header on every request. |
/health |
GET | owner |
Health check. Returns webhook registration status and bot username as JSON. |
| Key | Type | Default | Description |
|---|---|---|---|
bot_token |
secret | — | Telegram bot token from @BotFather. Required. |
allowed_users |
text | (empty) | Comma-separated Telegram usernames (e.g. @alice, @bob). Leave blank to allow everyone. |
send_typing |
toggle | on | Show a typing indicator while the agent works. Applies to work mode in group chats. |
send_progress |
toggle | off | Edit the status message with activity/progress text. Only applies to work mode in group chats. |
MIT