Update README
This commit is contained in:
parent
2d058020a0
commit
af82083cfe
163
README.md
163
README.md
|
|
@ -3,17 +3,24 @@ gitea: none
|
|||
include_toc: true
|
||||
---
|
||||
|
||||
`scel-buc` (`sc`ripts for T`el`egram `b`ot `u`ser `c`lient) 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 a couple of tool to use a Telegram bot to send and receive
|
||||
messages as if it was a regular user account. It was being developed because I
|
||||
lost access to my Telegram account, so it followed the "just make it work"
|
||||
philosophy. It was slightly refined and it will hoepfully be more in future.
|
||||
|
||||
`scel-buc` is distributed under the [AGPL-3.0-only license](./LICENSE).
|
||||
|
||||
`scel-buc` means _`sc`ripts for T`el`egram `b`ot `u`ser `c`lient_. I don't know
|
||||
if the stuff can still be considered a set of scripts but I can't come up with
|
||||
another stupid acronym anyway.
|
||||
|
||||
## Features and limitations
|
||||
|
||||
`scel-buc` can only send and receive unformatted text messages from single and
|
||||
group chats:
|
||||
`scel-buc.py` is a CLI tool to send and receive messages. It is the main piece
|
||||
of the repository.
|
||||
|
||||
`scel-buc.py` 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
|
||||
|
|
@ -32,41 +39,73 @@ group chats:
|
|||
|
||||
Any contribution adding support for unsupported message types is welcome.
|
||||
|
||||
If an unsupported message is received, its content can be retrieved by
|
||||
accessing [Telegram's bot API](https://core.telegram.org/bots/api#getupdates)
|
||||
manually, _before `scel-buc` is used another time. After that, the message is
|
||||
gone._
|
||||
|
||||
## Caveats
|
||||
|
||||
1. `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.
|
||||
2. Telegram keeps unfetched messages to bots [for 24 hours
|
||||
only](https://core.telegram.org/bots/api#getting-updates); therefore, you
|
||||
should run fetch them at least once every 24 hours, otherwise you _will_
|
||||
lose messages.
|
||||
|
||||
## 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.
|
||||
Messages are stored in the path defined in the [settings](#settings) and
|
||||
organized in HTML files. Open `index.html` in any browser and navigate to
|
||||
single chats.
|
||||
|
||||
#### Receiving
|
||||
CSS is very poor. Any contribution improving it is welcome.
|
||||
|
||||
Messages are received by executing the [`get_messages.py`](#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](#settings); its filename is determined as `<chat
|
||||
type>-<chat ID>(-<user/group name>)`, where:
|
||||
`scel-buc` is CLI tool with very clear commands and arguments. Here's the CLI
|
||||
help.
|
||||
|
||||
- `<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](#settings), or the group name.
|
||||
```
|
||||
$ scel-buc -h
|
||||
usage: scel-buc [-h] {get-updates,build-chats,send-message} ...
|
||||
|
||||
The `-<user/group name>` fragment is used only if it is available, otherwise
|
||||
the filename ends with the `<chat ID>`.
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
|
||||
**Important warning:** Telegram keeps unfetched messages to bots [for 24 hours
|
||||
only](https://core.telegram.org/bots/api#getting-updates); therefore, you
|
||||
should run `get_messages.py` at least once every 24 hours, otherwise you _will_
|
||||
lose messages.
|
||||
Subcommands:
|
||||
{get-updates,build-chats,send-message}
|
||||
get-updates receive new updates
|
||||
build-chats write the chats to HTML
|
||||
send-message send a message
|
||||
```
|
||||
|
||||
#### Sending
|
||||
```
|
||||
$ scel-buc.py get-updates -h
|
||||
usage: scel-buc get-updates [-h]
|
||||
|
||||
Messages can be sent, one by one, by repeatedly executing the
|
||||
[`send_message.py`](#send_message-py) script. They are automatically added to
|
||||
the corresponding chat log file, as determined in the [Receiving](#receiving)
|
||||
section.
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
```
|
||||
|
||||
```
|
||||
$ scel-buc.py build-chats -h
|
||||
usage: scel-buc build-chats [-h]
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
```
|
||||
|
||||
```
|
||||
$ ./scel-buc.py send-message -h
|
||||
usage: scel-buc send-message [-h] --id ID [--text TEXT]
|
||||
|
||||
options:
|
||||
-h, --help show this help message and exit
|
||||
--id ID ID of the chat
|
||||
--text TEXT message text. If omitted, the default text editor is opened to
|
||||
compose the message.
|
||||
```
|
||||
|
||||
### Set up
|
||||
|
||||
|
|
@ -83,17 +122,21 @@ 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.
|
||||
|
||||
Also, if your account
|
||||
[auto-deletes](https://telegram.org/privacy#10-4-account-self-destruction) all
|
||||
your bots are lost.
|
||||
|
||||
### Settings
|
||||
|
||||
`scel-bouc` is configured by filling the options in
|
||||
`scel-buc` is configured by filling the options in
|
||||
[`settings.ini`](./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.
|
||||
- `chat_path`: the absolute path where the chats will be stored. The path
|
||||
must exist and end with the `/` char. Path expansion is _not_ supported.
|
||||
- `users` section.
|
||||
|
||||
By default, `scel_buc` will indicate any user who contacts you with his
|
||||
|
|
@ -115,48 +158,32 @@ retrieve and change its token at any time, so he can hijack the bot.
|
|||
```
|
||||
987654321: The Spanish Inquisition
|
||||
```
|
||||
- `user_returned` section. If you use [`user-returned.py`](#user-returned) all
|
||||
settings in this section are mandatory.
|
||||
|
||||
## Scripts
|
||||
### `set_bot.py`
|
||||
This section is meant to inform your contacts who got used to converse with
|
||||
you through the bot that you are back and they should go back to your normal
|
||||
account.
|
||||
|
||||
Configures the bot with the default values for name, description and short
|
||||
description. The picture must be configured through
|
||||
[BotFather](https://t.me/BotFather), as in the bot API there is no method to do
|
||||
it.
|
||||
- `owner_id`: your Telegram user ID.
|
||||
- `send_sender`: whether the bot must send you a message specifing the
|
||||
original sender before forwarding a mesage to you. Must be a boolean value.
|
||||
- `redirect_msg`: the message to send to people contacting the bot. Line
|
||||
break is supported by indenting the following lines, formatting is _not_.
|
||||
|
||||
Of course, these values can be set to anything else through
|
||||
[BotFather](https://t.me/BotFather).
|
||||
## `user-returned.py`
|
||||
|
||||
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](https://t.me/BotFather).
|
||||
This is a very simple bot to use when you are back on Telegram with a regular
|
||||
account. It:
|
||||
|
||||
### `get_messages.py`
|
||||
1. automatically answer _each_ _private_ message redirecting the user to your
|
||||
regular account;
|
||||
2. forwards all _private_ messages to your regular account
|
||||
|
||||
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.[^group-id-dash]
|
||||
|
||||
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`.
|
||||
It requires `pyhon-telegram-bot`, you can install the correct version from
|
||||
[`requirements.txt`](./requirements.txt)
|
||||
|
||||
To answer immediately to the messages, the bot must keep running.
|
||||
|
||||
|
||||
[^why-user-id]: This is because in Telegram picking is not mandatory to pick a
|
||||
|
|
|
|||
|
|
@ -3,7 +3,6 @@ token:
|
|||
user:
|
||||
|
||||
[settings]
|
||||
proxy:
|
||||
# chat_path must exist and and with "/"
|
||||
chat_path:
|
||||
|
||||
|
|
|
|||
Reference in New Issue