Telegram Bot

Capture thoughts into Cortexa directly from Telegram. Send a text message to your bot and it lands encrypted in your vault, embedded for search, with optional auto-summarize and per-source defaults.

Prerequisites

• Cortexa desktop app running
• A Telegram account

Step 1 — Create a Bot with BotFather

1. Open Telegram and search for @BotFather.
2. Send /newbot and follow the prompts to name your bot.
3. BotFather replies with a bot token (a string like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz). Copy it.

Step 2 — Find Your Chat ID

You need your Telegram chat ID so the bot only accepts messages from you.

1. Send any message to your newly created bot.
2. Open this URL in your browser (replace <BOT_TOKEN> with your actual token):

https://api.telegram.org/bot<BOT_TOKEN>/getUpdates

3. In the JSON response, look for "chat": { "id": 123456789, ... }. That number is your chat ID.

Multiple users

You can add multiple chat IDs (comma-separated) if you want the bot to accept messages from more than one Telegram account.

Step 3 — Configure in Cortexa

1. Open the Cortexa app and go to Settings → External → Telegram bot.
2. Paste your bot token in the token field.
3. Enter your chat ID(s) in the chat IDs field (comma-separated if multiple).
4. Enable the toggle.
5. Save.

Step 4 — Restart Cortexa

The Telegram long-poller starts at boot time only, so you need to restart the app after first-time configuration.

On startup, the bot token is validated by calling the Telegram getMe API. If the token is invalid, you will see an error in the trace log (Settings → Storage → Trace).

Step 5 — Send a Message

Send a text message to your bot in Telegram. You should receive a reply:

Captured.

The message is now encrypted in your vault, queued for embedding, and subject to whatever per-source defaults you have configured for the telegram source.

Security

An empty chat ID list rejects all messages. This is by design. If you leave the chat IDs field empty, the bot will ignore every incoming message. You must explicitly list the chat IDs that are allowed to capture.

This prevents unauthorized users from writing to your vault if they discover your bot's username.

Per-Source Defaults

You can configure different auto-actions for Telegram captures in Settings → Notifications → Per-source defaults. For example:

• Always auto-summarize Telegram messages
• Never auto-think on Telegram captures
• Enable auto-share to Hive for Telegram captures

The Telegram poller identifies itself with the telegram source, so per-source defaults apply automatically.

Slash Templates

Slash templates work in Telegram just like in the app. Send:

/idea: distributed caching with Redis sharding

The backend strips the /idea: prefix, applies the template's tags (idea), and overrides the action toggles with the template's defaults. This works because template parsing happens server-side.

Keyword Triggers

Start a message with a trigger phrase and Cortexa runs that agent action on the thought it just captured — for typed text and transcribed voice notes alike. The phrase is stripped before the thought is stored.

Phrase	Action
deep research, research this	Web + vault research
deep think, deep dive, think about this	Full orchestration pipeline
expand	Expand the thought
counterpoint, steelman, devil's advocate	Generate counterpoints
synthesize	Synthesize

For example, send a voice note that starts with "deep research on…" and the bot replies ✅ captured — 🔬 deep research queued. Matching is leading-only and case-insensitive, so a trigger word mid-sentence won't fire. Toggle it off per connection with the Keyword actions switch in Settings → Integrations → Telegram.

Voice & Photos

The bot also accepts voice notes (transcribed via OpenAI Whisper — requires an OpenAI key in LLM settings) and photos (downloaded and attached, with the caption captured as the thought). The raw audio/image is stored as an encrypted attachment.

Limitations

The bot does not support inline queries, commands, or callbacks. It is a pure capture endpoint. Search and retrieval are done through the desktop app, CLI, or MCP tools.

Troubleshooting

Bot doesn't respond — Make sure the Cortexa app is running and you restarted it after configuring the bot. Check the trace log for errors.

"getMe failed" on startup — The bot token is invalid. Double-check the token from BotFather.

Messages ignored silently — Your chat ID is probably not in the allowed list. Verify your chat ID matches what's configured in Settings → External → Telegram bot.

423 Locked while bot is running — When the vault is locked via idle lock, the Telegram poller drops incoming messages with a log entry. Unlock the app to resume captures.