Telegram message forwarder (client API)

Functionality

• Live forwarding and updating messages
• Source and target channels/chats/topics (one-to-one, many-to-one, many-to-many) mapping
• Incoming message filters: word replacing, forward formating, skipping by keyword and more

Prepare

1. Create Telegram App

2. Obtain API_ID and API_HASH

   

3. Get SESSION_STRING

   SESSION_STRING can be obtained by running login.py with provided API_ID and API_HASH environment variables. ❗ DON'T USE your own account.

4. Setup Postgres database or use InMemoryDatabase with USE_MEMORY_DB=true parameter in .env file

5. Fill .env with your data

   .env-example contains the minimum environment configuration to run with an in-memory database.

   .env overview

   ###########################
   #    App configuration    #
   ###########################
   
   # Telegram app ID
   API_ID=test
   # Telegram app hash
   API_HASH=test
   # Telegram session string (telethon session, see login.py in root directory)
   SESSION_STRING=test
   # Use an in-memory database instead of Postgres DB (true or false). Defaults to false
   USE_MEMORY_DB=false
   # Postgres credentials
   DATABASE_URL=postgres://user:pass@host/dbname
   # or
   DB_NAME=test
   DB_USER=test
   DB_HOST=test
   DB_PASS=test
   # Logging level (debug, info, warning, error or critical). Defaults to info
   LOG_LEVEL=info

6. Setup mirror forwarding config:

   mirror.config.yml-example contains an example config: to set up a filter, specify the name of the filter (should be accessable from ./telemirror/messagefilters) and pass named parameters with the same types but in yaml syntax. Example:

   - ForwardFormatFilter:  # Filter name under telemirror/messagefilters
       # Filter string argument
       format: "{message_text}\n\nForwarded from [{channel_name}]({message_link})"
   
   - SkipUrlFilter:
       skip_mention: false # Filter bool argument
   
   - UrlMessageFilter:
       blacklist: !!set    # Filter set argument
           ? t.me
           ? google.com

   ./.configs/mirror.config.yml or .env (limited) can be used to configure mirroring:

   ./.configs/mirror.config.yml mirroring config overview

   # (Optional) Global filters, will be applied in order
   filters:
     - ForwardFormatFilter: # Filter name under ./telemirror/messagefilters
         format: ""           # Filters arguments
     - EmptyMessageFilter
     - UrlMessageFilter:
         blacklist: !!set
           ? t.me
     - SkipUrlFilter:
         skip_mention: false
   
   # (Optional) Global settings
   disable_edit: true
   disable_delete: true
   mode: copy # or forward
   
   # (Required) Mirror directions
   directions:
     - from: [-1001, -1002, -1003]
       to: [-100203]
   
     - from: [-1000#3] # forwards from topic to topic
       to: [-1001#4]
   
     - from: [-100226]
       to: [-1006, -1008]
       # Overwrite global settings
       disable_edit: false
       disable_delete: false
       mode: forward
       # Overwrite global filters
       filters:
         - UrlMessageFilter:
             blacklist: !!set
               ? t.me
         - KeywordReplaceFilter:
             keywords:
               "google.com": "bing.com"
             regex: false # treat keywords as plain text
         - SkipWithKeywordsFilter:
             keywords: !!set
               ? "stopword"
             regex: true # treat keywords as regex expr

   .env mirroring config overview

   ###############################################
   #    Setup directions and filters from env    #
   ###############################################
   
   # Mapping between source and target channels/chats
   # Channel/chat id can be fetched by using @messageinformationsbot telegram bot
   # Channel id should be prefixed with -100
   # [id1, id2, id3:id4] means send messages from id1, id2, id3 to id4
   # id5:id6 means send messages from id5 to id6
   # [id1, id2, id3:id4];[id5:id6] semicolon means AND
   CHAT_MAPPING=[-100999999,-100999999,-100999999:-1009999999];
   
   # (Optional) YAML filter configuration thru single-lined env string (new lines (\n) should be replaced to \\n), other filter settings from env will be ignored
   YAML_CONFIG_ENV=
   
   # Remove URLs from incoming messages (true or false). Defaults to false
   REMOVE_URLS=false
   # Comma-separated list of URLs to remove (reddit.com,youtube.com)
   REMOVE_URLS_LIST=google.com,twitter.com
   # Comma-separated list of URLs to exclude from removal (google.com,twitter.com).
   # Will be applied after the REMOVE_URLS_LIST
   REMOVE_URLS_WL=youtube.com,youtu.be,vk.com,twitch.tv,instagram.com
   # Disable mirror message deleting (true or false). Defaults to false
   DISABLE_DELETE=false
   # Disable mirror message editing (true or false). Defaults to false
   DISABLE_EDIT=false

   ❓ Channels ID can be fetched by using Telegram bot.

   ❗ Note: never push your .env/.yml files with real crendential to a public repo. Use a separate branch (eg, heroku-branch) with .env/.yml files to push to git-based deployment system like Heroku.

7. Make sure the account has joined source and target channels

8. Be careful with forwards from channels with RESTRICTED SAVING CONTENT. It may lead to an account ban

Deploy

Heroku

or via CLI:

1. Clone project

   git clone https://github.com/khoben/telemirror.git

2. Create new heroku app within Heroku CLI

   heroku create {your app name}

3. Add heroku remote

   heroku git:remote -a {your app name}

4. Set environment variables to your heroku app from .env by running bash script

   ./set_heroku_env.bash

5. Upload on heroku host

   git push heroku master

6. Start heroku app

   heroku ps:scale web=1

Keep up-to-date with Heroku

If you deployed manually, move to step 2.

0. Get project to your PC:

   heroku git:clone -a {your app name}

1. Init upstream repo (this repository or its fork)

   git remote add origin https://github.com/khoben/telemirror

2. Get latest changes

   git pull origin master

3. Push latest changes to heroku

   git push heroku master -f

Locally:

1. Create and activate python virtual environment

   python -m venv venv
   source ./venv/Scripts/activate # linux
   venv/Scripts/activate # windows

2. Install dependencies

   pip install -r requirements.txt

3. Run

   python main.py