Table of Contents

• Features and limitations
• How to
• Basics
• Receiving
• Sending
• Set up
• Settings
• Scripts
• set_bot.py
• get_messages.py
• get_user_info.py
• send_message.py

scel-buc (scripts for Telegram bot user client) is a set of scripts to use a Telegram bot to send and receive messages as if it was a regular user account. It's being developed because I lost access to my Telegram account, so it follows the "just make it work" philosophy. It may be refined in future.

scel-buc is distributed under the AGPL-3.0-only license.

Features and limitations

scel-buc can only send and receive unformatted text messages from single and group chats:

• There is no way to send anything other than simple text messages.

• received messages of unsupported types (e.g. audio or animated dice will be logged as [unsupported message type].

• Formatting, including inline links, is stripped from received message without notice. For example, if someone sends the message

  Nobody expects the Spanish Inquisition!

  it will be silently logged as

  Nobody expects the Spanish Inquisition!

Any contribution adding support for unsupported message types is welcome.

How to

Basics

scel-buc sends and receive Telegram messages. Since it works through a Telegram bot, it must receive a message from the user before being able to send one to him.

Receiving

Messages are received by executing the get_messages.py script. It fetches them from Telegram and stores them in on the corresponding chat log file. The chat log file is placed in the path is determined by the chat_path setting; its filename is determined as <chat type>-<chat ID>(-<user/group name>), where:

• <chat type> is SIN for single user chats and GRP for group chats;
• <chat ID> is the chat Telegram ID;
• <user/group name> is the user, if set in the users settings section, or the group name.

The -<user/group name> fragment is used only if it is available, otherwise the filename ends with the <chat ID>.

Important warning: Telegram keeps unfetched messages to bots for 24 hours only; therefore, you should run get_messages.py at least once every 24 hours, otherwise you will lose messages.

Sending

Messages can be sent, one by one, by repeatedly executing the send_message.py script. They are automatically added to the corresponding chat log file, as determined in the Receiving section.

Set up

scel-buc must be run through a Telegram bot account, that can be created by contacting the BotFather. If you plan to use the bot in groups, you must disable the privacy mode before adding it. If you forget to do so, you can disable privacy mode, remove the bot from the group and add it again.

Since scel-buc is meant to be used when you lost access to your regular Telegram account, you must have created a bot account beforehand and stored its token. If you didn't, you can ask someone trusted to create one for you. Remember that whoever creates the bot account can, and is the only one who can, retrieve and change its token at any time, so he can hijack the bot.

Settings

scel-bouc is configured by filling the options in settings.ini. Here's the explanation of what they mean.

• bot section. All settings in this section are mandatory.

  • token: the token of the bot
  • user: the name of the user who will use the bot. This can be any string.

• settings section. All settings in this section are mandatory.

  • chat_path: the absolute path where the cats will be stored. The path must exist and end with the / char. Expansion is not supported.

• users section.

  By default, scel_buc will indicate any user who contacts you with his Telegram user ID.¹ In this section you may add a user_id: user_name entry for any user you communicate with and such a user_name will be used instead of the user_id.

  An example entry can be the following:

  123456789: John Doe
  

• groups section.

  Same as users section but for groups.² If no group_name is given, the name of the group in Telegram will be used. This section is intended to allow you to prevent file names with emojis or other weirdnesses.

  An example entry can be the following:

  987654321: The Spanish Inquisition
  

Scripts

set_bot.py

Configures the bot with the default values for name, description and short description. The picture must be configured through BotFather, as in the bot API there is no method to do it.

Of course, these values can be set to anything else through BotFather.

Despite mitigation, this script hits some kind of rate limit fairly easy: usually running it three times in two minutes is enough to get the calling IP blocked for 24 hours on setMyName method. If this happens and you can't wait, just configure the bot with BotFather.

get_messages.py

Gets all new messages. update_id of the last downloaded message is written to .last_msg to prevent duplicating messages in the logs.

get_user_info.py

Get all available info for given user in given chat. This can be useful if someone contacts the bot but doesn't introduce himself.

For single chats, the chat ID is the same as the user ID.

send_message.py

Send a message.

The recipient ID is the ID of the chat you want to send the message to. For single chats it is the same as the user ID, whereas groups have their own ID.²

Multiline messages are supported. When you are prompted for the content, every time you hit Enter the line is appended to the message and you can begin writng anothe one. When you wrote the last one, confirm the message by hitting Ctrl+D.

---

1. This is because in Telegram picking is not mandatory to pick a username, as well as indicating a first name or a last name (you can give the first, or the last, or both). Therefore, it would be complex to generate a unique identifier based on these values. ↩︎

2. The group ID may include a -: in such a case, the dash must be specified. ↩︎