Skip to content

Telegram Integration

oAI-Web can receive and send Telegram messages via a bot, and dispatch agents in response to trigger phrases.

Setup

  1. Create a bot with @BotFather and copy the bot token
  2. In oAI-Web: Settings → Telegram → enter the bot token and save
  3. Add your Telegram chat ID to the whitelist (Settings → Telegram → Chat Whitelist → Add)
  4. To find your chat ID: message your bot, then check the incoming message — the chat ID is shown

Architecture

The Telegram listener (server/telegram/listener.py) uses long-polling (getUpdates) rather than webhooks. This means: - No public URL required — works on a home network - The server polls Telegram's API for new messages every few seconds - The bot only needs outbound internet access (no inbound connections)

The listener starts automatically at startup if a bot token is configured.

Whitelist

Only chat IDs in the telegram_whitelist table can send messages to or receive responses from oAI-Web. This is enforced before any trigger matching.

Manage chat IDs in Settings → Telegram → Chat Whitelist.

Trigger rules

A trigger rule fires when all tokens in the trigger phrase are present in the incoming message (order-independent, case-insensitive).

Example: trigger "check weather" matches: - "weather check" - "can you check the weather" - "check weather for Oslo"

Does not match: "what's the weather" (missing "check")

When a trigger fires: 1. The matching agent is looked up 2. agent_runner.run_agent_and_wait(agent_id, override_message=message_text) is called 3. The agent's response is sent back to the Telegram chat

Manage triggers in Settings → Telegram → Trigger Rules.

Outbound messages

Agents can send Telegram messages using the telegram tool:

{
  "operation": "send_message",
  "chat_id": "123456789",
  "message": "Your daily summary is ready."
}

The chat_id must be in the telegram_whitelist for the calling user.

Email account routing

Email accounts can optionally route incoming emails to Telegram. If an email account has a telegram_chat_id set: - Every incoming email (that matches trigger rules) triggers both an agent run AND a message to the Telegram chat - The Telegram message includes the sender, subject, and a snippet of the email

If telegram_keyword is set on an account, messages starting with /<keyword> in Telegram are routed to that account's inbox handling.

Bound Telegram tool (email handling context)

When an agent runs in the context of an email handling account, it receives a BoundTelegramTool with the chat_id pre-configured. This means the agent can reply to the Telegram channel associated with that inbox without being told the chat ID explicitly.