GATE Watcher — Telegram Bot

Self-hosted daemon that connects your Telegram Bot to GATE cloud for security processing via long polling. Your bot token never leaves your machine.

How it works

Your Machine (Watcher)              GATE Cloud
┌─────────────────────┐        ┌──────────────────┐
│ Telegram Bot polling │───────>│ Security pipeline │
│ (token stays HERE)   │<───────│ (redact, policy,  │
│                      │ poll   │  audit, forward)  │
└─────────────────────┘        └──────────────────┘

Quick Start (CLI)

cd gate-watcher-telegram-bot
npm install

# Create .env (or pass env vars directly)
cp .env.example .env
# Fill in GATE_KEY, GATE_INTEGRATION_ID, TELEGRAM_BOT_TOKEN

npm start

Embed in Your App (SDK)

npm install @anura-gate/watcher-telegram-bot

const { GateTelegramBotWatcher } = require("@anura-gate/watcher-telegram-bot");

const watcher = new GateTelegramBotWatcher({
  gateKey: "gk-xxx",
  integrationId: "int_xxx",
  botToken: "123456:ABC-xxx",
  sessionId: "my-bot",
});

watcher.on("ready", (botInfo) => {
  console.log(`Telegram Bot connected: @${botInfo.username}`);
});

// Every message after GATE security processing
watcher.on("message", (update, result) => {
  console.log(`From: ${update.message.from.username}, Text: ${update.message.text}`);
  console.log(`Security actions: ${result.securityActions}`);
  console.log(`Blocked: ${result.blocked}`);
});

watcher.on("action_result", ({ action, success, error }) => {
  console.log(`${action}: ${success ? "done" : error}`);
});

await watcher.start();

// Later...
await watcher.stop();

Pool mode (multiple bots)

Manage multiple Telegram bots from a single watcher instance.

const { GateTelegramBotWatcher } = require("@anura-gate/watcher-telegram-bot");

const watcher = new GateTelegramBotWatcher({
  gateKey: "gk-xxx",
  integrationId: "int_xxx",
  // No botToken → pool mode; each session provides its own
});

// Attach to your HTTP server — resolveUser maps requests to userId,
// and resolveToken provides the bot token per user
watcher.attach(server, "/ws/telegram-bot", {
  resolveUser: (req) => req.session?.userId,
  resolveToken: (userId) => getUserBotToken(userId),
});

watcher.on("pool:ready", (userId, botInfo) => {
  console.log(`[${userId}] Bot connected: @${botInfo.username}`);
});

watcher.on("pool:message", (userId, update, result) => {
  console.log(`[${userId}] From: ${update.message.from.username}`);
});

await watcher.start();

SDK Events

Single-session mode

| Event | Args | Description | |---|---|---| | ready | (botInfo) | Bot connected to Telegram | | message | (update, result) | Message received and processed by GATE | | action | (action) | Outbound action received from GATE queue | | action_result | ({ actionId, action, success, result, error }) | Outbound action completed | | gate_error | ({ path, status, error }) | GATE API call failed | | limit_reached | (type) | Plan limit hit | | disconnected | (reason) | Disconnected | | stopped | — | Watcher fully shut down |

Pool mode

All pool events include userId as the first argument.

| Event | Args | Description | |---|---|---| | pool:ready | (userId, botInfo) | Bot session ready | | pool:message | (userId, update, result) | Message for a user's bot | | pool:action | (userId, action) | Outbound action for a user's bot | | pool:action_result | (userId, { ... }) | Action completed for a user's bot | | pool:error | (userId, error) | Session error | | pool:disconnected | (userId, reason) | Bot session disconnected |

SDK Options

| Option | Required | Default | Description | |---|---|---|---| | gateKey | Yes | — | Virtual key (gk-xxx) | | integrationId | Yes | — | Integration ID (int_xxx) | | botToken | Single-session only | — | Telegram bot token from @BotFather | | gateUrl | No | "https://anuragate.com" | GATE cloud URL | | pollInterval | No | 3000 | ms between update polls | | heartbeatInterval | No | 30000 | ms between heartbeats | | sessionId | No | — | Session ID (omit for pool mode) | | sessionLabel | No | — | Human-readable session label | | sessionMetadata | No | {} | Arbitrary metadata for the session |

Setup

1. Open Telegram and message @BotFather
2. Send /newbot and follow the prompts to create your bot
3. Copy the Bot Token BotFather gives you
4. Go to GATE Dashboard → Integrations → Add Integration
5. Select Telegram Bot, copy the Integration ID
6. Copy your Virtual Key from the Keys page

Environment Variables

| Variable | Required | Description | |---|---|---| | GATE_KEY | Yes | Your GATE virtual key | | GATE_INTEGRATION_ID | Yes | Integration ID from the dashboard | | TELEGRAM_BOT_TOKEN | Yes | Bot token from @BotFather | | GATE_URL | No | Custom GATE cloud URL | | WEB_PORT | No | Port for the dev dashboard (CLI only) |

Security model

• Telegram bot token stored in .env on YOUR machine
• GATE cloud never sees or stores your credentials
• All message content passes through GATE's security pipeline
• Billing, limits, and security enforced server-side