discord-irc

Connects Discord and IRC channels by sending messages back and forth.

This is an opinionated fork that adds bidirectional channel topic syncing, a topic change alert message, and a setting to disable username stripping from !commands sent from irc -> discord.

Example

Installation and usage

Note: discord-irc requires Node.js version 6 or newer, as it depends on discord.js.

Before you can run discord-irc you need to create a configuration file by following the instructions here. After you've done that you can replace /path/to/config.json in the commands below with the path to your newly created configuration file - or just config.json if it's in the same directory as the one you're starting the bot from.

When you've done that you can install and start the bot either through npm:

$ npm install -g discord-irc
$ discord-irc --config /path/to/config.json

or by cloning the repository:

In the repository folder:
$ npm install
$ npm run build
$ npm start -- --config /path/to/config.json # Note the extra double dash

It can also be used as a module:

import discordIRC from 'discord-irc';
import config from './config.json';
discordIRC(config);

Configuration

First you need to create a Discord bot user, which you can do by following the instructions here.

Example configuration

[
  // Bot 1 (minimal configuration):
  {
    "nickname": "test2",
    "server": "irc.testbot.org",
    "discordToken": "botwantsin123",
    "channelMapping": {
      "#other-discord": "#new-irc-channel"
    }
  },

  // Bot 2 (advanced options):
  {
    "nickname": "test",
    "server": "irc.bottest.org",
    "discordToken": "botwantsin123",
    "autoSendCommands": [ // Commands that will be sent on connect
      ["PRIVMSG", "NickServ", "IDENTIFY password"],
      ["MODE", "test", "+x"],
      ["AUTH", "test", "password"]
    ],
    "channelMapping": { // Maps each Discord-channel to an IRC-channel, used to direct messages to the correct place
      "#discord": "#irc channel-password", // Add channel keys after the channel name
      "1234567890": "#channel" // Use a discord channel ID instead of its name (so you can rename it or to disambiguate)
    },
    "ircOptions": { // Optional node-irc options
      "floodProtection": false, // On by default
      "floodProtectionDelay": 1000, // 500 by default
      "port": "6697", // 6697 by default
      "secure": true, // enable SSL, false by default
      "sasl": true, // false by default
      "username": "test", // nodeirc by default
      "password": "p455w0rd" // empty by default
    },
    "format": { // Optional custom formatting options
      // Patterns, represented by {$patternName}, are replaced when sending messages
      "commandPrelude": "Command sent by {$nickname}", // Message sent before a command
      "ircText": "<{$displayUsername}> {$text}", // When sending a message to IRC
      "urlAttachment": "<{$displayUsername}> {$attachmentURL}", // When sending a Discord attachment to IRC
      "discord": "**<{$author}>** {$withMentions}" // When sending a message to Discord
      // Other patterns that can be used:
      // {$discordChannel} (e.g. #general)
      // {$ircChannel} (e.g. #irc)
    },
    "ircNickColor": false, // Gives usernames a color in IRC for better readability (on by default)
    // Makes the bot hide the username prefix for messages that start
    // with one of these characters (commands):
    "commandCharacters": ["!", "."],
    // Enables stripping nicknames from commands sent from irc to discord.
    // Useful for discord channels with bot commands, annoying for ones that don't
    // Defaults to true.
    "discordCommandFormatting": true,
    // Bi-directional syncing of channel topics. Defaults to false.
    // This feature REQUIRES the bot be in a roll with "Manage Channels" permission for the guild on discord
    // and have proper permissions to change the channel topic in IRC.
    "syncTopic": false,
    // Post a simple (non-pinging) message in discord when the topic is changed
    "topicAlert": false,
    "ircStatusNotices": true, // Enables notifications in Discord when people join/part in the relevant IRC channel
    "ignoreUsers": {
      "irc": ["irc_nick1", "irc_nick2"], // Ignore specified IRC nicks and do not send their messages to Discord.
      "discord": ["discord_nick1", "discord_nick2"] // Ignore specified Discord nicks and do not send their messages to IRC.
    },
    // List of webhooks per channel
    "webhooks": {
      "#discord": "https://discordapp.com/api/webhooks/id/token"
    }
  }
]

The ircOptions object is passed directly to irc-upd (available options).

To retrieve a discord channel ID, write \#channel on the relevant server – it should produce something of the form <#1234567890>, which you can then use in the channelMapping config.

Webhooks

Webhooks lets you override nicknames and avatars, so messages coming from IRC can appear as regular Discord messages:

To enable webhooks, follow part 1 of this guide to create and retrieve a webhook URL for a specific channel, then enable it in discord-irc's config as follows:

  "webhooks": {
    "#discord-channel": "https://discordapp.com/api/webhooks/id/token"
  }

Encodings

If you encounter trouble with some characters being corrupted from some clients (particularly umlauted characters, such as ä or ö), try installing the optional dependencies iconv and node-icu-charset-detector. The bot will produce a warning when started if the IRC library is unable to convert between encodings.

Further information can be found in the installation section of irc-upd.

Tests

Run the tests with:

$ npm test

Style Guide

discord-irc follows the Airbnb Style Guide. ESLint is used to make sure this is followed correctly, which can be run with:

$ npm run lint