Telegram Integration

Table of contents

  1. Telegram Integration
    1. Features
    2. Setup Guide
      1. 1. Create Telegram Bot
      2. 2. Get Chat ID
        1. For Private Chat
        2. For Group Chat
      3. 3. Configure chat.nvim
    3. Commands
      1. Neovim Commands
      2. Telegram Commands
    4. Workflow
    5. Message Handling
      1. Private Chat
      2. Group Chat
    6. Technical Details
    7. Markdown Support
    8. Troubleshooting
      1. Bot Not Responding
      2. Permission Errors
      3. State Issues
    9. Best Practices
      1. 1. Use Private Chat for Testing
      2. 2. Disable Privacy Mode for Groups
      3. 3. Create Dedicated Group
      4. 4. Monitor Token Usage
    10. 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
  • Reply Support: Reply to specific messages
  • Long Message Support: Auto-chunking for messages > 4,096 characters
  • Bot Commands: Support for /session and /clear commands
  • Group Support: Works in both private and group chats

Setup Guide

1. Create Telegram Bot

  • Open Telegram and search for @BotFather
  • Send /newbot command
  • 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',
    },
  },
})

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
/clear Clear messages in the bound session

Workflow

  1. Configure Telegram bot token and chat ID
  2. Open chat.nvim and create/start a session
  3. Run :Chat bridge telegram to bind the session
  4. In Telegram, send a message to the bot or mention it in a group
  5. 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?

Group Chat

Mention the bot to get a response:

@YourBotName What is the weather today?

In groups, the bot only responds when mentioned to avoid noise.

Technical Details

  • API: Telegram Bot API
  • Polling: 3-second intervals via getUpdates
  • Message Format: Markdown support
  • Message Limit: Auto-chunking for messages > 4,096 characters
  • State Persistence: stdpath('data')/chat-telegram-state.json
  • Bot Detection: Auto-fetches and caches bot username

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.

Troubleshooting

Bot Not Responding

Symptom: Bot does not respond to messages.

Solution:

  1. Verify bot token is correct
  2. Check if chat_id is correct (private chat or group)
  3. For groups, make sure bot has read permissions
  4. Try sending /start to the bot first

Permission Errors

Symptom: Bot cannot read messages in group.

Solution:

  1. Ensure bot is added to the group
  2. Check if bot has necessary permissions
  3. Disable group privacy mode in BotFather:
    • Send /setprivacy to @BotFather
    • Select your bot
    • Choose “Disable”

State Issues

Symptom: Session binding not working.

Solution:

  • Clear state: :lua require('chat.integrations.telegram').clear_state()

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. Monitor Token Usage

Keep track of your AI provider’s token usage.

Next Steps