Skip to main content
Using Deno in production at your company? Earn free Deno merch.
Give us feedback

CI Publish Docker Image and Native Binaries

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

Example

discord-irc

Installation and usage

Before you can run discord-irc you need to create a configuration file by following the instructions here.

Native builds (easiest)

Start the bot by downloading the latest release for your platform.

Windows:

The easiest method is place your config.json in the same folder as discord-irc-windows-x86_64.exe and double-click the application.

To run manually from command line, or adjust the config file path:

.\discord-irc-windows-x86_64.exe -c .\config.json

Linux/macOS:

## Linux users may need to mark as executable first
chmod +x ./discord-irc-linux-x86_64
./discord-irc-linux-x86_64 -c ./config.json

## Apple users may need to mark as executable and disable quarantine before running
chmod +x ./discord-irc-apple-* && xattr -c ./discord-irc-apple-*
./discord-irc-apple-* -c ./config.json

Config file location

If run with no arguments, the application will search for a config.json within the current working directory.

Running with Deno (developers)

For development work, discord-irc requires Deno, as it depends on Harmony. Please see the official install instructions to install Deno for your platform.

## Clone the repo
git clone https://github.com/aronson/discord-irc.git
## copy your config.json in
cp /path/to/config.json discord-irc
## Enter source directory
cd discord-irc
## Start with deno.
deno task start

## For custom path
CONFIG_FILE=/path/to/config.json deno task start

It can also be used as a module:

import {
  Config,
  createBots,
  parseConfigObject,
} from 'https://raw.githubusercontent.com/aronson/discord-irc/main/mod.ts';

// Read local config file into an object
const configFileObject = JSON.parse(Deno.readTextFileSync('./config.json'));
// Parse against provided JSON schema to validate integrity of config
const result = parseConfigObject(configFileObject);
if (!result.success) {
  console.log('Error parsing configuration:');
  console.log(result.error);
} else {
  // May still fail if invalid ircOptions
  const config = result.data as Config | Config[];

  const bots = createBots(config);

  // Graceful shutdown of network clients
  Deno.addSignalListener('SIGINT', async () => {
    bots[0].logger.warn('Received Ctrl+C! Disconnecting...');
    for (const bot of bots) {
      try {
        await bot.disconnect();
      } catch (e) {
        bot.logger.error(e);
      }
    }
    Deno.exit();
  });
}

Docker

As an alternative to running discord-irc directly on your machine, we provide a Docker container image. After creating a configuration file, you can fetch the image from Docker Hub and run it with the following command:

docker run -v /path/to/config.json:/app/config.json ghcr.io/aronson/discord-irc

If you’ve checked out the repository already, you can build the Docker image locally and run that instead:

docker build -t discord-irc .
docker run -v /path/to/config.json:/app/config.json discord-irc

Note that the path to the config file on the host (/path/to/) must be a valid absolute path to a config file. Otherwise, you may get the error “illegal operation on a directory”.

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: {
      // Deno/irc options, see https://github.com/jeromeludmann/deno-irc/blob/main/API.md#options
      username: 'test',
      password: 'p455w0rd',
    },
    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} [@{$discordUsername}]> {$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)
      webhookAvatarURL: 'https://robohash.org/{$nickname}', // Default avatar to use for webhook messages
    },
    ircNickColor: false, // Gives usernames a color in IRC for better readability (on by default)
    ircNickColors: [
      'light_blue',
      'dark_blue',
      'light_red',
      'dark_red',
      'light_green',
      'dark_green',
      'magenta',
      'light_magenta',
      'orange',
      'yellow',
      'cyan',
      'light_cyan',
    ], // Which irc-upd colors to use
    parallelPingFix: true, // Prevents users of both IRC and Discord from being mentioned in IRC when they speak in Discord (off by default)
    // Makes the bot hide the username prefix for messages that start
    // with one of these characters (commands):
    commandCharacters: ['!', '.'],
    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.
      discordIds: ['198528216523210752'], // Ignore specified Discord ids and do not send their messages to IRC.
    },
    // List of webhooks per channel
    webhooks: {
      '#discord': 'https://discord.com/api/webhooks/id/token',
    },
  },
];

The ircOptions object is passed directly to deno/irc (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:

discord-webhook

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://discord.com/api/webhooks/id/token"
}

Tests (TODO)

Run the tests with:

deno test

Style Guide

discord-irc follows the deno standard styles with some tweaks. Please use deno lint and deno fmt to make sure this is followed correctly.