Skip to main content

Telegram

The Telegram integration lets you send notes to Coeus from your phone. You set up a Telegram bot, link it to Coeus, and then send messages to the bot: they show up as notes.

What you need​

Telegram is a free messaging app. It's available for iPhone, Android, Mac, Windows, and Linux. If you don't have it yet, download it at telegram.org and create an account — it takes about two minutes.

Once you have Telegram, you'll create a personal bot. A bot in Telegram is just an automated account you can message. Telegram lets anyone create one for free through a built-in tool called BotFather. You don't need any coding knowledge. BotFather walks you through it and gives you a token (a long string of characters) that Coeus uses to connect to your bot.

Why this exists​

Coeus is a desktop app. When you're not at your computer and you want to capture something quickly, you need another way in. I use Telegram because it's always on my phone and I was already using it.

You can run Telegram in two ways:

  • Desktop runtime: Telegram works while the desktop app is running.
  • Headless runtime: Telegram works while coeus-headless run is running, without opening the UI.

Setup​

Step 1: Create a Telegram bot​

  1. Open Telegram and search for @BotFather
  2. Send /newbot
  3. Follow the prompts: give your bot a name and a username
  4. BotFather gives you a bot token. Copy it.

Step 2: Add the token to Coeus​

  1. Open Settings → Integrations → Telegram Bridge
  2. Toggle it on
  3. Paste your bot token
  4. Click Save
  1. Click Generate link code in the settings
  2. A short code appears (e.g. ABCD1234)
  3. Open Telegram, find your bot, and send it: /link ABCD1234
  4. The bot replies confirming it's linked

Now you're connected.

What you can send​

Text messages: Any message you send the bot becomes a note.

Voice messages: Send a voice note. Coeus will try to transcribe it and save the transcript as a note. If you're using local transcription, Telegram voice-note format may fail; switching transcription mode to OpenAI API in Settings → Integrations → Speech & Transcription handles those voice notes more reliably.

Photos: Send a photo. It gets imported as an attachment.

Documents: Send a file (PDF, image, etc.). It gets imported as an attachment and indexed.

URLs: Send a link. Coeus imports the page as a note, same as pasting a URL in the desktop app.

Asking questions​

You can also ask questions through Telegram. Send a message like "What did I write about last week's meeting?" and the bot searches your notes and replies.

The bot uses the AI provider you have configured in Coeus. It only works with the Anthropic API or OpenAI-compatible API: not with agent runtimes like Claude Code.

Headless runtime​

If you want Telegram-only operation, run:

cargo run --bin coeus-headless -- run

By default, headless uses the same Coeus config and keychain secrets as the desktop app. You can override config path with --config /path/to/.coeus.json.

For non-interactive startup (launchd, CI runner, server session), set the bot token in an env var so headless does not depend on an unlocked keychain:

export COEUS_TELEGRAM_BOT_TOKEN="<your-bot-token>"
cargo run --bin coeus-headless -- run

COEUS_TELEGRAM_BOT_TOKEN takes precedence over keychain token storage.

If you want one universal secret backend (desktop + CLI + headless), you can opt into encrypted local secrets with age:

export COEUS_SECRET_BACKEND=age
export COEUS_SECRETS_PASSPHRASE="<strong-passphrase>"
cargo run --bin coeus-headless -- run

Optional:

export COEUS_SECRETS_FILE="/path/to/.coeus.secrets.age"

When COEUS_SECRET_BACKEND=age, Coeus stores secrets in the encrypted age file instead of keychain.

Bot commands​

CommandWhat it does
/helpShows available commands
/statusShows whether the bot is connected and which AI provider is active
/forgetClears the bot's conversation memory (not your notes)
/link CODELinks a new Telegram account

Privacy​

The bot only responds to the account you linked it to. Anyone else who messages your bot gets no response. The bot token is stored in your operating system's keychain.

Your conversation with the bot stays in memory (up to a few hundred messages) so it has context for follow-up questions. The /forget command clears this memory.

If you use COEUS_TELEGRAM_BOT_TOKEN, your token is sourced from process environment instead of keychain. If you use COEUS_SECRET_BACKEND=age, secrets are read from the encrypted age store.

Unlinking​

To unlink your Telegram account: Settings → Integrations → Telegram → Unlink. You can re-link with a new code at any time.