| 1 | # Discord |
| 2 | |
| 3 | - Status: ??? |
| 4 | - Maintainers: ??? |
| 5 | - Features: ??? |
| 6 | |
| 7 | ## Configuration |
| 8 | |
| 9 | > [!TIP] |
| 10 | > For detailed information about discord settings, see [settings.md](settings.md) |
| 11 | |
| 12 | **Basic configuration example:** |
| 13 | |
| 14 | ```toml |
| 15 | [discord] |
| 16 | [discord.mydiscord] |
| 17 | RemoteNickFormat="[{PROTOCOL}] <{NICK}> " |
| 18 | Token="######" |
| 19 | Server="name or uid of guild" |
| 20 | AutoWebhooks=true |
| 21 | # Map threads from other bridges on discord replies |
| 22 | PreserveThreading=true |
| 23 | ``` |
| 24 | |
| 25 | ## FAQ |
| 26 | |
| 27 | ### How to create a discord bot token for matterbridge? |
| 28 | |
| 29 | See [account.md](account.md). |
| 30 | |
| 31 | ### Username/avatar spoofing |
| 32 | |
| 33 | [Creating a message](https://discordapp.com/developers/docs/resources/channel#create-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](https://discordapp.com/developers/docs/resources/webhook#execute-webhook) can set any username and avatar URL. |
| 34 | |
| 35 | 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. |
| 36 | |
| 37 | 1. Server Settings -> Roles |
| 38 | 2. Select your app's role (see [here](https://support.discord.com/hc/en-us/articles/206029707-How-do-I-set-up-Permissions-) for more info about how to create roles) |
| 39 | 3. Grant "Manage Webhooks" |
| 40 | |
| 41 | Then, just provide `AutoWebhooks=true` for the Discord account settings, as shown below: |
| 42 | |
| 43 | ```toml |
| 44 | [discord] |
| 45 | [discord.mydiscord] |
| 46 | Token="######" |
| 47 | Server="Wumpus Technologies Inc." |
| 48 | AutoWebhooks=true |
| 49 | ``` |
| 50 | |
| 51 | |
| 52 | <details><summary>If you would like to create webhooks yourself, instead of letting the bot manage them, follow these instructions.</summary> |
| 53 | |
| 54 | 1. On Discord, go to Server Settings, then Integrations, then Webhooks -> "Create Webhook" |
| 55 | 2. Specify the name and channel, and copy the resulting webhook URL |
| 56 | 3. Paste in your gateway as `WebhookURL="https://discordapp.com/api/webhooks/529689699999999999/Da-H4RRY_P0-kjdsknkfgfjghf` |
| 57 | |
| 58 | Specify a webhook per channel: |
| 59 | |
| 60 | ```toml |
| 61 | [[gateway]] |
| 62 | name="testing" |
| 63 | enable=true |
| 64 | |
| 65 | [[gateway.inout]] |
| 66 | account="slack.myworkspace" |
| 67 | channel="testing" |
| 68 | |
| 69 | [[gateway.inout]] |
| 70 | account="discord.myserver" |
| 71 | channel="testing" |
| 72 | |
| 73 | # Specify options for this gateway link |
| 74 | [gateway.inout.options] |
| 75 | WebhookURL="https://discordapp.com/api/webhooks/thing1/thing2" |
| 76 | ``` |
| 77 | |
| 78 | </details> |
| 79 | |
| 80 | ### Guessing avatars when they are missing |
| 81 | |
| 82 | > **This feature is only available when sending messages using webhooks.** |
| 83 | |
| 84 | 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. |
| 85 | |
| 86 | 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. |
| 87 | |
| 88 | Note that it won't try to "guess" avatars when: |
| 89 | |
| 90 | - an avatar on the source platform is present, or |
| 91 | - there are multiple Discord users with the same name. |
| 92 | |
| 93 | 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. |
| 94 | |
| 95 | ```toml |
| 96 | [discord] |
| 97 | [discord.mydiscord] |
| 98 | Token="#####" |
| 99 | Server="Wumpus Technologies Inc." |
| 100 | UseLocalAvatar=["irc", "slack.myworkspace"] |
| 101 | ``` |
| 102 | |
| 103 | ### Seeing IDs instead of usernames on the other bridges? |
| 104 | |
| 105 | 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. |
| 106 | |
| 107 | ### Can I join the bot to a server I don't own? |
| 108 | |
| 109 | You need permissions on the server to be able to join the bot, if you're allowed to here's how you do it: |
| 110 | Click on the bot here: https://discordapp.com/developers/applications/me |
| 111 | |
| 112 | Click the "Generate OAUTH" button, copy the URL and paste it into your address bar, open the page and you'll see the drop down menu for adding the bot to any server you have permissions on. |
| 113 | |
| 114 | ### Messages not being edited, but a new message with (edit) appears? |
| 115 | Message editing is not supported by discord using webhooks. If you want message editing, disable webhooks and use token only |
| 116 | |
| 117 | ### Error obtaining server members: HTTP 403 Forbidden |
| 118 | |
| 119 | Discord changed its API: |
| 120 | |
| 121 | See <https://github.com/42wim/matterbridge/wiki/Discord-bot-setup#privileged-gateway-intents> for a fix |
| 122 | See <https://github.com/42wim/matterbridge/issues/1263> for more info |
| 123 | |
| 124 | ### Do I need to allow inbound connections for webhooks to work |
| 125 | |
| 126 | No. |
| 127 | |
| 128 | ### Replies show the botname instead of the username/avatar |
| 129 | |
| 130 | This is a discord limitation: https://github.com/42wim/matterbridge/issues/1558#issuecomment-1030713994 |
| 131 | You can do a workaround by setting `PreserveThreading=false` |
| 132 | |
