<h1>Connect Evennia channels to Discord<aclass="headerlink"href="#connect-evennia-channels-to-discord"title="Permalink to this headline">¶</a></h1>
<p><aclass="reference external"href="https://discord.com">Discord</a> is a popular chat service, especially for game
communities. If you have a discord server for your game, you can connect it
to your in-game channels to communicate between in-game and out.</p>
<sectionid="configuring-discord">
<h2>Configuring Discord<aclass="headerlink"href="#configuring-discord"title="Permalink to this headline">¶</a></h2>
<p>The first thing you’ll need is to set up a Discord bot to connect to your game.
Go to the <aclass="reference external"href="https://discord.com/developers/applications">bot applications</a> page and make a new application. You’ll need the
“MESSAGE CONTENT” toggle flipped On, and to add your bot token to your settings.</p>
<p>Start/reload Evennia and log in as a privileged user. You should now have a new
command available: <codeclass="docutils literal notranslate"><spanclass="pre">discord2chan</span></code>. Enter <codeclass="docutils literal notranslate"><spanclass="pre">help</span><spanclass="pre">discord2chan</span></code> for an explanation
of its options.</p>
<p>Adding a new channel link is done with the following command:</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">evennia_channel</span></code> argument must be the name of an existing Evennia channel,
and <codeclass="docutils literal notranslate"><spanclass="pre">discord_channel_id</span></code> is the full numeric ID of the Discord channel.</p>
<blockquote>
<div><p>Your bot needs to be added to the correct Discord server with access to the
channel in order to send or receive messages. This command does NOT verify that
your bot has Discord permissions!</p>
</div></blockquote>
</section>
<sectionid="step-by-step-discord-setup">
<h2>Step-By-Step Discord Setup<aclass="headerlink"href="#step-by-step-discord-setup"title="Permalink to this headline">¶</a></h2>
<p>This section will walk through the entire process of setting up a Discord
connection to your Evennia game, step by step. If you’ve completed any of the
steps already, feel free to skip to the next.</p>
<sectionid="creating-a-discord-bot-application">
<h3>Creating a Discord Bot Application<aclass="headerlink"href="#creating-a-discord-bot-application"title="Permalink to this headline">¶</a></h3>
<blockquote>
<div><p>You will need an active Discord account and admin access to a Discord server
in order to connect Evennia to it. This assumes you already do.</p>
</div></blockquote>
<p>Make sure you’re logged in on the Discord website, then visit
<aclass="reference external"href="https://discord.com/developers/applications">https://discord.com/developers/applications</a>. Click the “New Application”
button in the upper right corner, then enter the name for your new app - the
name of your Evennia game is a good option.</p>
<p>You’ll next be brought to the settings page for the new application. Click “Bot”
on the sidebar menu, then “Build-a-Bot” to create your bot account.</p>
<p><strong>Save the displayed token!</strong> This will be the ONLY time that Discord will allow
you to see that token - if you lose it, you will have to reset it. This token is
how your bot confirms its identity, so it’s very important.</p>
<p>Next, add this token to your <em>secret</em> settings.</p>
<p>Once that is saved, scroll down the Bot page a little more and find the toggle for
“Message Content Intent”. You’ll need this to be toggled to ON, or you bot won’t
be able to read anyone’s messages.</p>
<p>Finally, you can add any additional settings to your new bot account: a display image,
display nickname, bio, etc. You can come back and change these at any time, so
don’t worry about it too much now.</p>
</section>
<sectionid="adding-your-bot-to-your-server">
<h3>Adding your bot to your server<aclass="headerlink"href="#adding-your-bot-to-your-server"title="Permalink to this headline">¶</a></h3>
<p>While still in your new application, click “OAuth2” on the side menu, then “URL
Generator”. On this page, you’ll generate an invite URL for your app, then visit
that URL to add it to your server.</p>
<p>In the top box, find the checkbox for <codeclass="docutils literal notranslate"><spanclass="pre">bot</span></code> and check it: this will make a second
permissions box appear. In that box, you’ll want to check off at least the
following boxes:</p>
<ulclass="simple">
<li><p>Read Messages/View Channels (in “General Permissions”)</p></li>
<li><p>Send Messages (in “Text Permissions”)</p></li>
</ul>
<p>Lastly, scroll down to the bottom of the page and copy the resulting URL. It should
<p>Visit that link, select the server for your Evennia connection, and confirm.</p>
<p>After the bot is added to your server, you can fine-tune the permissions further
through the usual Discord server administration.</p>
</section>
<sectionid="activating-discord-in-evennia">
<h3>Activating Discord in Evennia<aclass="headerlink"href="#activating-discord-in-evennia"title="Permalink to this headline">¶</a></h3>
<p>You’ll need to do two additional things with your Evennia game before it can connect
to Discord.</p>
<p>First, install <codeclass="docutils literal notranslate"><spanclass="pre">pyopenssl</span></code> to your virtual environment, if you haven’t already.</p>
<p>Start or reload your game to apply the changed settings, then log in as an account
with at least <codeclass="docutils literal notranslate"><spanclass="pre">Developer</span></code> permissions and initialize the bot account on Evennia with
the <codeclass="docutils literal notranslate"><spanclass="pre">discord2chan</span></code> command. You should receive a message that the bot was created, and
that there are no active connections to Discord.</p>
<h3>Connecting an Evennia channel to a Discord channel<aclass="headerlink"href="#connecting-an-evennia-channel-to-a-discord-channel"title="Permalink to this headline">¶</a></h3>
<p>You will need the name of your Evennia channel, and the channel ID for your Discord
channel. The channel ID is the last part of the URL when you visit a channel.</p>
<p>e.g. if the url is <codeclass="docutils literal notranslate"><spanclass="pre">https://discord.com/channels/55555555555555555/12345678901234567890</span></code>
then your channel ID is <codeclass="docutils literal notranslate"><spanclass="pre">12345678901234567890</span></code></p>
<p>Link the two channels with the following command:</p>
<p>The two channels should now relay to each other. Confirm this works by posting a
message on the evennia channel, and another on the Discord channel - they should
both show up on the other end.</p>
<blockquote>
<div><p>If you don’t see any messages coming to or from Discord, make sure that your bot
has permission to read and send messages and that your application has the
“Message Content Intents” flag set.</p>
</div></blockquote>
</section>
<sectionid="further-customization">
<h3>Further Customization<aclass="headerlink"href="#further-customization"title="Permalink to this headline">¶</a></h3>
<p>The help file for <codeclass="docutils literal notranslate"><spanclass="pre">discord2chan</span></code> has more information on how to use the command to
customize your relayed messages.</p>
<p>For anything more complex, however, you can create your own child class of
<codeclass="docutils literal notranslate"><spanclass="pre">DiscordBot</span></code> and add it to your settings.</p>
