What the Telegram bridge does
The bridge connects PostPilot on your desktop to your own private Telegram bot. Once paired, you can — from any phone or computer with Telegram — :
- Get live status when the agent finishes a task, hits an error, or pauses waiting for you.
- Compose posts remotely. Send
/post your messagefrom your phone, the desktop agent picks it up and posts to your enabled platforms. - Update standing instructions during the day.
/note today's focus is the new launch— every subsequent post obeys. - Steer a running agent. If it's mid-task and you want it to change direction, just type the steer message.
- Send a photo or video to use on the next post that needs media (Instagram, Facebook, TikTok).
Private to you. The bot you create only talks to you (and PostPilot on your machine). Your bot token is stored encrypted in your OS keychain and never leaves your computer except to call Telegram's official Bot API.
Create your bot with @BotFather
BotFather is Telegram's official bot for creating other bots. Free, takes about 2 minutes.
- Open Telegram. Search for @BotFather and start a chat.
- Send
/newbot. - BotFather asks for a display name. Anything — e.g. My PostPilot.
- Then it asks for a username. Must end with
bot. e.g.my_postpilot_bot. If taken, try another. - BotFather replies with a message containing your HTTP API token. It looks like:
123456789:ABCdefGHIjklMNOpqrSTUvwxYZabcDEFghi - Copy this token. Treat it like a password — anyone with it can control your bot.
Lost the token? Open the chat with BotFather, send /mybots, pick your bot, then API Token. You can also regenerate it from there.
Start a chat with your bot
Telegram bots can only send you messages once you've messaged them first. So:
- In BotFather's reply, click the t.me/<your_bot_username> link, or search for your bot's username in Telegram.
- Open the chat and tap Start (or send any message —
hiworks). - That's it — Telegram now knows you're allowed to receive messages from this bot.
Pair it in PostPilot
- Open PostPilot on your desktop.
- Click Settings in the sidebar, then the Telegram tab at the top.
- Paste your bot token (from Step 1) into the token field.
- Click Discover chat ID. PostPilot fetches your bot's recent chats and lists yours. Click your name.
- Tick Enable Telegram bridge.
- Click Save. The bridge starts polling for messages.
Can't see your chat after clicking Discover? Make sure you sent a message to your bot in Step 2 — Telegram only exposes chats once you've opened them.
Test & tune notifications
- In the Telegram tab, click Test. Within a second or two, your bot should send a "✅ PostPilot connected" message to your Telegram. If that arrives, you're done.
- Below the token/chat ID inputs there are four notification toggles:
- Task events — when a manual post or compose batch completes. Recommended: on.
- Warm-up events — every single warm-up action. Recommended: off. Warm-up runs dozens of actions a day; this will buzz your phone constantly.
- Errors — when something goes wrong (login wall, API failure, hit iteration cap). Recommended: on.
- Awaiting input — when the agent pauses and needs your help (CAPTCHA, 2FA prompt, manual sign-in). Recommended: on.
- Click Save.
Command reference
From the chat with your bot, send any of these. Plain text without a leading slash is added to the session note and delivered as a follow-up to the running agent (if any).
State & control
| Command | What it does |
|---|---|
| /start | Show full menu with all commands. |
| /status | Current agent state: idle, running task X, warm-up queue size, last activity. |
| /stop | Abort the current task AND stop warm-up. |
| /warmup on | Enable & start warm-up. |
| /warmup off | Stop warm-up immediately. |
Live instructions
| Command | What it does |
|---|---|
| /note <text> | Set a persistent instruction (replaces any existing note). Applied to every future agent run. |
| /note | Show the current note. |
| /note clear | Clear the note. |
| /say <text> | One-off follow-up to the running agent. Doesn't touch the note. |
Post (same content to one or more platforms, 15-45s gaps)
| Command | What it does |
|---|---|
| /post <text> | Post to every enabled warm-up platform. |
| /post x <text> | Post to X only. |
| /post x,threads <text> | Post to X and Threads. |
| /post tiktok <text> | Post to TikTok. Needs a video — see "Sending photos & videos" below. |
Platform aliases: x/twitter, r/reddit, t/threads, ig/insta/instagram, fb/facebook, tt/tiktok. Reddit is skipped by /post because it needs a subreddit and title — use the desktop app's compose form or /postall instead.
Postall (unique post per platform from topics, 5-15min gaps)
| Command | What it does |
|---|---|
| /postall <topics> | Agent writes a unique platform-appropriate post for each enabled platform from the topics you provide. |
| /postall x,reddit ai tooling | Same but only to X and Reddit. For Reddit, the agent picks a relevant subreddit and joins it if needed. |
Sending photos & videos
Some platforms (Instagram, Facebook, TikTok) need media. PostPilot picks them up from Telegram automatically:
- Send a photo to the chat (paperclip → image, or just drag-and-drop). It becomes the pending photo. The agent uses it on the next post that needs an image upload.
- Send a video to the chat. Becomes the pending video. Used on the next TikTok upload.
- Either works while the agent is already running — the agent will pick up the new file mid-task.
If the agent reaches a post that needs media and nothing is pending, it'll send you a "🟠 Agent is paused — waiting for you" message and stop. Send a photo or video to resume.
Troubleshooting
The Test button says "✗ Conflict: terminated by other getUpdates request"
This means another instance of PostPilot (or another app using the same bot token) is already polling your bot. Telegram only allows one consumer per bot at a time.
Fix: quit any other PostPilot windows, then restart this one. If you have stale background Electron processes (from a crash), force-quit them from Activity Monitor (Mac) or Task Manager (Windows) and try again.
I'm not getting any messages from my bot
Three things to check:
1. Did you actually click Start on your bot in Telegram? Bots can't message you until you've initiated the chat.
2. Is the bridge enabled? In Settings → Telegram, the Enable Telegram bridge checkbox must be ticked and saved.
3. Are notifications enabled for the type of event you're expecting? Warm-up events are off by default — turn them on if you want to see warm-up posts arrive.
"Discover chat ID" returns no chats
You need to have sent at least one message to your bot recently. Open your bot's chat in Telegram, tap Start (or send hi), then click Discover again.
Note: Telegram only exposes recent chats — usually the last 24h. If you've never messaged the bot or it's been a long time, send a fresh message.
Can I use a group chat instead of a private chat?
Yes. Add your bot to the group, send a message in the group, then click Discover — the group will appear with a negative chat ID. Pick it. Note that anyone in the group can issue commands to your bot, so use a private group you control.
My token leaked — how do I rotate it?
In Telegram, open the chat with @BotFather. Send /mybots → pick your bot → API Token → Revoke current token. BotFather replies with a new token. Paste it into PostPilot's Settings → Telegram, click Save. The old token immediately stops working.
How do I disable Telegram temporarily without losing settings?
Untick Enable Telegram bridge in Settings → Telegram, then click Save. The bridge stops polling. Your token and chat ID stay saved, so you can re-enable later with one tick.
Telegram messages stopped after my Mac went to sleep
PostPilot needs to be running to receive Telegram messages. When your machine sleeps, polling stops. Open PostPilot when you wake your Mac and it'll resume — any messages queued by Telegram in the meantime will arrive on the next poll.