Telegram Integration
Table of contents
- Features
- Setup Guide
- Commands
- Workflow
- Message Handling
- Multiple chats at once
- Access Control (ACL)
- Technical Details
- Markdown Support
- Troubleshooting
- Best Practices
- Next Steps
Telegram bot integration with full feature support.
Features
- Full Bot API Support: Works in groups and private chats
- Markdown Support: Send formatted messages with Markdown, falling back to plain text when Telegram rejects the markup
- Reply Support: Reply to specific messages
- Long Message Support: Auto-chunking for messages > 4,096 characters
- Bot Commands:
/session,/list,/status,/clear,/acl,/allow,/deny - Access Control:
allow_all,whitelistandblacklistmodes, managed from inside the chat - Per-chat Sessions: Every chat can own its own session, private chats get an isolated workspace
- Group Support: Works in both private and group chats
Setup Guide
1. Create Telegram Bot
- Open Telegram and search for
@BotFather - Send
/newbotcommand - Follow instructions to create your bot
- Copy the Bot Token (format:
123456789:ABCdefGHIjklMNOpqrsTUVwxyz)
Keep your bot token secure! Never share it or commit it to version control.
2. Get Chat ID
For Private Chat
- Start a conversation with your bot
- Send a message to the bot
- Visit:
https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates - Find the
"chat":{"id":value in the response
For Group Chat
- Add bot to group
- Send a message mentioning the bot
- Visit the same URL to get the group chat ID
Group chat IDs are typically negative numbers (e.g.,
-123456789).
3. Configure chat.nvim
require('chat').setup({
integrations = {
telegram = {
bot_token = 'YOUR_BOT_TOKEN',
chat_id = 'YOUR_CHAT_ID',
},
},
})
chat_id is the main chat: the one :Chat bridge telegram and the platform-level
session address. It is required — without it the integration does not start.
Optional: access control
require('chat').setup({
integrations = {
telegram = {
bot_token = 'YOUR_BOT_TOKEN',
chat_id = 'YOUR_CHAT_ID',
acl = {
-- 'allow_all' (default) | 'whitelist' | 'blacklist'
mode = 'whitelist',
-- Always allowed, and the only ones who may run /allow, /deny, /acl.
admins = { '123456789' },
whitelist = { '987654321' },
blacklist = {},
},
},
},
})
Numeric user ids are authoritative. An @username entry is accepted as a convenience,
but it is only a fallback: usernames are user-chosen and can be changed or squatted.
Optional: private chats
require('chat').setup({
integrations = {
telegram = {
p2p = {
-- false disables private chats entirely.
enable = true,
-- An explicit list is the whole policy (numeric ids only).
allow = { '123456789' },
-- Root of the per-chat workspaces. Defaults to the first
-- `allowed_path` entry.
cwd_root = '/path/to/project',
},
},
},
})
Optional: pending messages on start
While Neovim is closed the bot keeps receiving messages: Telegram holds them until the bot fetches them. Answering that queue on start would reply to hours of stale requests in one burst, so by default the backlog is skipped:
require('chat').setup({
integrations = {
telegram = {
-- true (default): ignore messages sent while the plugin was down.
-- false: replay them, like the integration behaved before this option.
discard_backlog = true,
},
},
})
The skip costs one extra request at start-up (getUpdates with offset = -1,
which returns only the newest queued update). The cursor is parked on that update
and polling begins just after it, so messages sent once the plugin is up are
answered normally.
Set
discard_backlog = falsewhen the bot must never lose a request — for example when it is the only way to reach the assistant and you restart Neovim often.
Commands
Neovim Commands
| Command | Description |
|---|---|
:Chat bridge telegram |
Bind current session to Telegram chat |
Telegram Commands
| Command | Description |
|---|---|
/session |
Bind current Telegram chat to active chat.nvim session |
/session N |
Bind the chat to session number N from /list |
/list |
List sessions (supports -p N for pages) |
/status |
Show the bound session, provider, model and cwd |
/clear |
Clear messages in the bound session |
/acl |
Show the effective ACL (admins only) |
/allow |
Allow a user — reply to their message (admins only) |
/deny |
Deny a user — reply to their message (admins only) |
/allowand/denyneed a reply to the target’s message, or a raw numeric user id. There is no reliable way to turn an@usernamein text into an id, and a username-based grant would let anyone who takes that name later in.
Workflow
- Configure Telegram bot token and chat ID
- Open chat.nvim and create/start a session
- Run
:Chat bridge telegramto bind the session - In Telegram, send a message to the bot or mention it in a group
- AI response will be sent back to Telegram automatically
Message Handling
Private Chat
Just send a message to the bot:
Hello, how can you help me?
No mention is needed: a private chat has nobody to mention.
Group Chat
Mention the bot to get a response:
@YourBotName What is the weather today?
Replying to one of the bot’s own messages also counts as addressing it.
In groups, the bot only responds when mentioned or replied to, to avoid noise.
Media messages
Text and captions are passed through as-is. Anything else becomes a short marker
([photo], [sticker], [voice], [document], …) so the message still shows up
and the assistant can say what it did not receive.
Multiple chats at once
One bot can serve several chats. Each chat is a container with its own session:
- Group chats keep sharing the Neovim working directory: a group is deliberately a shared workspace.
- Private chats get an isolated workspace under
<p2p.cwd_root>/telegram-<chat_id>, so two users never see each other’s files or git checkout.
chat_id stays the main container: it is what current_session() / set_session()
and the HTTP API address. Chat bindings are visible through the bridge API
(GET /session/:id/bridge), and unbinding clears both levels.
A p2p.cwd_root that points outside allowed_path is registered into it at
runtime, so the file tools accept <p2p.cwd_root>/telegram-<chat_id> without the
user repeating the path in config. Registration is runtime-only: the config file
is untouched and the allowed tree is not widened on the next start.
Because that entry is lost on restart, creating and registering the directory runs on every binding lookup rather than once at provisioning. A restart — or a workspace deleted while the plugin was down — therefore heals on the next message instead of leaving the chat unable to call any file tool.
The session’s working directory is still assigned when the session is created,
so changing p2p.cwd_root does not migrate an existing session.
Access Control (ACL)
By default anyone who can reach a served chat may talk to the bot. Set
integrations.telegram.acl (see the example above) to
restrict who can trigger replies.
| Mode | Behaviour |
|---|---|
allow_all |
Default. Everyone in the served chats may talk to it. |
whitelist |
Only the listed ids (plus admins) may talk to it. |
blacklist |
Everyone except the listed ids may talk to it. |
Notes:
- Admins always pass.
acl.adminsbypasses the ACL entirely and is the only set allowed to run/allow,/denyand/acl, so a whitelist that locked them out can still be repaired from inside the chat. -
Runtime entries win over the mode.
/allowand/denyare persisted in the state file and checked beforeacl.mode, which is what keeps them useful without editing the config first. The full order is:Order Check 1 acl.admins— always allowed2 runtime blacklist — refused 3 runtime whitelist — allowed 4 acl.mode=whitelist/blacklist— applied to the config lists5 Otherwise allowed - Ids first, usernames as fallback. A numeric id in
admins/whitelist/blacklistis authoritative; an@usernameentry is only matched against the sender’s current username, and/allow//denyrefuse a username outright — see the Telegram commands note above. - Recent speakers are cached. Every non-bot speaker is recorded in the state
file (up to 30, newest first) and exposed through
require('chat.integrations.telegram').get_recent_senders(), so user ids can be picked instead of copied out of the Telegram client. - ACL commands answer where they came from. A
/allowtyped in a private chat is answered in that private chat, never announced in the group. Commands from non-admins are dropped silently (logged as a warning) so a group is not spammed, and the bot refuses to change the ACL entry for itself.
Private chat admission
A private chat is one person talking to the bot privately, so it has its own policy
rather than reusing acl.mode:
| Order | Rule |
|---|---|
| 1 | The main chat_id is exempt — it is trusted by definition |
| 2 | p2p.enable = false — refuses every private chat |
| 3 | p2p.allow when set — authoritative, numeric ids only, no fallback |
| 4 | acl.mode = whitelist / blacklist — applied like any other chat |
| 5 | Otherwise allowed (a private chat only exists after somebody opened one) |
The default is “allowed” on purpose: this integration always answered private
chats, and a chat only exists once a person started the conversation with the bot.
An explicit p2p.allow list, on the other hand, is the whole policy — a typo in
one entry must not silently widen access.
- Only the registered peer is trusted. Inside a private container the message
is attributed to
containers[chat_id].peer; a message from any other user id is dropped before the container is registered, so a second person can never inherit that session or workspace.
Technical Details
- API: Telegram Bot API
- Polling: long polling (
getUpdates, 10-second timeout) started every 3 seconds - Pending updates: skipped on start via one
getUpdateswithoffset = -1(discard_backlog = falsereplays them instead) - Message Format: Markdown, retried as plain text when the API rejects the markup
- Message Limit: Auto-chunking for messages > 4,096 characters
- State Persistence:
<storage_dir>/integration/telegram.json— holds the cursor, the runtime ACL grants/denies, the recent-speaker cache and per-chat containers - Bot Detection: Auto-fetches and caches the bot id and username; group mentions stay undetectable until the lookup succeeds
- Deduplication: The last 100 update ids are kept, so a replayed update is never answered twice
Markdown Support
Telegram supports Markdown formatting in messages:
- Bold:
*text* - Italic:
_text_ - Code:
`code` - Pre: `
code block` - Links:
[text](URL)
The AI assistant can use Markdown formatting in its responses. Telegram’s classic Markdown parser rejects unbalanced
*or_, so a message refused with 400 “can’t parse entities” is automatically resent as plain text instead of being lost.
Troubleshooting
Bot Not Responding
Symptom: Bot does not respond to messages.
Solution:
- Verify bot token is correct
- Check if chat_id is correct (private chat or group)
- For groups, make sure bot has read permissions
- Try sending
/startto the bot first - Check the ACL:
/aclworks for admins only, so also look at the runtime log forSkip message (sender not allowed)
Group Messages Ignored
Symptom: The bot works in a private chat but ignores group messages.
Solution:
- Mention the bot (
@YourBotName) or reply to one of its messages - Check the runtime log for
bot_token not configured/ bot identity warnings - Disable group privacy mode in BotFather (see below)
Private Chat Rejected
Symptom: Messages in a private chat get no answer.
Solution:
- The main
chat_idis exempt fromp2pchecks — a second private chat is not - An explicit
p2p.allowlist is authoritative — make sure the sender’s numeric id is in it - With
p2p.enable = false, private chats are disabled entirely - With
acl.mode = 'whitelist', the sender must be whitelisted or an admin
ACL Commands Do Nothing
Symptom: /allow or /deny gets no reply.
Solution:
- Only
acl.adminsmay run them — everyone else is ignored silently (check the log forIgnore ACL command from non-admin) - The command must be a reply to the target’s message, or carry the raw
numeric id:
/allow 987654321 /allowedis not/allow— the command needs a space or the end of the message
State Issues
Symptom: Session binding not working.
Solution:
- Clear state:
:lua require('chat.integrations.telegram').clear_state()
Clearing state also drops the runtime ACL grants/denies and the private-chat peers recorded in the state file. The configured
acllists stay untouched.
Best Practices
1. Use Private Chat for Testing
Start with private chat to verify bot functionality:
Start a private conversation with your bot
2. Disable Privacy Mode for Groups
Disable privacy mode to receive all messages in groups:
Send /setprivacy to @BotFather
Select your bot
Choose "Disable"
3. Create Dedicated Group
Create a dedicated group for AI assistance:
Create group: "AI Assistant"
Add your bot
4. Lock Down Private Chats
In a group you control who is in the room, but a private chat is open to anyone who
finds the bot. Put the numeric ids in p2p.allow once the chat works:
p2p = { allow = { '123456789', '987654321' } }
An empty or missing list serves every private chat the bot receives.
5. Monitor Token Usage
Keep track of your AI provider’s token usage.
Next Steps
- Discord Integration - Setup Discord bot
- Slack Integration - Setup Slack bot
- IM Integration Overview - All IM integrations