Telegram Integration

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

Hosted bot (recommended)

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

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).

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.

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:

Crisis keywords — Messages containing crisis phrases (e.g. self-harm, exploitation) trigger an immediate API call for instant analysis.
Grooming buffer — Messages are accumulated per group. When the buffer has enough context from multiple senders, a conversation analysis is sent for grooming detection.
Batch queue — All other messages are batched and sent to the Tuteliq API for efficient bullying and unsafe content detection.
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.
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.

Command	Description
`/setup`	Configure the bot with your Tuteliq API key (DM-based flow)
`/status`	View current configuration, stats, and quota usage
`/sensitivity <level>`	Set detection sensitivity level
`/reset`	Remove all Tuteliq configuration from the group
`/help`	Display the help message
`/start`	Alias for help

Alert actions

When a threat is detected, the admin DM includes inline buttons:

Action	Effect
Delete	Removes the flagged message from the group
Timeout	Restricts the user for 5 minutes (no messages, media, or polls)
Report	Shows the full incident report with rationale and context
Dismiss	Marks the alert as reviewed without action

Sensitivity levels

Level	Threshold	Best for
`low`	70%+	Minimal alerts, only clear violations
`medium`	50%+	Balanced — good default for most groups
`high`	30%+	Stricter monitoring, catches more subtle threats
`maximum`	10%+	Maximum protection — useful for testing or high-risk communities

Set the level with /sensitivity <level>.

Deployment modes

The Telegram bot supports two transport modes:

Mode	When	How
Webhook	Production	Set the `WEBHOOK_URL` environment variable. The bot receives updates via POST requests.
Polling	Development	Omit `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"
}

Getting Started

SDKs

Integrations

Verification

Advanced

Compliance

Telegram Integration

Add to Telegram

Landing Page

Self-Host

Installation

Hosted bot (recommended)

Self-host

Quick start

How it works

Bot commands

Alert actions

Sensitivity levels

Deployment modes

Self-hosting

Requirements

Environment variables

Docker

Cloud Run

Health check

Next steps

API Reference

Slack Integration

Add to Telegram

Landing Page

Self-Host

​Installation

​Hosted bot (recommended)

​Self-host

​Quick start

​How it works

​Bot commands

​Alert actions

​Sensitivity levels

​Deployment modes

​Self-hosting

​Requirements

​Environment variables

​Docker

​Cloud Run

​Health check

​Next steps

API Reference

Slack Integration

Installation

Hosted bot (recommended)

Self-host

Quick start

How it works

Bot commands

Alert actions

Sensitivity levels

Deployment modes

Self-hosting

Requirements

Environment variables

Docker

Cloud Run

Health check

Next steps