Bee Box documentation · directory: https://beebox.run/docs/capabilities/ · index: https://beebox.run/docs/capabilities/index.md · root: https://beebox.run/llms.txt

# Telegram

A box is a directory of your data, kept under version control with a full
history of changes (using git); a card is a markdown file with a structured
header; the agent is the coding agent (Claude Code or Codex) that operates the
box. Telegram is a way to reach the box that does not require opening a
browser.

**What it does for you**

- Lets you message the box from Telegram, on your phone or desktop, and get
  the agent's replies in the same chat.
- Works in a private chat with the bot or in a group, and the agent can
  choose to stay quiet on group chatter that is not directed at it.
- Delivers proactive messages from the box (a scheduled task's result, an
  alert) to you on Telegram, alongside or instead of browser notifications.
- Catches up on messages sent while your server was offline instead of
  losing them.

**What it needs**

A Telegram bot token, created through Telegram's BotFather and pasted into
the box's admin page; no config file to edit by hand. See the install
directory: [../install/index.md](https://beebox.run/docs/install/index.md).

**How it works, briefly**

Incoming messages accumulate on a `chat-thread` card, one per Telegram chat,
and each new message creates a job for the agent to process. Outbound
messages are written as a `telegram-message` card and sent, then deleted,
the next time the connector runs, both to check for missed messages and to send
anything queued.

**Limits**

A message the connector could not deliver is recorded with its error rather
than silently dropped, but it is not retried forever. The documentation does
not describe a way to reach the box over Telegram before a bot is connected
through the admin page.

**Go deeper**

[../reference/connectors.md](https://beebox.run/docs/reference/connectors.md),
[../reference/cards/chat-thread.md](https://beebox.run/docs/reference/cards/chat-thread.md),
[../reference/cards/telegram-message.md](https://beebox.run/docs/reference/cards/telegram-message.md),
[../reference/chat-voice.md](https://beebox.run/docs/reference/chat-voice.md)