Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Telegram Setup Guide
TL;DR
vibe
Choose Telegram in the wizard, create a bot in @BotFather, paste the token, validate it, then finish the Telegram-side setup.
Step 1: Create a Bot with BotFather
- Open @BotFather in Telegram
- Send
/newbot - Choose a display name
- Choose a username ending in
bot - Keep the generated token page open
If you already created the bot, you can skip straight to copying the token.
Step 2: Paste the Token in Avibe
- Run
vibe - In the setup wizard, choose Telegram
- Paste the bot token from BotFather
- Click Validate Token
If validation fails, make sure you copied the full token and did not include extra spaces.
Step 3: Finish the BotFather Switches
Run these commands in @BotFather and select your bot each time:
/setprivacy/setjoingroups/setcommands
Recommended settings:
/setprivacy->Disableif you want the bot to respond to normal group messages without explicit@mentions/setjoingroups->Enableif the bot should be used in groups or forum-enabled supergroups/setcommands-> publish common commands such as/start,/settings,/new,/resume
The most common Telegram setup issue is leaving privacy mode enabled. In that state, the bot only receives commands, mentions, and replies.
Step 4: Finish Setup, Bind, Then Discover Chats
Avibe discovers Telegram chats from inbound messages. Telegram does not provide a generic "list every chat the bot is in" API.
Important: Telegram DMs are usable, but they stay hidden in the wizard chat-selection UI. The wizard selects discovered groups and forum chats. After setup, the dashboard's Group Settings page also lists forum topics that the bot has seen.
Configure individual forum topics
Open Dashboard → Group Settings → Telegram, then expand a forum group. Every discovered topic initially inherits the group settings. Choose Customize to give that topic its own:
- enabled state and
@mentionrequirement - bound-user-only access policy
- Vibe Agent, model, reasoning, and working directory
- visible message types
Choose Use group settings to delete the override and resume inheritance. Telegram does not provide a complete topic-list API, so a topic appears after the bot receives a message there. The General topic is treated as topic ID 1.
On first setup, do this in order:
- Finish the Avibe setup flow and start the service
- On the final summary screen, copy the first bind command shown there
- Open a DM with the bot and send
bind <code>(or/bind <code>) to become the first admin - After binding, send
/startin the DM to verify direct-message connectivity - If you want to use a group or forum, add the bot there and grant permission to send messages
- For auto-created forum topics, also grant admin or topic-management rights
- Send one message in each target group or forum chat; for forums, sending a message inside the forum helps Avibe discover that chat and later use topic-related behavior there
- In the dashboard group settings page, refresh the Telegram chat list and enable the discovered group or forum chat
If the bot only reacts to commands in groups, go back and verify /setprivacy is really set to Disable.
Step 5: Choose Telegram Defaults
The wizard exposes two important Telegram defaults:
- Require explicit bot targeting in groups
- When enabled, the bot responds only to commands, mentions, or replies
- Good for busy groups
- Forum auto-topic mode
- In forum-enabled supergroups, a new top-level message can create a new topic automatically
- Requires admin or topic-management rights for the bot
Using in Telegram
Direct Messages
- Open your bot in Telegram
- First send
bind <code>(or/bind <code>) using the bind code shown by Avibe setup - Then send
/start - Continue chatting normally
Groups
- Add the bot to the group
- If
require_mentionis enabled, use/start,@botname, or reply-to-bot style messages - If
require_mentionis disabled, the bot can respond to normal group messages too
Forum Topics
- Add the bot to a forum-enabled supergroup
- Ensure it has enough permissions
- Send a message in the target topic so Avibe discovers it
Troubleshooting
| Problem | Fix |
|---|---|
| Token validation fails | Re-copy the token from BotFather and validate again |
| Bot works in DM but not in groups | Run /setjoingroups and confirm it is Enable |
Bot only reacts to commands or @mentions |
Run /setprivacy and set it to Disable |
| Group or forum does not show up in the wizard | Send one message there first, then refresh the Telegram chat list |
| Forum auto-topic does not work | Grant admin or topic-management rights to the bot |
Logs: ~/.vibe_remote/logs/vibe_remote.log
Diagnostics: vibe doctor
Using a Proxy
If Telegram API is blocked in your region, you can configure a proxy server. The easiest way is to set it up in the setup wizard: enter the proxy URL in the "Proxy URL" field before validating your bot token.
Configuration via Setup Wizard
In the Telegram setup wizard (Step 2: Paste the Token), you'll see a "Proxy URL" field below the bot token input. Enter your proxy URL there and click "Validate Token" — the validation will use the proxy automatically.
Configuration via Config File
Alternatively, add proxy_url to your config in ~/.vibe_remote/config/config.json:
{
"mode": "self_host",
"platforms": {
"telegram": {
"bot_token": "YOUR_BOT_TOKEN",
"proxy_url": "socks5://user:[email protected]:1080"
}
}
}
Supported Proxy Types
| Scheme | Type |
|---|---|
socks5:// |
SOCKS5 proxy |
socks4:// |
SOCKS4 proxy |
http:// |
HTTP proxy |
https:// |
HTTPS proxy |
If the Proxy Fails
Avibe does not automatically fall back to a direct connection when
the proxy is unreachable. Telegram requests will fail and the error will be
logged. To recover, fix the proxy, switch proxy_url to a working endpoint,
or remove the proxy_url field if Telegram is reachable directly.
Troubleshooting
| Problem | Fix |
|---|---|
| Bot can't connect | Check proxy URL format and credentials |
| Works then stops | Proxy is down — restart it or remove proxy_url to use a direct connection |
| Token validation fails | Verify proxy allows connections to api.telegram.org |