LinBot

LinBot Documentation

Welcome to the official documentation for LinBot. This guide covers everything you need to know to connect your Linear workspace to Telegram, manage user permissions, and use our two-way syncing features.

✨ Important Prerequisites & Constraints

Before you begin, please ensure you meet the following platform requirements:

  • Admin Rights Required: The person installing this integration must be an Admin in the Linear Workspace AND an Admin in the Telegram group.
  • 1-to-1 Mapping: We currently support exactly 1 installation per Linear Workspace and per Telegram group.
  • Topics Must Be Enabled: Two-Way Sync requires Telegram Topics. You must go to your Group Settings and toggle "Topics" to ON. If your group is a standard group, you may need to upgrade it to a Supergroup first.
  • Groups & Supergroups Only: LinBot operates exclusively in Telegram Groups and Supergroups with Topics enabled. It will not work in Telegram Channels, and Direct Messages (DMs) with the bot are not supported.
  • Console Access: For security, only the original installer who authenticated the app will have access to the LinBot Console to manage settings.

🚀 Setup Guide

Follow these steps to get your group connected.

  1. Install the Bot: First, install the LinBot integration directly into your Linear workspace.
  2. Linear Workspace: Log in to the LinBot Console and authenticate with your Linear account.
  3. Select Team: Choose the specific Linear Team you want to sync with your Telegram group.
  4. Bot Token: Create a new bot via @BotFather on Telegram and paste the provided HTTP API Token into the console.
  5. Generate Connection Code: Click to generate your secure /auth code.
  6. Connect the Group: Add your newly created bot to your Telegram group as an Admin, and paste the /auth [your-secret-code] command into the chat.

Note: Your bot must be granted Admin access in the Telegram group. If you wish to use the Two-Way Sync feature, you must also grant the bot "Manage Topics" permissions.

🔒 Enabling 2-Way Sync for Private Teams

LinBot perfectly supports Private Teams right out of the box for creating, searching, unfurling, and updating issues using our standard commands.

However, to protect your company's sensitive data, Linear prevents automated apps from listening to Private Teams by default. If you want to enable the live 2-way thread syncing feature for a Private Team, you will need to add a manual webhook.

How to set it up:

  1. Email us at support@linbot.app with your Linear Workspace Name.
  2. We will immediately reply with your secure Webhook URL.
  3. Go to Linear -> Your Private Team -> Team Settings -> Webhooks.
  4. Click New Webhook, paste the URL we gave you, and check the boxes for "Issues" and "Comments".

That's it! Your private team is now fully synced.

🔐 Access Control & Permissions

By default, all members of your Telegram group have Read-Only access to what the bot actively posts in the chat. However, taking action requires explicit permission.

Automatic User Discovery You do not need to manually add users to the console. LinBot automatically discovers users when they join the Telegram group or send a message.

Granting Permissions Once a user is discovered, the Integrator (Admin) can open the LinBot Console to map their Telegram profile to their Linear account and grant them access to use all bot commands (creating issues, searching, updating) and to unfurl Linear links.

⌨️ Bot Commands & Features

Once permissions are granted, you can use these features directly in your Telegram group.

Smart Unfurling

You don't need a command to share context! Simply paste a full Linear URL (e.g., https://linear.app/acme/issue/ENGG-2), or type an issue ID (e.g., ENGG-61), and LinBot will automatically unfurl it into a rich, formatted preview card right in the chat.

Creating Issues

Use the /issue command to create tickets on the fly. You can add flags for priority (-p) and assignee (-a).

  • /issue [Title] -p high -a me | [Description] — Creates a fully detailed issue.
  • /issue [Title] — Creates an issue with only a title.
  • Reply to Create: Reply to a previous message with /issue [Title] and the bot will use the original message as the issue description!
  • Photo Uploads: Send a photo with the caption /issue [Title] to instantly attach the image to your new ticket.

File & Attachment Uploads

To add an image or file to an existing issue: Upload the file to the Telegram chat, reply to any LinBot Issue Card (or message containing the issue ID) with the caption /file, and it will securely attach to the Linear issue.

Searching Issues

Use the /search command to find tickets without leaving Telegram.

  • /search [keywords] — Search issues by title or description.
  • /search [keywords] -a me — Search only your assigned issues.
  • /search -a @username — Search issues assigned to a specific teammate in Telegram (if mapped in the console).
  • /search -a john.doe@example.com — Search issues assigned to a specific teammate in Linear, even if they aren't in the Telegram group!
  • You can also filter by state using the -s flag (e.g., /search login -s todo).

Quick Updates

Reply directly to any Issue Card in Telegram with these commands to update Linear instantly:

  • /state [name] — Updates the status (e.g., done, in progress).
  • /priority [level] — Changes the priority (e.g., high, low).
  • /assign [me | @username | email] — Reassigns the issue.
  • /comment [text] — Posts a new comment to the issue.
  • /title [new title] — Updates the issue title.
  • /desc [new description] — Updates the issue description.

🔄 Two-Way Thread Syncing

LinBot supports powerful, real-time two-way synchronization using Telegram Topics (Threads). When a sync is started, LinBot creates a dedicated Topic in your Telegram group for that specific issue.

  • Live Updates: Any changes made in Telegram OR Linear—including Due Dates, Labels, Status, Priority, Title, and Description—will sync across both platforms automatically.
  • Public vs. Internal Comments: Replies sent inside the Telegram topic automatically post as comments on the Linear issue. However, comments made in Linear will only sync back to Telegram if they are posted directly in the LinBot's specific comment thread. Other threads in Linear are treated as internal/private and will not sync to the group.
  • Auto-Close: If a synced issue is closed or completed in Linear, LinBot will automatically close the linked Topic in Telegram.

How to Stop a Sync

To permanently stop a 2-way sync for a specific issue, simply Delete the Topic in Telegram. Our system will detect the removal and automatically clean up the database link. If you need to chat about it again later, just hit the Start Sync button in the main chat to create a fresh thread!

Warning for Telegram Users: When a sync is started, LinBot creates a comment in Linear that says "🧵 Telegram Sync Started". Please do not delete this root comment in Linear. If it is deleted, the sync for that specific topic will break, and you will need to click "Start Sync" again in Telegram to generate a fresh thread.