burke/teleirc repository overview

⁠teleirc

NodeJS implementation of a Telegram⁠ <=> IRC⁠ bridge for use with any IRC channel and Telegram group

⁠About

This project was written by Mark Repka⁠ to help bridge communication between RITlug⁠'s IRC channel with our Telegram group. The project is a lightweight NodeJS application. This is also being used in various IRC channels and Telegram groups than just RITlug.

⁠Try it out

A public Telegram supergroup and IRC channel are available for you to see it live in action. This is also where our developers and community hang out as well.

• Telegram⁠
• IRC⁠ (#ritlug-teleirc @ irc.freenode.net)

⁠Who's using this app?

Ask any of our successful users!

• RITlug teleirc⁠ (Telegram⁠ | IRC⁠)
• RITlug⁠ (Telegram invite-only | IRC⁠)
• Fedora Project⁠ (Telegram⁠ | IRC⁠)
• LIBOCon 2016⁠ (Telegram invite-only | IRC⁠)
• FOSS@MAGIC at RIT⁠ (Telegram⁠ | IRC⁠)
• Fedora LATAM⁠ (Telegram⁠ | IRC⁠)
• MINECON Agents⁠ (Telegram invite-only | IRC⁠)

⁠Installation

In order to use this bridge, you will need several pieces of information. This guide is broken up into Telegram, teleirc, and IRC sections.

⁠Telegram

For the Telegram side, you will need to create a new Telegram bot that will sit inside your Telegram group. You will need to do a little configuration and information gathering with the bot.

1. Send a /start Telegram message to the @BotFather, the Telegram bot⁠ for creating Telegram bots⁠.
2. Create a bot with the /newbot command in a chat window with BotFather. You will then be prompted to enter a bot name. Once you have done this, you will get a bot token from the BotFather for accessing the Telegram API. Make note of the token for later configuration.
3. Before this bot can enter any group chats, you will need to configure it with correct permissions. Send the /setprivacy command to the BotFather, specify which bot this command is for, then disable the privacy so the bot receives all messages sent in the group chat.
4. Optionally, you can supply a different bot name, description, and picture to make it more obvious what the bot is in the group chat.
5. This bot supports adhering to Telegram's bot rate limits. You can set messages per minute in the config. As of this writing, the limit from Telegram is 20, which is the default. If you don't want to use rate limiting, set the option to 0. The bot will bundle messages and send them together with a delay while rate limiting in hopes of avoiding dropped messages.
6. Add the bot to the Telegram group chat you want to bridge.

Now that you have a bot created, have its Telegram API token, and have it in your group, you can start using this bridge.

⁠Teleirc

To get teleirc working, you will need a server to run it on and a recent version of Docker installed.

docker run -d --name teleirc --restart always \
	-e TELEIRC_TOKEN="000000000:AAAAAAaAAa2AaAAaoAAAA-a_aaAAaAaaaAA" \
	-e IRC_CHANNEL="#channel" \
	-e IRC_BOT_NAME="teleirc" \
	-e IRC_BLACKLIST="CowSayBot,SomeOtherBot" \
	-e TELEGRAM_CHAT_ID="-0000000000000" \
	bmamlin/teleirc

⁠Configuration Settings

• TELEIRC_TOKEN: Private API key for Telegram bot
• IRC_BLACKLIST: Comma-separated list of IRC nicks to ignore (default: "")
• IRC_BOT_NAME: Nickname for your bot to use on IRC
• IRC_CHANNEL: IRC channel you want your bot to join
• IRC_PREFIX: Text displayed before Telegram name in IRC (default: <)
• IRC_SERVER: IRC server you wish to connect to (default: irc.freenode.net)
• IRC_SUFFIX: Text displayed after Telegram name in IRC (default: >)
• MAX_MESSAGES_PER_MINUTE: Maximum rate at which to relay messages (default: 20)
• SHOW_ACTION_MESSAGE: Relay action messages (default: true)
• SHOW_JOIN_MESSAGE: Relay join messages (default: false)
• SHOW_KICK_MESSAGE: Relay kick messages (default: false)
• SHOW_LEAVE_MESSAGE: Relay leave messages (default: false)
• TELEGRAM_CHAT_ID: Telegram chat ID of the group you are bridging (how do I get this?⁠)

Alternatively, if you start up the bot with no Telegram chat ID set, it will sit waiting for messages to be sent to it. If you invite the bot to your group chat, you should see a "Debug TG" message with some information about the invite that was sent. One of the fields here will be the chatId. This is the value that needs to be put in the config object. Be careful not to get the user ID of a specific user when reading these messages.

⁠IRC

There is not real configuration needed on the IRC side, as IRC is generally very open. It might be a good idea to register the channel⁠ you are using.

⁠Hey, I use this project too!

Want to have your name added to the list in this README? Let us know you're using teleirc too! Submit an issue⁠ against this repo with the following info:

• Organization / group name and website
• Telegram group URL
• Your IRC channel

Please note, to be added, your group must not discuss / contain inappropriate or explicit content.

⁠License

Licensed under the MIT License⁠. If you're hacking on teleirc, we'd love to see you bring your improvements back upstream!