Telegram
Last updated:
Telegram integration lets your main agent answer private Telegram messages through a bot.
Note
A Telegram bot is created with BotFather. Oscova uses the saved bot token to long-poll Telegram and accepts only private messages from the saved numeric user ID.
What you need first
Create the bot in Telegram with BotFather and save its token in the built-in Telegram Bot credential slot. The Telegram settings page does not store the token itself.
You also need the numeric Telegram user ID for the one private user allowed to chat with the bot. This is not an @username. Tools such as @userinfobot can show the number.
Start a conversation with the bot in Telegram before expecting replies. Telegram bots cannot initiate the first private conversation with a user.
Configure the page
- Open Settings > Connections > Telegram.
- Turn on Enable Telegram bot at startup only if you want automatic connection on app start.
- Enter the positive numeric Authorized Telegram User ID.
- Select Save Settings.
- Select Start Bot to connect immediately.
The startup toggle saves immediately. User ID changes require Save Settings. Saving a different authorized user stops the bot. Select Start Bot to reconnect with the new authorization. If startup is enabled without a saved user ID, the page turns the toggle off and shows a warning.
Runtime behavior
When running, Oscova listens for private Telegram messages from the authorized user. Group chats and messages from other users are ignored. Text, captions, documents, and photos can become agent input when they pass the same attachment validation used by web chat.
Hooks and tool approvals still apply. Before downloading an attachment, Oscova gives UserPromptSubmit hooks its Telegram-supplied file name, media type, and size. If a hook denies a prompt or tool call, the bot replies with the denial message instead of continuing silently. A prompt denial downloads and stages nothing.
Telegram attachments follow the chat attachment limits: up to 50 usable attachments per message and 10 MB per attachment. Supported files include images, PDFs, and common text formats such as Markdown, TXT, JSON, CSV, XML, YAML, and logs. Unsupported or oversized attachments are skipped rather than downloaded into the run.
Telegram runs use the main agent and its current provider, tools, skills, memory, privacy, and file access. Tool approval prompts can be answered through Telegram when the selected tool policy requires confirmation.
Telegram polling and replies always use Telegram's external network service. A local-only user or agent does not download message attachments, but it does not make the Telegram channel itself offline. Agent replies longer than Telegram's 4,096-character message limit are split into multiple messages.
When a tool or MCP server asks a follow-up question through text elicitation, the next matching Telegram reply from the same private chat is consumed as that answer instead of starting a new agent run.
Telegram runs are saved into the current main-agent chat thread and recorded in metrics. Outbound replies appear in the run's egress audit. Inbound polling and attachment downloads remain outside that ledger. If a new session starts from Telegram, the thread title is set to Telegram.
Troubleshooting
- Start Bot says the token is not configured: create or update the
telegram-botcredential with abotTokenvalue. - Start Bot warns about the user ID: save a positive numeric Authorized Telegram User ID first.
- The bot ignores messages: make sure you are messaging it privately from the saved user ID.
- A reply answered a tool prompt instead of starting a new chat: finish the pending approval or elicitation first, then send a new message.
- No first reply arrives: open the bot conversation in Telegram before using it from Oscova.
- Startup does not connect: confirm the startup toggle and user ID were saved, then restart Oscova Agents.
- The status changes to an error: check that the token is valid and the Oscova host can reach Telegram.