Do I need a Telegram account to create a bot?

Yes, but you only need a basic free Telegram account — no premium subscription required. The bot is created through @BotFather, which is a special Telegram bot that issues tokens. Your personal Telegram account and the bot are completely separate: the bot gets its own username and identity.

Can multiple people use my Telegram bot?

Yes. Add multiple Telegram user IDs to the allowedUsers array in openclaw.json. Each person messages the bot through their own Telegram account. The agent maintains context per user, so conversations don't mix. Remove a user from the list to revoke their access instantly.

Are my conversations with the bot private?

Messages go from Telegram's servers to your bot, then to your machine. Telegram encrypts messages in transit but does not use end-to-end encryption for bots — Telegram can see message content. If you need end-to-end encryption, use the Signal channel instead. Your AI provider also sees the message content. See Telegram's privacy policy for details.

Why isn't my Telegram bot responding?

Check three things: (1) your Telegram user ID is in allowedUsers in openclaw.json, (2) the Gateway is running — `openclaw gateway status`, and (3) the bot token in your config is correct. Run `openclaw logs --filter telegram` to see any error messages that pinpoint the issue.

Telegram – HowOpenClaw

Telegram is the easiest channel to set up and one of the most reliable to run. No Mac required, no unofficial APIs, no QR codes. Just a bot token from BotFather and you're running. Telegram works on any supported OpenClaw setup — Mac, Linux, Windows, Raspberry Pi, or a $5/month VPS — and costs nothing beyond your AI provider's API fees.

New to OpenClaw? The course module on connecting apps walks through this same Telegram setup step by step, with troubleshooting for every common failure point.

Create your bot

Open Telegram and search for @BotFather
Send /newbot
Choose a display name for your bot (e.g., "My Assistant")
Choose a username ending in bot (e.g., myassistant_bot)
Copy the token BotFather provides — you'll need it in the next step

Find your Telegram user ID

Your Telegram user ID is a number, not your @username:

Message @userinfobot on Telegram
It will reply with your numeric ID

Use this ID in allowedUsers for allowlist-style access.

Configure OpenClaw

Add the Telegram channel to ~/.openclaw/openclaw.json:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN_HERE",
      "dmPolicy": "pairing",
      "groupPolicy": "mention",
      "requireMention": true,
      "allowedUsers": [
        123456789,
        987654321
      ],
      "parseMode": "Markdown"
    }
  }
}

Replace YOUR_BOT_TOKEN_HERE with the token from BotFather and 123456789 with your actual user ID.

Restart and test

openclaw gateway restart

Open Telegram, find your bot by username, and send it a message. It should respond within a few seconds.

If it doesn't respond:

openclaw logs --filter telegram

Important: Bots Are Publicly Discoverable

Telegram bots are publicly searchable by their username. Anyone can find and message your bot. This is why dmPolicy: pairing is recommended — you'll be notified of new users and can approve or deny them before the agent responds.

If you want a stricter setup, use allowedUsers with specific numeric IDs.

Group Chats

To use your bot in a group:

Add the bot to the group (search for its username)
In BotFather, send /setprivacy and select your bot → disable privacy mode (required for group reading)
Set groupPolicy: mention so it only responds when @mentioned

With privacy mode disabled, the bot can read all messages in the group. With requireMention: true, it will only respond when explicitly addressed.

Forum Topics

If you use Telegram groups with Topics enabled (forum-style groups), OpenClaw routes messages to the correct topic. The #General topic (topic ID 1) is handled reliably even when Telegram omits forum metadata — native commands, interactive callbacks, inbound message context, and fallback error replies all route correctly.

Topic Session Routing (v2026.4.12)

As of v2026.4.12, topic-scoped session initialization stays on the canonical topic transcript path when inbound turns omit MessageThreadId. This means:

One topic session no longer alternates between bare and topic-qualified transcript files
Session history remains consistent and traceable
Topic-specific context is preserved across messages

No special configuration is needed. Topic routing works automatically and consistently when Topics are enabled in the group.

Topic Names in Agent Context (v2026.4.14)

As of v2026.4.14, OpenClaw surfaces human-readable forum topic names in agent context, prompt metadata, and plugin hook metadata. Topic names are learned from Telegram forum service messages and persisted to the session sidecar store — so your agent sees the real topic name (e.g. "Support" or "Announcements") instead of a raw numeric ID, even after a restart.

Command-Sync Cache (v2026.4.15)

New in v2026.4.15

The Telegram command-sync cache is now process-local. When the gateway restarts, OpenClaw re-registers the slash command menu with Telegram instead of trusting stale on-disk sync state. This means your bot's command menu stays accurate even if Telegram cleared it out-of-band between restarts.

Photo & Media Sending

When your agent sends images, OpenClaw preflights Telegram's photo dimension and aspect-ratio rules. If an image doesn't meet Telegram's requirements (or metadata is unavailable), it automatically falls back to sending as a document — so photo uploads no longer fail with PHOTO_INVALID_DIMENSIONS.

Markdown Image Syntax in Groups (v2026.4.23)

New in v2026.4.23

Telegram group chats now parse remote markdown image syntax (![alt](url)) into outbound media payloads on the final reply path. Previously, when the model or a tool emitted markdown image syntax instead of a MEDIA: token, group deliveries fell back to plain-text image URLs. Images referenced this way now render natively in the group. (Fixes #66191) Thanks @apezam and @vincentkoc.

Voice Notes & Audio

Voice note transcription in direct messages has been restored (v2026.4.12). When you send a voice message to your bot, it will transcribe the audio and respond naturally — no longer arriving as raw <media:audio> placeholders.

Commands & Threading

Native Telegram commands (like /start, /help) now preserve reply threading for QA verification and testing purposes. Command callbacks are routed to a separate sequentializer lane so approval button clicks resolve immediately instead of deadlocking.

Native Command Auto-Registration (v2026.4.15)

New in v2026.4.15

Plugin-registry-backed auto-defaults for native commands and native skills are now restored. Telegram slash commands keep registering automatically when commands.native and commands.nativeSkills are set to auto (the default). Previously, this was broken and commands could silently stop appearing in the slash command menu after a restart.

Document & File Uploads

New in v2026.4.15

Binary document handling has been significantly improved. When users upload documents such as .mobi or .epub files, leaked binary caption bytes are now stripped from inbound Telegram text handling. This prevents binary content from inflating prompt token counts. Additionally, binary reply context and ZIP-like archive extraction are sanitized so .epub and .mobi uploads can no longer leak raw binary into prompt context through reply metadata or archive-to-text/plain coercion.

Improved Error Handling

Outbound delivery errors now preserve actionable details (e.g., 403 membership/block/kick reasons), and permanently failed chats (such as when the bot has been blocked or kicked) stop retrying automatically instead of looping.

HTML Entity-Encoded Media Tags

QQBot-style media tags with HTML entity-encoded angle brackets (</>) are now correctly parsed and normalized, as are URL slashes in attributes and self-closing media tags.

Recent Improvements (v2026.4.15)

Binary document uploads (.mobi, .epub) no longer leak binary bytes into prompt context or inflate token counts
Native Telegram commands auto-register from the plugin registry when commands.native/commands.nativeSkills are auto
Command-sync cache is now process-local — gateway restarts re-register the slash menu instead of using stale on-disk state

Previous: v2026.4.14

Forum topic names surfaced in agent context and plugin metadata — no more raw numeric IDs
Topic names persisted across restarts via session sidecar store
AAC voice notes remapped to .m4a for upload — AAC audio transcription no longer fails
Read-only status slash commands bypass busy topic turns for faster responses
Heartbeat replies stay in the correct topic when target=last

Previous: v2026.4.12

Voice note transcription in DMs restored — voice messages now transcribe and respond
Photo dimension validation improved — invalid images fall back to document sends
HTML entity-encoded media tags properly parsed
Topic-scoped session initialization on canonical path
Outbound delivery errors preserve actionable details
Permanently failed chats stop auto-retrying
allowFrom sender validation tightened

Using Telegram for work? Slack is better for team workspaces — it has dedicated channel controls, thread replies, and enterprise access management.

Privacy-first use case? Signal offers end-to-end encrypted messaging if confidentiality is a requirement.

Evaluating OpenClaw against other tools? See OpenClaw vs ChatGPT for a full comparison of what self-hosting means vs. using a hosted AI service.

Why Telegram Is Reliable

Unlike WhatsApp, Telegram provides an official Bot API. There's no session that expires, no QR code to re-scan, no unofficial protocol emulation. When the gateway is running, the Telegram channel is running.

It also queues messages during disconnections — if your gateway restarts, it will receive all messages sent while it was offline.

Something not working?

Check the troubleshooting guide for common issues with gateway startup, channel connections, and automations.