Connect a Telegram bot

Add your Telegram bot as an agent, prove it with its About text, and know how our attacker talks to it.

Before you start: your plan must include Telegram, and you must be able to edit the bot in @BotFather. See Plans and usage.

​

How it works

Your agent is a Telegram bot. Our attacker writes to it as a Telegram user account, not as a bot, because on Telegram a bot cannot start a chat with another bot. The attacker sends the text exactly as written, waits for the bot’s answer, and hands the answer back for the next turn.

​

Before you start

• The bot’s user name, for example @AcmeHelpBot. It ends in “bot”.
• The bot answers a private message from a Telegram user it has not seen before.
• A test copy of the bot, if the live bot acts on real systems. See Test modes.

​

Steps

1. Add the agent

   On the Agents tab press Add an agent. Under Where we talk to it pick Telegram. Fill in Your bot’s user name. See Add an agent.

2. Put the code in the About text

   On the Connection tab press Copy next to the code. In Telegram open @BotFather, send /setabouttext, pick the bot and paste the code. Other words around it are fine.

3. Press Check now

   We read https://t.me/<bot name> and look for the code. The pill turns to Proven yours. You can remove the code afterwards.

4. Set rules, sign and plan

   Continue as for any agent: Rules, the testing agreement, Run tests.

​

How a conversation runs on Telegram

Rule	Value
Message sent	The attacker’s text, nothing added
Wait for an answer	Up to 4 minutes
Answer counted as finished	After 8 seconds with no new or edited message from the bot
Several messages	Joined into one answer
Answer length	The first 16,000 characters are kept
A late piece	A message the bot sends after we stopped reading is added to the next answer, for up to 30 minutes

​

What a test can show

A bot is reached on its real channel. Unless you connect our test tools to a test copy, we judge each answer from the words alone, so a finding is capped at Moderate. See Test modes.

​

Problems

Check now says it did not find the code in the About text

Open https://t.me/<bot name> in a browser. The page must show the bot’s user name and the About text with the code. @BotFather sometimes takes a minute to publish. Then press Check now again.

The bot name is refused

It must be 5 to 32 letters, digits or underscores and end in “bot”. Type it with or without the @.

The test runs but every message fails

The bot did not answer within 4 minutes. Send it a private message from a personal Telegram account you have never used with it. If it stays silent, check the bot is running and answers new users.

See also Troubleshooting.