Skip to main content
The Tuteliq Telegram bot monitors group chats for grooming, bullying, and unsafe content in real time using the Tuteliq API. Add it to any group in seconds or self-host on your own infrastructure.

Add to Telegram

Add the bot to your Telegram group

Landing Page

Features overview and pricing

Self-Host

Clone and deploy on your own infrastructure

​
Installation

Click Add to Telegram above or search for @tuteliq_guardian_bot in Telegram, then add the bot to your group. No code required — configure everything with bot commands. The bot needs the following group permissions:
  • Delete Messages
  • Restrict Members

​
Self-host

git clone https://github.com/Tuteliq/telegram.git
cd telegram
npm install
cp .env.example .env
# Fill in your values (see Self-Hosting section below)
npm run build
npm start

​
Quick start

1

Add the bot to your group

Open the bot profile, tap Add to Group, and select the group you want to protect. Grant it admin permissions (Delete Messages and Restrict Members).
2

Configure your API key

Run /setup in the group. The bot will ask you to open a DM and send your Tuteliq API key there (starts with tq_). This keeps your key private. The key is encrypted at rest with AES-256.
3

Verify the setup

Run /status in the group to confirm the bot is active and view your current configuration.

​
How it works

Messages in the group flow through a multi-stage pipeline:
  1. Crisis keywords — Messages containing crisis phrases (e.g. self-harm, exploitation) trigger an immediate API call for instant analysis.
  2. Grooming buffer — Messages are accumulated per group. When the buffer has enough context from multiple senders, a conversation analysis is sent for grooming detection.
  3. Batch queue — All other messages are batched and sent to the Tuteliq API for efficient bullying and unsafe content detection.
  4. Alert — When a risk score exceeds your sensitivity threshold, an alert is sent as a DM to the group admin with severity, risk score, message excerpt, and recommended action.
  5. Act — Admins take action directly from the alert using inline buttons.
Alerts are sent as direct messages to the admin who configured the bot, keeping moderation activity private from the group.

​
Bot commands

All commands require group admin permissions. Most commands only work inside groups, not in DMs.
CommandDescription
/setupConfigure the bot with your Tuteliq API key (DM-based flow)
/statusView current configuration, stats, and quota usage
/sensitivity <level>Set detection sensitivity level
/resetRemove all Tuteliq configuration from the group
/helpDisplay the help message
/startAlias for help

​
Alert actions

When a threat is detected, the admin DM includes inline buttons:
ActionEffect
DeleteRemoves the flagged message from the group
TimeoutRestricts the user for 5 minutes (no messages, media, or polls)
ReportShows the full incident report with rationale and context
DismissMarks the alert as reviewed without action

​
Sensitivity levels

LevelThresholdBest for
low70%+Minimal alerts, only clear violations
medium50%+Balanced — good default for most groups
high30%+Stricter monitoring, catches more subtle threats
maximum10%+Maximum protection — useful for testing or high-risk communities
Set the level with /sensitivity <level>.

​
Deployment modes

The Telegram bot supports two transport modes:
ModeWhenHow
WebhookProductionSet the WEBHOOK_URL environment variable. The bot receives updates via POST requests.
PollingDevelopmentOmit WEBHOOK_URL. The bot continuously polls Telegram for updates.
Webhook mode is recommended for production as it is more efficient and scales better.

​
Self-hosting

​
Requirements

  • Node.js 20+
  • Telegram bot token from @BotFather
  • Tuteliq API key
  • Firebase project with Firestore enabled
  • Firebase service account key (JSON)

​
Environment variables

# Telegram Bot
TELEGRAM_TOKEN=your-bot-token

# Tuteliq API
TUTELIQ_API_URL=https://api.tuteliq.ai

# Encryption (generate with: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
ENCRYPTION_KEY=your-64-hex-char-encryption-key

# Firebase
GOOGLE_APPLICATION_CREDENTIALS=./service-account.json

# Webhook (optional — omit for polling mode)
WEBHOOK_URL=https://your-domain.com/webhook
WEBHOOK_SECRET=your-webhook-secret

# Server
PORT=8080
NODE_ENV=production
LOG_LEVEL=info

​
Docker

docker build -t tuteliq-telegram .
docker run -p 8080:8080 --env-file .env tuteliq-telegram

​
Cloud Run

gcloud builds submit --config=telegram/cloudbuild.yaml .
Cloud Run deployment uses 256 MiB memory, 1 CPU, and scales to zero when idle.

​
Health check

The bot exposes a health endpoint at GET /health on the configured port (default 8080). It returns 200 with status, transport mode, and bot state: 
{
  "status": "ok",
  "mode": "webhook",
  "bot": "running"
}

​
Next steps

API Reference

Explore the full API specification.

Slack Integration

See the Slack integration for workspace chat protection.