Tutorial: Team Telegram Assistant

Commands, package names, and image names on this page come from the open-source project that Mibyan Desktop is built on, and can differ from the Mibyan Desktop installer. For the supported Mibyan install and update path, see Install and update.

This tutorial walks you through setting up a Telegram bot powered by Mibyan that multiple team members can use. By the end, your team will have a shared AI assistant they can message for help with code, research, system administration, and anything else — secured with per-user authorization.

What We’re Building

A Telegram bot that:

Any authorized team member can DM for help — code reviews, research, shell commands, debugging
Runs on your server with full tool access — terminal, file editing, web search, code execution
Per-user sessions — each person gets their own conversation context
Secure by default — only approved users can interact, with two authorization methods
Scheduled tasks — daily standups, health checks, and reminders delivered to a team channel

Prerequisites

Before starting, make sure you have:

Mibyan installed on a server or VPS (not your laptop — the bot needs to stay running). Follow the installation guide if you haven’t yet.
A Telegram account for yourself (the bot owner)
An LLM provider configured — at minimum, an API key for OpenAI, Anthropic, or another supported provider in ~/.mibyan/.env

A $5/month VPS is plenty for running the gateway. Mibyan itself is lightweight — the LLM API calls are what cost money, and those happen remotely.

Step 1: Create a Telegram Bot

Every Telegram bot starts with @BotFather — Telegram’s official bot for creating bots.

Open Telegram and search for @BotFather, or go to t.me/BotFather
Send /newbot — BotFather will ask you two things:
- Display name — what users see (e.g., Team Mibyan Assistant)
- Username — must end in bot (e.g., myteam_mibyan_bot)
Copy the bot token — BotFather replies with something like:
Use this token to access the HTTP API: 7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...
Save this token — you’ll need it in the next step.

Set a description (optional but recommended):

/setdescription

Choose your bot, then enter something like:

Team AI assistant powered by Mibyan. DM me for help with code, research, debugging, and more.

Set bot commands (optional — gives users a command menu):

/setcommands

Choose your bot, then paste:

new - Start a fresh conversation
model - Show or change the AI model
status - Show session info
help - Show available commands
stop - Stop the current task

Keep your bot token secret. Anyone with the token can control the bot. If it leaks, use /revoke in BotFather to generate a new one.

Step 2: Configure the Gateway

You have two options: the interactive setup wizard (recommended) or manual configuration.

Option A: Interactive Setup (Recommended)

mibyan gateway setup

This walks you through everything with arrow-key selection. Pick Telegram, paste your bot token, and enter your user ID when prompted.

Option B: Manual Configuration

Add these lines to ~/.mibyan/.env:

# Telegram bot token from BotFather
TELEGRAM_BOT_TOKEN=7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...

# Your Telegram user ID (numeric)
TELEGRAM_ALLOWED_USERS=123456789

Finding Your User ID

Your Telegram user ID is a numeric value (not your username). To find it:

Message @userinfobot on Telegram
It instantly replies with your numeric user ID
Copy that number into TELEGRAM_ALLOWED_USERS

Telegram user IDs are permanent numbers like 123456789. They’re different from your @username, which can change. Always use the numeric ID for allowlists.

Step 3: Start the Gateway

Quick Test

Run the gateway in the foreground first to make sure everything works:

mibyan gateway

You should see output like:

[Gateway] Starting Mibyan Gateway...
[Gateway] Telegram adapter connected
[Gateway] Cron scheduler started (tick every 60s)

Open Telegram, find your bot, and send it a message. If it replies, you’re in business. Press Ctrl+C to stop.

Production: Install as a Service

For a persistent deployment that survives reboots:

mibyan gateway install
sudo mibyan gateway install --system   # Linux only: boot-time system service

This creates a background service: a user-level systemd service on Linux by default, a launchd service on macOS, or a boot-time Linux system service if you pass --system.

# Linux — manage the default user service
mibyan gateway start
mibyan gateway stop
mibyan gateway status

# View live logs
journalctl --user -u mibyan-gateway -f

# Keep running after SSH logout
sudo loginctl enable-linger $USER

# Linux servers — explicit system-service commands
sudo mibyan gateway start --system
sudo mibyan gateway status --system
journalctl -u mibyan-gateway -f

# macOS — manage the service
mibyan gateway start
mibyan gateway stop
tail -f ~/.mibyan/logs/gateway.log

macOS PATHThe launchd plist captures your shell PATH at install time so gateway subprocesses can find tools like Node.js and ffmpeg. If you install new tools later, re-run mibyan gateway install to update the plist.

Verify It’s Running

mibyan gateway status

Then send a test message to your bot on Telegram. You should get a response within a few seconds.

Step 4: Set Up Team Access

Now let’s give your teammates access. There are two approaches.

Approach A: Static Allowlist

Collect each team member’s Telegram user ID (have them message @userinfobot) and add them as a comma-separated list:

# In ~/.mibyan/.env
TELEGRAM_ALLOWED_USERS=123456789,987654321,555555555

Restart the gateway after changes:

mibyan gateway stop && mibyan gateway start

Approach B: DM Pairing (Recommended for Teams)

DM pairing is more flexible — you don’t need to collect user IDs upfront. Here’s how it works:

Teammate DMs the bot — since they’re not on the allowlist, the bot replies with a one-time pairing code:
🔐 Pairing code: XKGH5N7P Send this code to the bot owner for approval.
Teammate sends you the code (via any channel — Slack, email, in person)

You approve it on the server:

mibyan pairing approve telegram XKGH5N7P

They’re in — the bot immediately starts responding to their messages

Managing paired users:

# See all pending and approved users
mibyan pairing list

# Revoke someone's access
mibyan pairing revoke telegram 987654321

# Clear expired pending codes
mibyan pairing clear-pending

DM pairing is ideal for teams because you don’t need to restart the gateway when adding new users. Approvals take effect immediately.

Security Considerations

Never set GATEWAY_ALLOW_ALL_USERS=true on a bot with terminal access — anyone who finds your bot could run commands on your server
Pairing codes expire after 1 hour and use cryptographic randomness
Rate limiting prevents brute-force attacks: 1 request per user per 10 minutes, max 3 pending codes per platform
After 5 failed approval attempts, the platform enters a 1-hour lockout
All pairing data is stored with chmod 0600 permissions

Step 5: Configure the Bot

Set a Home Channel

A home channel is where the bot delivers cron job results and proactive messages. Without one, scheduled tasks have nowhere to send output. Option 1: Use the /sethome command in any Telegram group or chat where the bot is a member. Option 2: Set it manually in ~/.mibyan/.env:

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="Team Updates"

To find a channel ID, add @userinfobot to the group — it will report the group’s chat ID.

Configure Tool Progress Display

Control how much detail the bot shows when using tools. In ~/.mibyan/config.yaml:

display:
  tool_progress: new    # off | new | all | verbose

Mode	What You See
`off`	Clean responses only — no tool activity
`new`	Brief status for each new tool call (recommended for messaging)
`all`	Every tool call with details
`verbose`	Full tool output including command results

Users can also change this per-session with the /verbose command in chat.

Set Up a Personality with SOUL.md

Customize how the bot communicates by editing ~/.mibyan/SOUL.md: For a full guide, see Use SOUL.md with Mibyan.

# Soul
You are a helpful team assistant. Be concise and technical.
Use code blocks for any code. Skip pleasantries — the team
values directness. When debugging, always ask for error logs
before guessing at solutions.

Add Project Context

If your team works on specific projects, create context files so the bot knows your stack:

<!-- ~/.mibyan/AGENTS.md -->
# Team Context
- We use Python 3.12 with FastAPI and SQLAlchemy
- Frontend is React with TypeScript
- CI/CD runs on GitHub Actions
- Production deploys to AWS ECS
- Always suggest writing tests for new code

Context files are injected into every session’s system prompt. Keep them concise — every character counts against your token budget.

Step 6: Set Up Scheduled Tasks

With the gateway running, you can schedule recurring tasks that deliver results to your team channel.

Daily Standup Summary

Message the bot on Telegram:

Every weekday at 9am, check the GitHub repository at
github.com/myorg/myproject for:
1. Pull requests opened/merged in the last 24 hours
2. Issues created or closed
3. Any CI/CD failures on the main branch
Format as a brief standup-style summary.

The agent creates a cron job automatically and delivers results to the chat where you asked (or the home channel).

Server Health Check

Every 6 hours, check disk usage with 'df -h', memory with 'free -h',
and Docker container status with 'docker ps'. Report anything unusual —
partitions above 80%, containers that have restarted, or high memory usage.

Managing Scheduled Tasks

# From the CLI
mibyan cron list          # View all scheduled jobs
mibyan cron status        # Check if scheduler is running

# From Telegram chat
/cron list                # View jobs
/cron remove <job_id>     # Remove a job

Cron job prompts run in completely fresh sessions with no memory of prior conversations. Make sure each prompt contains all the context the agent needs — file paths, URLs, server addresses, and clear instructions.

Production Tips

Use Docker for Safety

On a shared team bot, use Docker as the terminal backend so agent commands run in a container instead of on your host:

# In ~/.mibyan/.env
TERMINAL_ENV=docker
TERMINAL_DOCKER_IMAGE=nousresearch/hermes-sandbox:desktop

Or in ~/.mibyan/config.yaml:

terminal:
  backend: docker
  container_cpu: 1
  container_memory: 5120
  container_persistent: true

This way, even if someone asks the bot to run something destructive, your host system is protected.

Monitor the Gateway

# Check if the gateway is running
mibyan gateway status

# Watch live logs (Linux)
journalctl --user -u mibyan-gateway -f

# Watch live logs (macOS)
tail -f ~/.mibyan/logs/gateway.log

Keep Mibyan Updated

From Telegram, send /update to the bot — it will pull the latest version and restart. Or from the server:

mibyan update
mibyan gateway stop && mibyan gateway start

Log Locations

What	Location
Gateway logs	`journalctl --user -u mibyan-gateway` (Linux) or `~/.mibyan/logs/gateway.log` (macOS)
Cron job output	`~/.mibyan/cron/output/{job_id}/{timestamp}.md`
Cron job definitions	`~/.mibyan/cron/jobs.json`
Pairing data	`~/.mibyan/pairing/`
Session history	`~/.mibyan/sessions/`

Going Further

You’ve got a working team Telegram assistant. Here are some next steps:

Security Guide — deep dive into authorization, container isolation, and command approval
Messaging Gateway — full reference for gateway architecture, session management, and chat commands
Telegram Setup — platform-specific details including voice messages and TTS
Scheduled Tasks — advanced cron scheduling with delivery options and cron expressions
Context Files — AGENTS.md, SOUL.md, and .cursorrules for project knowledge
Personality — built-in personality presets and custom persona definitions
Add more platforms — the same gateway can simultaneously run Discord, Slack, and WhatsApp

Questions or issues? Open an issue on GitHub — contributions are welcome.

تطبيق ديسكتوب

البداية

استخدام مبيان

الميزات

منصات المراسلة

التكاملات

الأدلة والدروس

دليل المطوّر

المرجع

Tutorial: Team Telegram Assistant

What We’re Building

Prerequisites

Step 1: Create a Telegram Bot

Step 2: Configure the Gateway

Option A: Interactive Setup (Recommended)

Option B: Manual Configuration

Finding Your User ID

Step 3: Start the Gateway

Quick Test

Production: Install as a Service

Verify It’s Running

Step 4: Set Up Team Access

Approach A: Static Allowlist

Approach B: DM Pairing (Recommended for Teams)

Security Considerations

Step 5: Configure the Bot

Set a Home Channel

Configure Tool Progress Display

Set Up a Personality with SOUL.md

Add Project Context

Step 6: Set Up Scheduled Tasks

Daily Standup Summary

Server Health Check

Managing Scheduled Tasks

Production Tips

Use Docker for Safety

Monitor the Gateway

Keep Mibyan Updated

Log Locations

Going Further

​What We’re Building

​Prerequisites

​Step 1: Create a Telegram Bot

​Step 2: Configure the Gateway

​Option A: Interactive Setup (Recommended)

​Option B: Manual Configuration

​Finding Your User ID

​Step 3: Start the Gateway

​Quick Test

​Production: Install as a Service

​Verify It’s Running

​Step 4: Set Up Team Access

​Approach A: Static Allowlist

​Approach B: DM Pairing (Recommended for Teams)

​Security Considerations

​Step 5: Configure the Bot

​Set a Home Channel

​Configure Tool Progress Display

​Set Up a Personality with SOUL.md

​Add Project Context

​Step 6: Set Up Scheduled Tasks

​Daily Standup Summary

​Server Health Check

​Managing Scheduled Tasks

​Production Tips

​Use Docker for Safety

​Monitor the Gateway

​Keep Mibyan Updated

​Log Locations

​Going Further

What We’re Building

Prerequisites

Step 1: Create a Telegram Bot

Step 2: Configure the Gateway

Option A: Interactive Setup (Recommended)

Option B: Manual Configuration

Finding Your User ID

Step 3: Start the Gateway

Quick Test

Production: Install as a Service

Verify It’s Running

Step 4: Set Up Team Access

Approach A: Static Allowlist

Approach B: DM Pairing (Recommended for Teams)

Security Considerations

Step 5: Configure the Bot

Set a Home Channel

Configure Tool Progress Display

Set Up a Personality with SOUL.md

Add Project Context

Step 6: Set Up Scheduled Tasks

Daily Standup Summary

Server Health Check

Managing Scheduled Tasks

Production Tips

Use Docker for Safety

Monitor the Gateway

Keep Mibyan Updated

Log Locations

Going Further