Section Discord (basic)

Configuration

The bot setup takes a bit of time, but it's necessary. Make sure you also get the "Members Intent" checkbox.

Basic example

[discord]
[discord.mydiscord]

# You can get your token by following the instructions on
# https://github.com/42wim/matterbridge/wiki/Discord-bot-setup
# in particular that the "Members Intent" checkbox is important.
# If you want roles/groups mentions to be shown with names instead of ID, 
# you'll need to give your bot the "Manage Roles" permission.
Token="YOUR_TOKEN_HERE"
Server="name or uid of guild" # if you want to bridge https://discord.com/channels/8888888888888/7777777777777777, then this should be 8888888888888
AutoWebhooks=true
RemoteNickFormat="[{PROTOCOL}] <{NICK}> "
# Map threads from other bridges on discord replies
PreserveThreading=true

Specification

Entire set of options that can be used in a Discord gateway

[discord]

# You can configure multiple servers "[discord.name]" or "[discord.name2]"
# In this example we use [discord.game]
#REQUIRED
[discord.game]
# Token (REQUIRED) is the token to connect with Discord API
# You can get your token by following the instructions on
# https://github.com/reactiflux/discord-irc/wiki/Creating-a-discord-bot-&-getting-a-token
# If you want roles/groups mentions to be shown with names instead of ID, you'll need to give your bot the "Manage Roles" permission.
Token="Yourtokenhere"

# Server (REQUIRED) is the ID or name of the guild to connect to, selected from the guilds the bot has been invited to
Server="yourservername"

## RELOADABLE SETTINGS
## All settings below can be reloaded by editing the file.
## They are also all optional.

# AllowMention controls which mentions are allowed. If not specified, all mentions are allowed.
# Note that even when a mention is not allowed, it will still be displayed nicely and be clickable. It just prevents the ping/notification.
#
# "everyone" allows @everyone and @here mentions
# "roles" allows @role mentions
# "users" allows @user mentions
AllowMention=["everyone", "roles", "users"]

# ShowEmbeds shows the title, description and URL of embedded messages (sent by other bots)
ShowEmbeds=false

# UseLocalAvatar specifies source bridges for which an avatar should be 'guessed' when an incoming message has no avatar.
# This works by comparing the username of the message to an existing Discord user, and using the avatar of the Discord user.
#
# This only works if WebhookURL is set (AND the message has no avatar).
# Example: ["irc"]
UseLocalAvatar=[]

# UseUserName shows the username instead of the server nickname
UseUserName=false

# UseDiscriminator appends the `#xxxx` discriminator when used with UseUserName
UseDiscriminator=false

# AutoWebhooks automatically configures message sending in the style of puppets.
# This is an easier alternative to manually configuring "WebhookURL" for each gateway,
# as turning this on will automatically load or create webhooks for each channel.
# This feature requires the "Manage Webhooks" permission (either globally or as per-channel).
AutoWebhooks=false

# EditDisable disables sending of edits to other bridges
EditDisable=false

# EditSuffix specifies the message to be appended to every edited message
# Example: " (edited)"
EditSuffix=""

# IgnoreNicks mutes outgoing messages from certain users.
# Messages from these users will not be transmitted to other bridges.
# Regular expressions are also supported.
# Example: "ircspammer1 ircspammer2"
IgnoreNicks=""

# IgnoreMessages mutes outgoing messages of a certain format.
# Messages matching this regular expression will not be transmitted sent to other bridges
# See https://regex-golang.appspot.com/assets/html/index.html for more regex info
#
# Example that ignores messages starting with ~~ or messages containing badword:
#   IgnoreMessages="^~~ badword"
IgnoreMessages=""

# ReplaceMessages replaces substrings of messages in outgoing messages.
# Regular expressions are supported.
#
# Example that replaces 'cat' => 'dog' and 'sleep' => 'awake':
#   ReplaceMessages=[ ["cat","dog"], ["sleep","awake"] ]
# Example that replaces all digits with the letter 'X', so 'hello123' becomes 'helloXXX':
#   ReplaceMessages=[ ["[0-9]","X"] ]
ReplaceMessages=[]

# ReplaceNicks replaces substrings of usernames in outgoing messages.
# See the ReplaceMessages setting for examples.
# Example: [ ["user--","user"] ]
ReplaceNicks=[]

# ExtractNicks allows for interoperability with other bridge software by rewriting messages and extracting usernames.
#
# Recommended reading:
# - https://github.com/42wim/matterbridge/issues/466
# - https://github.com/42wim/matterbridge/issues/713
#
# This example translates the following message
#   "Relaybot: <relayeduser> something interesting"
# into this message
#   "relayeduser: something interesting"
# like so:
#   ExtractNicks=[ [ "Relaybot", "<(.*?)>\\s+" ] ]
#
# This example translates the following message
#   "otherbot: (relayeduser) something else"
# into this message
#   "relayeduser: something else"
# like so:
#   ExtractNicks=[ [ "otherbot","\\((.*?)\\)\\s+" ] ]
#
# This example combines both of the above examples into one:
#   ExtractNicks=[ [ "Relaybot", "<(.*?)>\\s+" ],[ "otherbot","\\((.*?)\\)\\s+" ]
#
ExtractNicks=[]

# Label is as an extra identifier for use in the RemoteNickFormat setting.
Label=""

# RemoteNickFormat formats how remote users appear on this bridge.
# See the [general] config section for default options
RemoteNickFormat="[{PROTOCOL}] <{NICK}> "

# ShowJoinPart emits messages that show joins/parts from other bridges
# Supported from the following bridges: irc, mattermost, slack, discord
ShowJoinPart=false

# StripNick strips non-alphanumeric characters from nicknames.
# Recommended reading: https://github.com/42wim/matterbridge/issues/285
StripNick=false

# ShowTopicChange emits messages that show topic/purpose updates from other bridges
# Supported from the following bridges: slack
ShowTopicChange=false

# SyncTopic synchronises topic/purpose updates from other bridges
# Supported from the following bridges: slack
SyncTopic=false

Username/avatar spoofing

Creating a message via a user's API token (the basic configuration above) only lets Matterbridge post with the user/avatar that generated the token. But executing a webhook can set any username and avatar URL.

If you grant the bot the "Manage Webhooks" permission, it will automatically load and create webhooks in every bridged channel. You can even grant that permission on specific channels, if you don't want to give it global permission.

1. Server Settings -> Roles
2. Select your app's role (see here for more info about how to create roles)
3. Grant "Manage Webhooks"

Then, just provide AutoWebhooks=true for the Discord account settings, as shown below:

[discord]
    [discord.mydiscord]
    Token="some-secret-token"
    Server="Wumpus Technologies Inc."
    AutoWebhooks=true

If you would like to create webhooks yourself, instead of letting the bot manage them, follow these instructions.

1. On Discord, go to Server Settings, then Integrations, then Webhooks -> "Create Webhook"
2. Specify the name and channel, and copy the resulting webhook URL
3. Paste in your gateway as WebhookURL="https://discordapp.com/api/webhooks/529689699999999999/Da-H4RRY_P0-kjdsknkfgfjghf

Specify a webhook per channel:

[[gateway]]
name="testing"
enable=true

[[gateway.inout]]
account="slack.myworkspace"
channel="testing"

[[gateway.inout]]
account="discord.myserver"
channel="testing"
    
    # Specify options for this gateway link
    [gateway.inout.options]
    WebhookURL="https://discordapp.com/api/webhooks/thing1/thing2"

Guessing avatars when they are missing

This feature is only available when sending messages using webhooks.

Avatars from source platforms will usually be shown in Discord messages. However, sometimes users can't (or don't) set their avatar on the source platform, (e.g for messages sent from IRC to Discord), so messages from those may use a default avatar.

The UseLocalAvatar specifies source bridges for which an avatar should be "guessed", so that all messages have avatars. This works by comparing the source message username to an existing Discord user on your server, and using the avatar of that Discord user.

Note that it won't try to "guess" avatars when:

• an avatar on the source platform is present, or
• there are multiple Discord users with the same name.

As shown below, you can either provide the bridge platform name ("irc") or the full account name ("slack.myworkspace"). This means that for messages coming from IRC, or messages from the Slack myworkspace account, avatar "guessing" is enabled.

[discord]
    [discord.mydiscord]
    Token="some-secret-token"
    Server="Wumpus Technologies Inc."
    UseLocalAvatar=["irc", "slack.myworkspace"]

User token

To use a user token instead of a bot, refer to the settings page

⚠️ read the Discord ToS about using user tokens for automation: https://support.discord.com/hc/en-us/articles/115002192352-Automated-user-accounts-self-bots-