Skip to main content

Telegram Master Channel for EH Forwarder Bot, based on Telegram Bot API.

Project description

Channel ID: blueset.telegram

ETM is a Telegram Master Channel for EH Forwarder Bot, based on Telegram Bot API, python-telegram-bot.

Beta version

This is an unstable beta version, and its functionality may change at any time.

Requirements

  • Python >= 3.6
  • EH Forwarder Bot >= 2.0.0
  • ffmpeg
  • libmagic
  • libwebp

Getting Started

  1. Install all required binary dependencies

  2. Install ETM

    pip3 install efb-telegram-master
    
  3. Enable ETM in the profile’s config.yaml

    The path of your profile storage directory depends on your configuration.

    (As of EFB 2.0.0a1: Default profile storage directory is located at ~/.ehforwarderbot/profiles/default )

  1. Configure the channel (described as follows)

Configuration

Set up a bot

Create a bot with @BotFather, give it a name and a username. Then you’ll get a token, which will be used later. Keep this token secure, as it gives who owns it the full access to the bot.

Use /setjoingroups to allow your bot to join groups. Use /setprivacy to disable the privacy restriction of the bot, so that it can receive all messages in the group.

Complete configuration file

Configuration file is stored at <profile directory>/blueset.telegram/config.yaml.

A sample config file can be as follows:

##################
# Required items #
##################
# You are required to fill the option below,
# or this channel will not work.

# Telegram bot token.
# This is the token you obtained from BotFather
token: "12345678:1a2b3c4d5e6g7h8i9j"

# List of Telegram User IDs of admins
# ETM will only process messages and commands from users
# listed below. This ID can be obtained from various ways
# on Telegram.
admins:
- 102938475
- 91827364

##################
# Optional items #
##################
# The following options are optional. Lack of this section
# will only affect an additional part of functionality of
# this channel.

# API tokens required for speech recognition
speech_api:
    # Microsoft (Bing) speech recognition token
    # API key can be obtained from
    # https://azure.microsoft.com/en-us/try/cognitive-services/
    bing: "VOICE_RECOGNITION_TOKEN"
    # Baidu speech recognition token
    # API key can be obtained from
    # http://yuyin.baidu.com/
    baidu:
        app_id: 123456
        api_key: "API_KEY_GOES_HERE"
        secret: "SECRET_KEY_GOES_HERE"


# Experimental Flags
# This section can be used to enable experimental functionality.
# However, those features may be changed or removed at any time.
# Options in this section is explained afterward.
flags:
    option_one: 10
    option_two: false
    option_three: "foobar"

Usage

At the beginning, messages from all senders will be sent to the user directly, that means every message will be mixed in the same conversation. By linking a chat, you can redirect messages from a specific sender to an empty group for a more organized conversation.

In a nutshell, ETM offers the following commands, you can also send it to BotFather for a command list:

help - Show commands list.
link - Link a remote chat to a group.
unlink_all - Unlink all remote chats from a group.
info - Display information of the current Telegram chat.
chat - Generate a chat head.
recog - Recognize a speech by replying to it.
extra - Access extra functionalities.
update_info - Update the group name and profile picture

Note

In case of multiple admins are assigned, they may all send message on your behalf, but only the 0th admin can receive direct message from the bot.

Send a message

Send to a linked chat

You can send message as you do in a normal Telegram chat.

What is supported:

  • Send/forward message in all supported types
  • Direct reply to a message
  • Send message with inline bot in supported types

What is NOT supported:

  • @ reference
  • Markdown/HTML formatting
  • Messages with unsupported types

Send to a non-linked chat

To send a message to a non-linked chat, you should “direct reply” to a message or a “chat head” that is sent from your recipient. Those messages should appear only in the bot conversation.

In a non-linked chat, direct reply will not be delivered to the remote channel, everything else is supported as it does in a linked chat.

Edit and delete message

In EFB v2, the framework added support to message editing and removal, and so does ETM. However, due to the limitation of Telegram Bot API, although you may have selected “Delete from the bot”, or “Delete from everyone” while deleting messages, the bot would not know anything about it. Therefore, if you want your message to be removed from a remote chat, edit your message and prepend it with rm` (it’s R, M, and ~`, not single quote), so that the bot knows that you want to remote the message.

Please also notice that some channels may not support editing and/or deleting messages depends on their implementations.

/chat: Chat head

If you want to send a message to a non-linked chat which has not yet sent you a message, you can ask ETM to generate a “chat head”. Chat head works similarly to an incoming message, you can reply to it to send messages to your recipient.

Send /chat to the bot, and choose a chat from the list. When you see “Reply to this message to send to from ”, it’s ready to go.

Advanced feature: Filtering

If you have just too much chats, and being too tired for keep tapping Next >, or maybe you just want to find a way to filter out what you’re looking for, now ETM has equipped /chat and /list with filtering feature. Attach your keyword behind, and you can get a filtered result.

E.g.: /chat Eana will give you all chats has the word “Eana”.

Technical Details

The filter query is in fact a regular expression matching. We used Python’s re.search with flags re.DOTALL | re.IGNORECASE in this case, i.e.: . matches everything including line breaks, and the query is NOT case-sensitive. Each comparison is done against a specially crafted string which allows you to filter multiple criteria.

Channel: <Channel name>
Name: <Chat name>
Alias: <Chat Alias>
ID: <Chat Unique ID>
Type: (User|Group)
Mode: [[Muted, ]Linked]
Other: <Python Dictionary String>

Note

Type can be either “User” or “Group”

Other is the vendor specific information provided by slave channels. Format of such information is specified in their documentations respectively.

Examples:

  • Look for all WeChat groups: Channel: WeChat.*Type: Group
  • Look for everyone who has an alias Name: (.*?)\nAlias: (?!\1)
  • Look for all entries contain “John” and “Jonny” in any order: (?=.*John)(?=.*Jonny)"

/extra: External commands from slave channels (“extra functions”)

Some slave channels may provide commands that allows you to remotely control those accounts, and achieve extra functionality, those commands are called “extra functions”. To view the list of available extra functions, send /extra to the bot, you will receive a list of commands available, together with their usages.

Those commands are named like “/<number>_<command_name>”, and can be called like a Linux/unix CLI utility. (of course, please don’t expect piping etc to be supported)

/recog: Speech recognition

If you have entered a speech recognition service API keys, you can use it to convert speech in voice messages into text.

Reply any voice messages in a conversation with the bot, with the command /recog, and the bot will try to convert it to text using those speech recognition services enabled.

If you know the language used in this message, you can also attach the language code to the command for a more precise conversion.

Supported language codes:

Code Baidu Bing
en, en-US English English (US)
zh, zh-CN Mandarin Mandarin (China Mainland)
ct Cantonese -
de-DE - German
ru-RU - Russian
ja-JP - Japanese
ar-EG - Arabic
es-ES - Spanish (Spain)
pt-BR - Portuguese (Brazil)
fr-FR - French (France)

/update_info: Update name and profile picture of linked group

EFB can help you to update the name and profile picture of a group to match with appearance in the remote chat.

This functionality is available when:

  • This command is sent to a group
  • The bot is an admin of the group (“Everyone is admin” will not work in this case)
  • The group is linked to exactly one remote chat
  • The remote chat is accessible

Profile picture will not be set if it’s not available from the slave channel.

Telegram Channel support

ETM supports linking remote chats to Telegram Channels with partial support.

The bot can:

  • Link one or more remote chats to a Telegram Channel
  • Check and manage link status of the channel
  • Let the bot to update channel title and profile pictures accordingly

It cannot:

  • Process messages sent by you or others to the channel
  • Accept commands in the channel

Currently the following commands are supported in channels:

  • /start for manual chat linking
  • /link to manage groups linked to the channel
  • /info to show information of the channel
  • /update_info to update the channel title and picture

How to use:

  1. Add the bot as an administrator of the channel
  2. Send commands to the channel
  3. Forward the command message to the bot privately

Experimental flags

The following flags are experimental features, may change, break, or disappear at any time. Use at your own risk.

Flags can be enabled in the flags key of the configuration file, e.g.:

flags:
    flag_name: flag_value
  • no_conversion (bool) [Default: false]

    Disable audio conversion, send all audio file as is, and let Telegram to handle it.

    Only works in linked chats.

  • chats_per_page (int) [Default: 10]

    Number of chats shown in when choosing for /chat and /link command. An overly large value may lead to malfunction of such commands.

  • network_error_prompt_interval (int) [Default: 100]

    Notify the user about network error every n errors received. Set to 0 to disable it.

  • multiple_slave_chats (bool) [Default: true]

    Link more than one remote chat to one Telegram group. Send and reply as you do with an unlinked chat. Disable to link remote chats and Telegram group one-to-one.

  • prevent_message_removal (bool) [Default: true]

    When a slave channel requires to remove a message, EFB will ignore the request if this value is true.

Project details


Release history Release notifications

History Node

2.0.0b12

History Node

2.0.0b11

History Node

2.0.0b10

History Node

2.0.0b9

History Node

2.0.0b8

History Node

2.0.0b7

History Node

2.0.0b6

History Node

2.0.0b5

History Node

2.0.0b4

History Node

2.0.0b3

History Node

2.0.0b2

This version
History Node

2.0.0b1.dev2

History Node

2.0.0b1.dev0

History Node

2.0.0b0.dev0

History Node

2.0.0a1.dev0

History Node

2.0.0.dev0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
efb_telegram_master-2.0.0b1.dev2-py3-none-any.whl (51.2 kB) Copy SHA256 hash SHA256 Wheel py3 Feb 1, 2018
efb-telegram-master-2.0.0b1.dev2.tar.gz (45.5 kB) Copy SHA256 hash SHA256 Source None Feb 1, 2018

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page