realvco Docs

Connecting Telegram

Telegram is the easiest messaging platform to set up. Completely free, no business account required, no API fees, and syncs across mobile, desktop, and web. We recommend this as your first connection.

Flow Overview

① Create a bot with BotFather       ← 2 minutes
② Copy the Bot Token                ← instant
③ Paste the token in the Admin Panel ← 30 seconds
④ Bind an AI companion (Rose/Ada/Vi) ← pick one
⑤ Send /start to the bot on Telegram ← instant
⑥ Start chatting                     ← done!

Prerequisites

You need:

  • A Telegram account (mobile app or web client)
  • Admin Panel access

Step 1: Create a Telegram Bot

In Telegram, search for @BotFather (official account with a blue checkmark).

[Screenshot: BotFather conversation window showing the official checkmark]

Send /newbot, then answer:

Q1: “Alright, a new bot. How are we going to call it?” → Enter the bot’s display name (e.g., My AI Assistant).

Q2: “Good. Now let’s choose a username for your bot.” → Enter the bot’s username — must end with bot (e.g., my_ai_assistant_bot).

If the username is taken, you’ll be asked to pick another. Suggested format: [your_name]_[purpose]_bot.

BotFather will confirm and send you a Bot Token:

Done! Congratulations on your new bot. ...

Use this token to access the HTTP API:
123456789:ABCdefGHIjklMNOpqrSTUvwxyz

Keep your token secure and store it safely, it can be used by anyone to control your bot.

Token format: digits:alphanumeric (roughly 46 characters).

A Bot Token is equivalent to a password. Anyone who has it can control your bot.

  • Do not post screenshots in public groups
  • Do not paste into public Slack or Discord channels
  • Do not commit to public GitHub repos
  • If leaked, use /revoke in BotFather to invalidate and reissue

Step 2: Configure in the Admin Panel

  1. Sign in to the Admin Panel
  2. Switch to the target companion tab (e.g. Ada (oc-2))
  3. Go to Settings → Messaging → Telegram
  4. Paste the Bot Token
  5. Click Save

[Screenshot: Admin Panel → Ada → Settings → Messaging → Telegram configuration]

The Admin Panel verifies the token immediately. On success it displays:

  • ✅ Bot Username
  • ✅ Bot ID
  • ✅ Webhook Status: Connected

Most failures are caused by stray whitespace or missing characters in the copied token.

Which companion should I bind?

  • Public-facing support → Ada (OpenClaw, strong conversational)
  • Internal ops group → Rose (can run system commands)
  • Data analysis group → Vi (Hermes, runs Python)

One bot binds to one companion. For multiple companions on Telegram, create multiple bots.

Step 3: Start Chatting

Back in Telegram, search for your new bot’s username (e.g. @my_ai_assistant_bot).

Click Start at the bottom of the bot chat window (or send /start).

The AI companion replies with a welcome message. Send any message to start the conversation.

[Screenshot: Telegram bot chat window with a welcome message]

Advanced Configuration

Restrict Access (Allowlist)

By default anyone can message your bot (the username is public). The simplest way to restrict it is to just tell Rose:

“Please limit Ada’s Telegram bot to me only. My Telegram User ID is 123456789.”

Rose handles the underlying configuration.

Get your Telegram User ID: search for @userinfobot, send any message, and it replies with your User ID.

Advanced: manual configuration

If you’re comfortable with a terminal, SSH into the host:

openclaw config set channels.telegram.dmPolicy "allowlist"
openclaw config set channels.telegram.allowFrom '["tg:your_user_id"]'

Using in a Group

Add your bot to a Telegram group:

  1. Group settings → Add member → search the bot username
  2. In BotFather, enable Group Privacy: /mybots → pick the bot → Bot Settings → Group Privacy → Turn off (so the bot can see every message)

Trigger rules in groups:

By default the bot only replies when @mentioned. To change this, tell Rose:

“For the XXX group, let Ada reply to every message — no @mention needed.”

Or manually:

openclaw config set channels.telegram.groups."*".requireMention true
openclaw config set channels.telegram.groups.GROUPID.requireMention false

Streaming Replies (Typewriter)

Stream AI replies word-by-word, like ChatGPT. Tell Rose:

“Switch Ada’s Telegram replies to streaming mode.”

Or manually:

openclaw config set channels.telegram.streaming "partial"

Media Support

Telegram bots support:

  • ✅ Text messages
  • ✅ Images (read automatically — ask “what is this image?”)
  • ✅ Voice messages (auto-transcribed)
  • ✅ Files (PDF, Word, Excel)
  • ✅ Stickers
  • ❌ Video analysis (not supported)

FAQ

Bot Does Not Respond

  1. Check the token — the Admin Panel’s Telegram settings page should show “Connected”
  2. Confirm you sent /start — Telegram bots require /start for the first conversation
  3. Check container status — Ada Dashboard → Overview → container should be Running
  4. Inspect the Activity log — are messages being received? Any errors?
  5. Restart the container — Ada Dashboard → Restart

Responses Are Slow

  • Normal response is 1 to 3 seconds
  • Over 10 seconds suggests a busy model or network issue
  • Check Usage — if token consumption looks normal but slow, the provider may be rate-limiting
  • Switching to a lightweight model (GPT-4o-mini, Claude Haiku) usually speeds things up

Can I Create Multiple Bots?

Yes. Each bot binds to one companion.

Useful combinations:

  • Bot 1 → Ada (public support)
  • Bot 2 → Ada (internal staff only)
  • Bot 3 → Rose (system alerts)

What If My Bot Token Leaks?

Go to BotFather:

/mybots → pick the bot → API Token → Revoke current token

BotFather issues a new token; the old one is invalidated immediately. Remember to update the Admin Panel’s setting.

Can I Change the Bot’s Avatar and Name?

Yes, through BotFather:

/mybots → pick the bot →
  - Edit Bot Picture (avatar)
  - Edit Name (display name)
  - Edit Description (appears at the bottom of the bot chat)
  - Edit About (appears when users tap the avatar)

Next Steps