What this gives you
Two directions between your phone and your computer. They are switched on separately, and only one of them is on by default.
Reporting. A run tells your chat when it starts, when it stops to ask you something, when it finishes, and when it fails. A live card keeps updating while the agent works.
Prompts and answers. You send text, a photo, or a voice note from the phone and Cortex runs it on the computer as if you had typed it. When the agent asks you a question, you answer it from the phone too. This is a remote control for your computer, which is why it has its own switch and starts switched off.
What Telegram can never do: approve a command. A run waiting for approval waits for you at the computer. Questions are different: when the agent stops to ask you something, you can answer it from the phone, as long as Allow prompts is on. See Answering the agent's questions.
Telegram is bundled with the Cortex subscription, the same way OCR and web search are. The IDE itself stays free with your own API keys.
Before you start
About five minutes, once. Four things need to be in place.
- Cortex Desktop 3.0.70 or later, on Windows or Linux, is installed and running on the computer. Earlier builds have no Telegram section, or only part of it.
- You are signed in and your subscription is active. Without it, pairing is refused. See pricing.
- Telegram is installed on your phone and you are signed in.
- You know which project folder you want open in Cortex. Section 7 explains why that matters.
Telegram works fully on Windows and Linux with Cortex Desktop 3.0.70 or later: run reports, prompts, photos, voice notes and answering the agent's questions. Every step below is the same on both. macOS: not available yet.
Create the bot with BotFather
The token comes from BotFather, a bot that Telegram itself runs. There is no website and no API key page.
- On your phone, open Telegram and search for
@BotFather. Open the one with the blue verified check. - Press Start, then send
/newbot. - BotFather asks for a name. This is the display name, anything you like, for example
My Cortex. - BotFather asks for a username. It must be unique across all of Telegram and must end in
bot, for exampleMariamCortex_bot. - BotFather replies with a line that contains your token. That long string is the password to your bot.
- Never share it. Not in a chat, a screenshot, a support ticket, or a public repository. Anyone holding it can control the bot.
- If it leaks, go back to BotFather, send
/revoke, and pick the bot. A new token is issued and the old one stops working immediately. - A pasted chat link or a row of dots is refused with "That does not look like a BotFather token."
Optional but worth doing: in BotFather, send /setdescription and /setuserpic so the chat is recognisable later.
Using more than one computer? Create one bot per computer, with a different username for each, for example CortexWorkBot and CortexHomeBot. One bot cannot serve two computers at the same time. Section 11 explains why, and what breaks if you try.
Add the token to Cortex
Nothing is sent to Telegram at this point. Saving the token just stores it.
- In Cortex, open File, then Settings... (or press
Ctrl+,). - In the left sidebar, click Telegram.
- Under Bot token, paste the token into the Token from BotFather field.
- Press Save.
What you should see: the token is replaced by twelve dots and a Change button. That is normal. The token is kept in the encrypted vault on this computer and is never sent back to the settings page, so it can be read only by Cortex itself.
| Message | What it means |
|---|---|
| A token is already saved | You do not need to paste it again. Press Change only to replace it. |
| Paste a token from BotFather first | The field was empty. |
| That does not look like a BotFather token | The string is truncated or has extra characters. Copy it again from BotFather. |
Pair your phone
Saving a token is not the same as linking a chat. The pairing code is what links one specific chat to this computer.
- Stay in Settings, then Telegram. Under Pairing, press Show code.
- An eight character code appears, for example
AB3D7K9Q. Cortex is now listening for it. - On your phone, open a private chat with your own bot: search the username you created in section 3, then press Start.
- Send exactly
/pair AB3D7K9Q, with your own code. - The bot replies to confirm, and the status card at the top of the settings page switches to paired.
| Item | Behaviour |
|---|---|
| Where to pair | Private chat with the bot only. A group is refused, because every group member shares one chat id and would inherit your agent. |
| Code alphabet | 8 characters from 23456789ABCDEFGHJKLMNPQRSTUVWXYZ. There is no 0, O, 1 or I, so a code read off the screen cannot be mistyped. |
| Must include the prefix | /pair AB3D7K9Q works. Sending only the code is answered with "Send the code as /pair CODE". |
| Wrong code | The bot replies "That code does not match" to each of the first five wrong attempts, then stops replying to wrong codes. The code itself is not cancelled: the right code still works until it expires. |
| Code lifetime | Choose in Code is valid for: 1 hour (default), 24 hours, 7 days, 30 days, 90 days, or no limit. |
| One code, one chat | With Reusable code off, which is the default, the code is used up after the first successful pairing. |
| Reusable code | With Reusable code on, the code keeps working until it expires, so you can move the pairing to a new phone by sending the same /pair code from it, without going back to the computer. The pairing moves to the new chat and the old chat is told. Only switch it on with a short Code is valid for, because anyone who has the code can move the pairing. |
| One chat at a time | Once a chat is paired, Show code is refused with "already paired". Press Unpair first to move to another phone. That extra click is deliberate: it stops anyone holding a fresh code from silently taking the channel. |
| App must be running | Pairing happens while Cortex is open and the code is still valid. If you close Cortex first, the code cannot be accepted. |
Pressing Show code a second time replaces the code shown before it. The older code stops working at that moment.
Choose what gets sent
Still in Settings, then Telegram, under What to send. Everything here applies the moment you change it, with no Save button.
| Setting | What it does |
|---|---|
| Notifications on | The master switch for reporting. Turning it off keeps the pairing, so you can silence the phone without redoing setup. While Allow prompts is on, the agent's questions still come through, so you can answer them. |
| Run started | One message when a run begins. |
| Blocked on you | The run is waiting for an answer or an approval. Sent even during quiet hours, because this is the one message that needs you. A question arrives with its options, ready to answer (section 7). |
| Run finished | Duration, file counts, and the final state of the live progress card. |
| Include the answer | Appends the final answer to the finished message, capped at 2500 characters so one run stays one message. It can contain file paths and code, so turn this off if the chat is not private to you. |
| Run failed | The error message, shortened. |
| Quiet hours | Silences progress messages between two local times on the computer. A window that crosses midnight works. "Blocked on you" still gets through. |
Press Test message to send one right now. It ignores quiet hours and the event list, so it is the fastest way to confirm the token, the pairing and the chat are all working.
Prompts from your phone
Under Prompts from Telegram, switch on Allow prompts. It is off by default on purpose: with it on, anyone holding your unlocked phone can start work on your computer and answer the questions the agent asks.
What is accepted
- Only the paired chat is accepted. A message from any other chat is ignored with no reply at all.
- Text becomes a prompt. Anything up to 4000 characters is accepted.
- A photo becomes a prompt with the image attached. The caption becomes the prompt text. With no caption, Cortex uses "What is in this image?". Photos need a model that can see images.
- A voice note is transcribed first, then treated as a normal prompt. The language is the one chosen next to the microphone in Cortex.
- Files, stickers, video, and other media are refused, with a short reply saying what is supported.
- Six prompts per minute, per chat. That is a flood guard, not a typing limit.
What happens when you are already busy
If a run is already going when a prompt arrives, the prompt waits in a queue of three instead of being refused. A photo cannot wait, so it is refused while a run is in flight and you are asked to resend it after.
If Cortex was closed when you sent a prompt, or the app was busy restarting, a message that is more than two minutes old when Cortex receives it is not run. Firing yesterday's request the moment the app opens would be a surprise, so you get a reply asking you to send it again. This only applies to messages Cortex could not receive in time: a prompt already waiting in the queue behind a run is never dropped for age.
Commands and reactions
/status replies with what Cortex is doing right now, or "Cortex is idle." /help lists the commands.
Any other slash command is refused, so a typo cannot become a task.
A text prompt gets a check mark when the agent takes it. A voice note gets an eye reaction immediately, so you know it arrived while it is still being transcribed, then the check mark once it is accepted. A message with neither reaction was not accepted, and the bot's reply says why.
Answering the agent's questions
Sometimes the agent stops and asks you to choose, for example which database to use. With Allow prompts on, the question comes to the phone with every option numbered and a button for each:
Cortex needs your answer
Which database should the app use?
1. PostgreSQL - Server database
2. SQLite - File database
Reply with a number, or type your own answer.
Below the message: one button per option, 1. PostgreSQL and 2. SQLite.
Answer in any of three ways:
- Reply with the number, for example
2, to pick that option. - Tap the option's button.
- Type your own answer, for example "use MySQL instead". Any reply that is not an option number is sent as your answer, the same as typing in the question card's own box.
The answer goes to the question card on the computer, the card closes, and the run carries on. The phone message then changes to Answered from Telegram, and its buttons disappear. If the agent asks several questions at once, they arrive one at a time: answer the first and the next one follows.
- Whichever side answers first wins. Answer on the computer and the phone message changes to Answered in Cortex. A reply sent after that gets "That question is already closed."
- While a question is open, your next text message is its answer, not a new prompt. With no question open, a message is a prompt as usual.
- A question that is not answered within five minutes closes, and the agent carries on without that answer. A question left open when the run ends is marked closed on the phone.
- With Allow prompts off, the phone still shows the question and its options, but you answer it in Cortex.
- Approvals stay on the computer. A message asking to approve a command has no buttons, and no reply can approve it.
Answering from Telegram needs Cortex 3.0.70 or later, on Windows or Linux.
Whichever project is open in Cortex at that moment. Telegram has no project of its own and no project is stored with the pairing. If you switch projects on the computer, the next prompt from the phone runs in the new project, and the progress card shows the new project name. Conversation history does not carry across projects.
Limits
Everything is capped, so a phone left unlocked cannot run up a bill or flood a chat.
| Limit | Value |
|---|---|
| Prompt length | 4000 characters |
| Prompts per minute | 6, per chat |
| Queued prompts while a run is active | 3 |
| Message sent while Cortex was not listening | Not run if it is more than 2 minutes old when Cortex receives it (Cortex was closed, or prompts were off). A prompt waiting in the queue behind a run is kept, however long the run takes. |
| Photo size | 4 MB |
| Photo caption | 1024 characters |
| Voice note length | 180 seconds |
| Voice note size | 4 MB (a 180-second note is far smaller, so the length is the limit you will meet) |
| Answer included in "finished" | 2500 characters |
| Live card update rate | At most one edit every 4 seconds |
Security and privacy
The short version: the token stays on your computer, only one chat can talk to the bot, and Telegram cannot approve anything.
| Concern | How it works |
|---|---|
| Where the token lives | In the encrypted credential vault on the computer, never in the plain settings file. The settings page shows dots, not the value. |
| Who can see the token | Only Cortex. It is never uploaded to our servers and never written to logs. |
| Where traffic goes | Directly from the computer to api.telegram.org over HTTPS. Cortex uses long polling, so there is no webhook, no public URL, and no inbound port. |
| Who can send prompts | Only the one paired chat. Everyone else is ignored silently. |
| Can Telegram approve things | No. Approving a command needs the computer. Telegram can answer the agent's questions, only from the paired chat and only while Allow prompts is on. |
| Subscription | Required. If the plan lapses, the bot freezes and tells the paired chat once how to renew. Renewing turns it back on by itself, with no re-pairing. |
| Voice notes | Transcribed through the same speech service the microphone button uses in Cortex, not by Telegram. |
Use Unpair, which forgets the chat and cancels any open code. If the phone is lost, also sign that Telegram account out from another device.
Change, pause, or remove
Everything in this table applies the moment you change it, with no Save button.
| Action | Effect | Token kept? |
|---|---|---|
| Notifications on switched off | Stops all reporting. Pairing and prompt settings stay. The agent's questions still arrive while Allow prompts is on, so they can be answered. | Yes |
| Allow prompts switched off | The phone can no longer start runs. Reporting still works. | Yes |
| Unpair | Forgets the chat and cancels any open pairing code. Pairing again needs only a new code, no token paste. | Yes |
| Remove bot | Unpairs and deletes the token from this computer. Nothing is left behind, so you will need the BotFather token again. | No |
Removing the bot on the computer does not delete the bot on Telegram. To delete the bot itself, use BotFather and send /deletebot.
Two computers, one Telegram account
You can run Cortex on two computers and use the same Telegram account for both. What differs is whether you need prompts on both, or only reports.
| What you want | What to do |
|---|---|
| Reports from both computers to the phone | One bot is enough. Both computers send to the same chat. Nothing conflicts. |
| Prompts from the phone on one computer only | One bot is enough. Turn on Allow prompts on that computer and leave it off on the other. A computer with prompts off never listens for messages, so the two never fight. |
| Prompts from the phone on both computers | One bot per computer. This is the only clean setup. |
Why one bot cannot serve two computers
Telegram tracks which messages have been delivered per bot, not per computer. When two installations poll the same bot, both ask for updates on the same token, and Telegram answers only one of them, refusing the other with 409 Conflict: terminated by other getUpdates request.
The installation that wins takes the message and moves the delivery marker forward. The other never sees it. So with a single bot, a prompt from the phone runs on whichever computer happened to poll first, which is luck rather than a choice. Some messages are lost entirely, with no error on the phone.
This line repeats in the log on the affected computer, at %USERPROFILE%\.cortex\logs\cortex.log on Windows or ~/.cortex/logs/cortex.log on Linux:
[Telegram] getUpdates refused: 409 Conflict: terminated by other getUpdates request
Cortex does not detect this. The refusal is written to the log and the poller simply continues every three seconds, so the bot looks silent rather than broken.
The worst case is pairing. If you press Show code on the second computer and send /pair CODE, the first installation can collect that message first. It has no code waiting, so it discards the message silently, and the second computer stays unpaired with no explanation.
Setting up two bots: in BotFather, send /newbot a second time with a different username, paste the first token on computer A and pair it, then paste the second token on computer B and pair that bot's chat. The same Telegram account works for both, and either computer can be removed without touching the other.
Troubleshooting
Symptoms in the order people hit them. Find yours and read the one line under it.
Code never accepted
Cortex must be open, and the code must still be valid. Press Show code again and send /pair with the new code.
"Already paired" and no code appears
A chat is already linked. Press Unpair first, then Show code.
"Pair Cortex in a private chat with this bot, not in a group."
You paired inside a group. Open the bot's private chat instead.
No messages arrive, but pairing worked
Check Notifications on, check the individual event switches, and check Quiet hours. Send Test message to isolate which one is blocking.
Prompts from the phone do nothing
Allow prompts must be on, and Cortex must be running. Check that the message came from the paired chat, not a group.
"Cortex is busy with a run"
A run is in progress. Wait, or press Stop in Cortex. Text queues up to three; photos cannot queue.
"Cortex was not listening when this was sent"
The app was closed, or prompts were off, and the message is older than two minutes. Send it again.
"Cortex needs a subscription"
The plan is not active. To renew, open Cortex, then Help, then Upgrade to Pro (the same item renews a lapsed plan), or renew from your plan page. The bot resumes by itself within a minute of renewal.
The answer is not in the finished message
Include the answer is off, or the answer is longer than the cap and the message says so.
The token works but nothing at all happens
Check the computer's internet connection and any firewall or proxy that blocks api.telegram.org. Corporate networks sometimes do.
Prompts run on the wrong computer, or vanish
Two computers are paired to the same bot. Check for 409 Conflict in the log, then give each computer its own bot. See section 11.
Logs for diagnosis are in %USERPROFILE%\.cortex\logs\cortex.log on Windows and ~/.cortex/logs/cortex.log on Linux. Lines starting with [Telegram] are the ones that matter.
Common questions
The questions people ask before switching it on, rather than after something breaks.
Does the Telegram bot need a public IP address or an open port?
No. Cortex sends outgoing requests to api.telegram.org and uses long polling. There is no webhook, no URL to publish, and no inbound port to open, so a normal home or office network is enough.
Can Telegram approve a command or answer a question for me?
It can answer questions, but it cannot approve commands. With Allow prompts on, a question the agent asks arrives with numbered options: reply with a number, tap a button, or type your own answer, and the run carries on. Approving a command still needs the computer, and a run waiting for approval waits there.
Is my bot token stored on Cortex servers?
No. The token is kept in the encrypted credential vault on your own computer, is never uploaded to our servers, and is never written to logs. The settings page shows dots instead of the value.
Can I use the same Telegram account on two computers?
Yes, but prompts need one bot per computer. Reports alone work with a single bot sending to the same chat. With two computers polling one bot, Telegram answers only one of them and refuses the other with a 409 Conflict, so a prompt runs on whichever machine happened to poll first.
Do I need a paid plan for the Telegram bot?
Yes. Telegram is bundled with the Cortex subscription, the same way OCR and web search are. The IDE itself stays free with your own API keys. If the plan lapses the bot freezes and tells the paired chat once, and renewing turns it back on with no re-pairing.
Does Telegram transcribe my voice notes?
No. Voice notes are transcribed through the same speech service the microphone button uses in Cortex, not by Telegram. The language is the one chosen next to the microphone.
What happens to a prompt I sent while Cortex was closed?
A message that is more than two minutes old when Cortex receives it is not run, because firing yesterday's request the moment the app opens would be a surprise. You get a reply asking you to send it again. A prompt already waiting in the queue behind a run is kept, however long the run takes.
Which computers does Cortex on Telegram work on?
Windows and Linux, with Cortex Desktop 3.0.70 or later. Everything works the same on both: run reports, prompts, photos, voice notes and answering the agent's questions. macOS is not supported yet.