BotLane

Run a Grok-powered bot from Telegram.

Open-source bridge that connects a Grok (xAI) bot to Telegram and lets you drive it straight from chat. One-to-one, in groups, or with scheduled tasks — no server to babysit, no webhooks to configure.

Why it exists

People who run agent bots on X want to reach them from Telegram too — the same bot, the same memory, no extra setup. BotLane is that bridge:

• Dependency-free — runs on plain Node using the built-in fetch. No npm install needed for production.
• 1:1 and group mode — private chats work out of the box; in groups the bot responds only to @mention, /commands, and replies.
• Session memory — per-chat conversation history persisted to disk.
• Secure by default — an allowlist gates who can talk to the bot so your credits don't get drained by strangers.
• Hosted path available — use the open tool locally, or run it on Talocode Cloud under /v1/botlane/* for managed power.

Part of Talocode: open tools people trust, hosted power behind them.

Install

npm install -g @talocode/botlane

Quickstart

export TELEGRAM_BOT_TOKEN=123456:ABC      # from @BotFather
export XAI_API_KEY=xai-xxxx               # from your xAI account

botlane check                             # verify config
botlane run                               # start the bridge

Then open your bot on Telegram, press Start, and send a message. The bot replies using Grok and remembers the conversation.

SDK usage

import { createBotLane } from '@talocode/botlane'

const bot = createBotLane({
  telegramToken: process.env.TELEGRAM_BOT_TOKEN!,
  xaiApiKey: process.env.XAI_API_KEY!,
  systemPrompt: 'You are a terse assistant.',
})

await bot.start()
await bot.sendText(chatId, 'Hello from the bot')
await bot.stop()

Configuration

| Env var | Default | Description | |---------|---------|-------------| | TELEGRAM_BOT_TOKEN | — | Required. Bot token from @BotFather. | | XAI_API_KEY | — | Required. xAI API key. | | BOTLANE_MODEL | grok-3-mini | Model used for completions. | | BOTLANE_POLL_MS | 1000 | Telegram poll interval in ms. | | BOTLANE_ALLOW_EVERYONE | false | Allow any user to talk to the bot. | | BOTLANE_ALLOWLIST | — | Comma-separated user ids or @usernames. | | BOTLANE_SYSTEM_PROMPT | — | System prompt for the bot. |

Commands

| Command | Effect | |---------|--------| | botlane run | Start the bridge (long polling). | | botlane send <chatId> <text> | Send a one-off message from the bot. | | botlane check | Validate env config and print bot identity. | | botlane-mcp | Start the Model Context Protocol server over stdio. | | botlane-api | Start the HTTP API server under /v1/botlane/*. |

MCP server

BotLane ships a dependency-free Model Context Protocol server so agent runtimes (Cursor, Claude Code, OpenCode, Codra) can drive the bot directly.

export TELEGRAM_BOT_TOKEN=123456:ABC
export XAI_API_KEY=xai-xxxx
botlane-mcp

Connect it as an MCP stdio server in your agent runtime, then call:

| Tool | Purpose | |------|---------| | botlane_check | Verify credentials and report bot identity. | | botlane_send | Send a message from the bot to a Telegram chat. | | botlane_history | Read per-chat conversation history. | | botlane_reset | Clear a chat's conversation history. | | botlane_chat | One-off Grok completion (no polling needed). |

HTTP API

Run the bridge as a hosted-style API:

export TELEGRAM_BOT_TOKEN=123456:ABC
export XAI_API_KEY=xai-xxxx
export TALOCODE_API_KEY=your-key        # optional; protects all routes
botlane-api                             # listens on :8787 by default

| Method | Path | Description | |--------|------|-------------| | GET | /v1/botlane/health | Liveness + config summary. | | POST | /v1/botlane/chat | One-off Grok completion. | | POST | /v1/botlane/send | Send a message from the bot. | | GET | /v1/botlane/history | Per-chat conversation history. | | POST | /v1/botlane/reset | Clear a chat's history. |

Auth (when TALOCODE_API_KEY or BOTLANE_API_KEY is set):

Authorization: Bearer $TALOCODE_API_KEY
# or
X-Api-Key: $TALOCODE_API_KEY

Docs

• Architecture & configuration
• Step-by-step example

Related packages

• Tera · pip install talocode-tera
• Codra · pip install talocode-codra
• SearchLane · pip install talocode-searchlane
• StackLane · pip install talocode
• GateLane
• ContextLane · pip install contextlane
• ScreenLane · pip install talocode-screenlane
• MemoryLane
• Tradia · pip install tradia
• DevTool · pip install talocode-devtool
• XProLane · pip install talocode-xprolane
• XSearchLane · npm i @talocode/xsearchlane
• Agent Browser
• InvoiceLane
• GeoLane
• ClipLoop

Talocode ecosystem

| Product | GitHub | Package | |---------|--------|---------| | BotLane (this repo) | github.com/talocode/botlane | npm i @talocode/botlane | | Tera | github.com/talocode/tera | pip install talocode-tera | | Codra | github.com/talocode/codra | pip install talocode-codra | | SearchLane | github.com/talocode/searchlane | pip install talocode-searchlane | | StackLane | github.com/talocode/stacklane | pip install talocode | | GateLane | github.com/talocode/gatelane | — | | ContextLane | github.com/talocode/contextlane | pip install contextlane | | ScreenLane | github.com/talocode/screenlane | pip install talocode-screenlane | | MemoryLane | github.com/talocode/memorylane | — | | Tradia | github.com/talocode/tradia | pip install tradia | | DevTool | github.com/talocode/devtool | pip install talocode-devtool | | XProLane | github.com/talocode/xprolane | pip install talocode-xprolane | | XSearchLane | github.com/talocode/xsearchlane | npm i @talocode/xsearchlane | | Agent Browser | github.com/talocode/agent-browser | — | | InvoiceLane | github.com/talocode/invoicelane | — | | GeoLane | github.com/talocode/geolane | — | | ClipLoop | github.com/talocode/cliploop | — |

More: github.com/talocode · talocode.site · docs.talocode.site

License

MIT © Talocode