Setup Guide

Step-by-step guide to setting up the Locus Telegram bot.

Prerequisites

• Locus CLI installed and configured — see Installation

• A Telegram account

• A Locus API key — see Workspace Setup

---

Step 1: Create a Telegram Bot

1. Open Telegram and search for @BotFather

2. Send /newbot

3. Choose a name for your bot (e.g., "My Locus Bot")

4. Choose a username (must end in bot, e.g., my_locus_bot)

5. BotFather will give you a bot token — copy it

Keep your bot token secret. Anyone with the token can control your bot.

---

Step 2: Get Your Chat ID

You need your numeric Telegram chat ID to restrict the bot to only respond to you.

1. Start a conversation with your new bot (send any message)

2. Open this URL in your browser (replace YOUR_BOT_TOKEN):

   https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates

3. Find your chat.id in the JSON response

Example response

{
  "result": [
    {
      "message": {
        "chat": {
          "id": 123456789,
          "type": "private"
        }
      }
    }
  ]
}

Your chat ID is 123456789.

---

Step 3: Install the Telegram Bot

npm install -g @locusai/telegram

Verify:

locus-telegram --help

---

Step 4: Configure the Bot

Interactive

locus telegram setup

Follow the prompts to enter your bot token and chat ID.

Non-Interactive

Individual Settings

Verify your configuration:

locus telegram config

---

Step 5: Start the Bot

locus-telegram

The bot is now running. Send /help in your Telegram chat to see all available commands.

---

Running as a Background Service

For 24/7 operation, you'll want to run the bot as a system service. See the self-hosting guides:

• Linux Setup — Runs as a systemd service

• macOS Setup — Runs as a LaunchAgent

---

Configuration Reference

All Telegram settings are stored in .locus/settings.json:

Setting	Description	Required
telegram.botToken	Bot token from @BotFather	Yes
telegram.chatId	Your numeric Telegram chat ID	Yes
telegram.testMode	Enable test mode	No

For CLI configuration details, see locus telegram.

---

Troubleshooting

Bot doesn't respond to commands

1. Check that the bot is running (locus-telegram process is active)

2. Verify your chat ID matches: locus telegram config

3. Make sure you're messaging the correct bot

4. Check that your API key is valid: locus config show

Commands fail with "API key required"

The bot reads configuration from .locus/settings.json. Make sure you've run locus config setup in your project directory and that the bot is started from the same directory.

"Unauthorized" errors

Your bot token may be invalid or expired. Generate a new one from @BotFather and update:

locus telegram set botToken "NEW_TOKEN"