Skip to main content
Connecting Telegram to your Suji instance lets your OpenClaw bot receive and respond to messages on Telegram. Once connected, anyone who messages your Telegram bot will be talking to your OpenClaw agent — it works in both direct messages and group chats.

​
What You’ll Need

Before you start, make sure you have:
  • A Telegram account (any free account works)
  • The Telegram app installed on your phone or desktop, or access to Telegram Web
  • A running Suji instance (see Create Your First Instance if you haven’t set one up yet)

​
Create a Telegram Bot

Every Telegram bot is created through BotFather, Telegram’s official tool for registering and managing bots. You’ll chat with BotFather like a normal Telegram conversation.
1

Open BotFather

Open Telegram and search for @BotFather in the search bar, or click this link directly: @BotFather.BotFather is verified by Telegram and has a blue checkmark next to its name. Make sure you’re messaging the real BotFather and not an impersonator.
2

Start a conversation

Click Start (or type /start) to begin interacting with BotFather. It will reply with a list of available commands.
3

Create a new bot

Type /newbot and send it. BotFather will ask you two things:
  1. A display name for your bot — This is the name users see in chats. It can be anything, like My Store Assistant or Acme Support Bot. You can change this later.
  2. A username for your bot — This is the unique @username that people use to find your bot. It must end in bot (for example: my_store_bot, AcmeSupportBot, or acme_help_bot). Usernames are case-insensitive and cannot be changed after creation.
If the username you want is taken, try adding a prefix or suffix. For example, if support_bot is taken, try acme_support_bot or support_bot_123.
4

Copy the bot token

After you choose a valid username, BotFather will reply with a congratulations message that includes your bot token. It looks something like this:
123456789:ABCdefGHIjklMNOpqrSTUvwxYZ1234567890
The token is made up of two parts separated by a colon: a numeric bot ID and an alphanumeric secret string. Copy the entire token — you’ll paste it into Suji in the next section.
Keep your bot token secret. Anyone who has your token can fully control your bot — read messages, send messages, and change settings. Never share it publicly or commit it to a code repository.
5

Configure privacy mode (for group chats)

By default, Telegram bots in group chats can only see messages that are either directed at them (using /commands) or replies to their messages. This is called privacy mode, and it’s enabled by default.If you want your bot to read and respond to all messages in a group chat (not just commands and replies), you need to disable privacy mode:
  1. Send /setprivacy to BotFather
  2. Select your bot from the list
  3. Choose Disable
BotFather will confirm that privacy mode has been disabled.
If your bot will only be used in direct messages (one-on-one chats), you can skip this step. Privacy mode only affects group chat behavior.
After changing the privacy mode, you need to remove and re-add the bot to any existing group chats for the change to take effect. New groups added after the change will work automatically.

​
Connect to Suji

Now that you have a bot token, connect it to your Suji instance.
1

Go to your instance

Open the Suji dashboard and navigate to the instance you want to connect. Click the Connectors tab.
2

Add a Telegram connector

Click Add Connector and select Telegram from the list.
3

Enter the bot token

Paste the bot token you copied from BotFather into the botToken field. Make sure there are no extra spaces before or after the token.
4

Save

Click Save. The connector status should change to Connected within a few seconds. If it stays on “Connecting” for more than 30 seconds, double-check that your token is correct.

​
Verify the Connection

Once the connector shows Connected, test it out:
  1. Open Telegram and search for your bot by its @username
  2. Click Start to begin a conversation
  3. Send any message — your OpenClaw agent should reply
You can also check the connector status at any time by clicking Sync Status on the Connectors tab in the Suji dashboard.
If this is a new instance, make sure you’ve configured your OpenClaw agent with a system prompt and any necessary settings before testing the connection. An unconfigured agent may not respond as expected.

​
Troubleshooting

If your bot isn’t replying to messages:
  • Check that the instance is running — Open your instance in the Suji dashboard and confirm it shows a Running status. If it’s stopped or in an error state, the bot can’t process messages.
  • Verify the bot token — Make sure you pasted the full token correctly. Even a single missing character will prevent the connection from working.
  • Check the connector status — The Connectors tab should show Connected. If it shows an error, try deleting and re-adding the connector.
  • Look at instance logs — Check the instance logs in the Suji dashboard for any error messages that might indicate what’s going wrong.
  • Make sure you started the bot — You need to press Start in Telegram (or send /start) before the bot can communicate with you. This is a Telegram requirement for all bots.
An error status usually means the bot token is invalid or has been revoked. To fix this:
  1. Open Telegram and go to @BotFather
  2. Send /mybot and select your bot
  3. Check that the bot still exists and is active
  4. If needed, send /revoke to generate a new token (this will invalidate the old one)
  5. In the Suji dashboard, delete the old connector and create a new one with the fresh token
Some delay between sending a message and receiving a reply is normal — your OpenClaw agent needs time to process the message and generate a response. However, if delays are consistently long:
  • Check your instance’s resource usage — High CPU or memory usage can slow down response times. You may need to upgrade to a plan with more resources.
  • Check for network issues — Telegram’s servers may occasionally experience slowdowns. Try again after a few minutes.
  • Review your agent configuration — Complex system prompts or large knowledge bases can increase response times.
If your bot works in direct messages but ignores messages in group chats, privacy mode is likely still enabled. By default, bots in groups can only see commands (messages starting with /) and direct replies to the bot.To fix this:
  1. Send /setprivacy to @BotFather
  2. Select your bot
  3. Choose Disable
  4. Remove the bot from the group and re-add it — this step is required for the change to take effect in existing groups
After re-adding the bot, it should be able to see and respond to all messages in the group.
If your bot token has been compromised or you need a new one for any reason:
  1. Open @BotFather in Telegram
  2. Send /revoke
  3. Select the bot you want to revoke the token for
  4. BotFather will generate a new token and invalidate the old one immediately
After revoking, your existing Suji connector will stop working because the old token is no longer valid. You’ll need to:
  1. Delete the old connector in the Suji dashboard
  2. Add a new Telegram connector with the new token
Revoking a token takes effect immediately. Your bot will stop responding until you update the connector with the new token.