Skip to content

Commit

Permalink
Update README.md to v0.4.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@p-hash
p-hash authored and p-hash committed Aug 1, 2016
1 parent cd6e513 commit 09f6268
Showing 1 changed file with 50 additions and 65 deletions.
115 changes: 50 additions & 65 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,13 @@
#<p align="center">Telegram Proxy Bot
A simple BITM, for [Telegram](https://telegram.org/) acting as some kind of "proxy". Can use it as "virtual" second account for your purposes without revealing your "actual" identity.
#Telegram Proxy Bot
A simple BITM (Bot-In-The-Middle), for [Telegram](https://telegram.org/) acting as some kind of "proxy". Can use it as "virtual" second account for your purposes without revealing your "actual" identity.

Credits to **Groosha** for the actual version.

Credits to [Mr_Gigabyte](https://github.com/mrgigabyte/proxybot) for additional features.

| What user sees | What admin sees |
| --- | --- |
| ![Screenshot](http://i.imgur.com/te66bIa.png) | ![Screenshot](http://i.imgur.com/g3tEa2c.png) |

* [ChangeLog!](#changelog)
* [Prerequisites](#prerequisites)
Expand All @@ -23,6 +26,12 @@ Credits to [Mr_Gigabyte](https://github.com/mrgigabyte/proxybot) for additional
* [Contact](#contact)

##ChangeLog!
####Version0.4.0
* **Major Update**: Replying behavior and usage changed. [Smart availability feature](#available-and-unavailable-feature).
* **Bugs in this version**:
* All strings and pager buttons are waiting for my attention. Not a bug.
* Unfortunately, In-Reply-To feature gone. Maybe I will come back to it.

####Version0.3.0
* **Major Update**: Basic log viewing.
* **Bugs in this version**:
Expand All @@ -42,7 +51,6 @@ Credits to [Mr_Gigabyte](https://github.com/mrgigabyte/proxybot) for additional
3. Simplified user blocking using inline keyboards.
4. Code refactored and beautified.
* **Bugs in this version**: Hopefully no



## Prerequisites
Expand All @@ -53,138 +61,115 @@ Credits to [Mr_Gigabyte](https://github.com/mrgigabyte/proxybot) for additional
* Basic Knowledge about coding of course!
* And the ability to read the manual patiently :D


## How to install
* Get your own bot's token from [@BotFather](https://telegram.me/botfather);
* Get your MongoDB (If you don't want to install it, try online services such as [mLab](https://mlab.com/))
* Find out your account's unique ID (you can use [ID bot](https://telegram.me/my_id_bot) or just send message via Curl or something else and get `message.chat.id` from response JSON);
* Fill in the necessary variables in `config.py`;
* Start bot: `bash launch.sh`


## What's new ???
* You can now examine full message history with one user. Just use *Show Log* button in _usercard_.
* Added **Reply** button to _usercard_. Now it is the only way to reply back to user. Forwards are gone forever.
* [Smart availability](#available-and-unavailable-feature).
* Due to smart availability: removed commands `/available` or `/unavailable`.
* You can now examine full message history with one user. Just use **Show Log** button in _usercard_.
* You can now set Start Message the same way you do with the Block Message and Unavailable Message. New commands are `/setstartmessage` and `/viewstartmessage`
* Bot sends _usercard_ with each user's message (which increases the number of messages, i know. I hope, I'll get to it later). _Usercard_ shows all info about user. Ream more about blocking and unblocking [here](#blocking-and-unblocking-feature).
* Admins can set their status as `/available` or `/unavailable`. This means that when you will not be available bot will notify the user if he/she tries to text you by sending him your unavailable message, just like the way you have a pre-recorded message on answering machines! The bot will however forward you the message. You can set and view your unavailable message by typing `/setunavailablemessage` and `/setunavailablemessage` respectively.
* You can now view the list of all users bot has seen! Type `/viewuserslist`. The list will contain basic info about every user and a command to their usercard.
* You can now view the list of users you've blocked! Type `/viewblocklist`. The list will contain basic info about every user and a command to their usercard.
* You can check your status whether you're currently available or unavailable by typing `/checkstatus`
* `/help` command is also there for admins to see all the available commands
* `/viewblockmessage` and `/setblockmessage` to view and set the block message that the user will see once he/she is blocked
* [In Reply to](#in-reply-to) feature. Admin can now see what message the user has force replied to


## How it works
### Basic Functionality
The idea of this bot is pretty simple: you just place the bot between you and the one you want to chat with. The upside is that no one will find out your unique chat id or some other info (nickname, first name or avatar, for example). They won't also know your last seen time. However, the downside is that you can't initiate chat with someone (Because you're writing from bot and bots can't start chats to prevent spam), so you'll have to ask people to write to your bot first.

![A simple scheme of interaction](https://habrastorage.org/files/4a2/d19/753/4a2d19753eb34073bfda0b872bf228b3.png)

<p align="center"> ![A simple scheme of interaction](https://habrastorage.org/files/4a2/d19/753/4a2d19753eb34073bfda0b872bf228b3.png)

<p align="center">![Screenshot](http://i.imgur.com/YZoiTjd.png)

### Viewing Log
I've added **Show log** button to _usercard_ which turns _usercard_ into list of messages. You can read text messages right in the list. Non-text messages, such as stickers, files, photos, voice, location, etc are converted into command, which will forward you specified message.

So, to view log:

1. Find user, which log do you want to see, in list of users (`/viewuserlist`) or in list of blocked (`/viewblocklist`)
2. Request his _usercard_ by `/userNNNNNN` command, which can be found in lists
2. Request his _usercard_ by pressing user's inline button.
3. Tap **Show log** button

To view non-text messages tap on `/msgABCDEF` commands which would be placeholders for non-text messages in the list.

To reply back to user, you still have to find a message, which is forwarded from this user, and reply to it.
To reply back to user, press **Reply** button.

![Screenshot](http://i.imgur.com/2wEvnjx.png)

### Setting Start Message
You can set Start Message -- the message, which user sees when he/she starts the bot.
Use `/setstartmessage` command for setting it and `/viewstartmessage` for viewing it.


### Blocking and Unblocking Feature
It was messy and complicated for me in Mr_Gigabyte's implementation, so I've fully rewrited it.

There is a message which I call _usercard_. It has all information about user and an inline keyboard with only one button, which allows to block or unblock user. _Usercard_ can be requested by `/userNNNNNN` command, where `NNNNNN` is Telegram user\_id. Bot also send _usercard_ to admin before each user's message. A list of `/userNNNNNN` commands can be found in all users list (`/viewuserlist`) and blocked user list (`/viewblocklist`)
There is a message which I call _usercard_. It has all information about user and an inline keyboard with only one button, which allows to block or unblock user. _Usercard_ can be requested by inline buttons, which could be found in all users list (`/viewuserlist`) and blocked user list (`/viewblocklist`)

Data storage moved from couple text files to MongoDB, which will help us to add functionality in future.

So here are the commands connected to blocking: <br>
* `/setblockmessage` <-- To **set the block text** that the user will see once he/she is blocked <br>
* `/viewblockmessage` <-- To **view** your own block message
* `/viewuserlist` <-- To **view** all users in a list with their `/userNNNNNN` commands
* `/viewblocklist` <-- To **view** blocked users list with their `/userNNNNNN` commands
* `/userNNNNNN` <-- To **view** _usercard_. `NNNNNN` here stands for Telegram user\_id
<br>
So here are the commands connected to blocking:

#### Screenshots:
#####Basic Blocking Functionality:
![screenshot](http://i.imgur.com/wjcE4Yy.png)<br><br>
#####Setting the blocking text:
![screenshot](http://i.imgur.com/1JVLQRr.png)<br><br>
#####Viewing the Block List and the User List:
<p align="cente">![screenshot](http://i.imgur.com/6hXC3lR.png)<br><br>
* `/setblockmessage` <-- To **set the block text** that the user will see once he/she is blocked
* `/viewblockmessage` <-- To **view** your own block message
* `/viewuserlist` <-- To **view** all users in a list
* `/viewblocklist` <-- To **view** blocked users list


### Available and Unavailable Feature
There can be at times when you as an admin are unavailable or don't temporarily have access to the bot, but you at the same time want to notify all the users about your unavailability just like the way we have on answering machines ?
<br>
<br>
**"Joshua is Unavailable! Kindly leave your message after the beep.........."**
<br>
<br>
Keeping this in mind here's the `/unavailable` and `/available` feature!
<br>
You can now set your status as **available** or **unavailable** <br>
<br>
So now the admins set the status by typing:
* `/available` <--- To set the status as available
* `/unavailable` <--- to set the status as unavailable<br>
To check the current status simply send `/checkstatus` to the bot<br><br>

If your status is set to **unavailable** then the bot will simply forward the message to the admin and notify the user about the unavailability of the admin **( by sending an unavailable message)**<br><br>

> "Joshua is Unavailable! Kindly leave your message after the beep.........."
Keeping this in mind here's the **unavailable** and **available** feature!

Your available status is managed automatically. I did this because I always forget to set it back.

Status is set to **available** each time admin replies to user. After **1 hour** of inactivity it resets back to **unavailable**.
The expiration time is adjustable in config file.
To check the current status simply send **/checkstatus** to the bot

If your status is set to **unavailable** then the bot will send the message to the admin (as usually) and notify the user about the unavailability **( by sending an unavailable message)**

To set the unavailable message simply send:
* `/setunavailablemessage`

To view the unavailable message simply send:
* `/viewunavailablemessage`

####Screenshots :
##### Setting Unavailable Message :
![screenshot](http://i.imgur.com/kVegDzP.png)<br><br>
##### Basic Feature :
![screenshot](http://i.imgur.com/uvMbmfg.png)<br><br>
##### Checking Status:
<p align="center">![screenshot](http://i.imgur.com/R3VIqfw.png)<br><br>

##In Reply To:
Well as stated before/in the previous version. The admins were not able to see the text the user has force replied to, since the bot only forwards every new text and not the old ones.. So admin wouldn't know if the user has replied to a previously sent text or not. Now admins can see the previously send message to which the user replied.

###Screenshot:
<p align="center">![screenshot](http://i.imgur.com/FFpAcYF.png)<br><br>


## Notes and restrictions
1. Message formatting (both Markdown and HTML) is not supported.
2. You(Admins) should **always** use "reply" function, because bot will check `message_id` of selected "message to reply".
2. You(Admins) should always press **Reply** button to specify user, who will recieve your reply.
3. Database is needed to store users' statuses and log messages.
4. Supported message types in reply: `text`, `sticker`, `photo`, `video`, `audio`, `voice`, `document`, `location`.
5. To block a user simply tap `Block` button under his _usercard_. It will change its name to `Unblock` and user will be blocked.
5. To block a user simply tap **Block** button under his _usercard_. It will change its name to **Unblock** and user will be blocked.
6. This bot only works in the private chats.
7. You can use the `/help` command to view all the commands which you can use an admin
![screenshot](http://i.imgur.com/hgWuEuz.png)


## Upcoming Features
* Anti-Spam Feature, limiting messages sent per-second
* Broadcast feature for admins, they can broadcast a certain message to selected users they want


## Remember!
I understand, that "proxy" bots can be used to prevent spammers from being reported, so if you encounter such bots that are used to do "bad" things, feel free to report them: [[email protected]](mailto:[email protected])


## F.A.Q
#### 1. Will this bot work in groups/supergroups/channels?
For the time being this bot just works in private chats.

#### 2. Can I use Emojis in my saved messages (start, block and unavailable)?
Yes! You can use **ONLY** emojis or text in your saved messages, you cannot save stickers/gifs or any other media. Hope that links could help in your particular case.


## Contact
You can contact me via my [Proxy Bot](https://telegram.me/phash_bot).<br>
You can contact me via my [Proxy Bot](https://telegram.me/phash_bot)*[]:

**PS: Let me know if you need a new feature/tweak in this bot, please don't hesitate to text me :)**

0 comments on commit 09f6268

Please sign in to comment.