Mojo::Discord

This is a set of Perl Modules designed to implement parts of the Discord public API, build on Mojo::IOLoop.

There are four modules involved

• Mojo::Discord::Auth handles OAuth2
• Mojo::Discord::Gateway handles the Websocket realtime event monitoring part (connect and monitor the chat)
• Mojo::Discord::REST handles calls to the REST web API, which mostly handles actions you want the bot to take
• Mojo::Discord is a wrapper that saves the user the trouble of managing both REST and Gateway APIs manually.

Note: This is a spare-time project

I offer no promises as to code completion, timeline, or even support. If you have questions I will try to answer.

Second Note: Amateur code warning

I would recommend not building anything on this code for now. It is lacking in documentation, error handling, and other things. I hope to improve this over time, but again because it's a side project I can only do so much with the time I have.

Pre-Requisites

• Mojo::UserAgent and Mojo::IOLoop to provide non-blocking asynchronous HTTP calls and websocket functionality.
• Compress::Zlib, as some of the incoming messages are compressed Zlib blobs
• Mojo::JSON to convert the compressed JSON messages into Perl structures.
• Encode::Guess to determine whether we're dealing with a compressed stream or not.
• IO::Socket::SSL is required to fetch the Websocket URL for Discord to connect to.

Example Program

This application creates a very basic AI Chat Bot using the Hailo module (a modern implementation of MegaHAL)

Rather than in-lining the code in the README, you can find the example program in hailobot.pl. A sample config file is included. You just need to give it a valid Discord bot token.

Mojo::Discord::Gateway

The Discord "Gateway" is a persistent Websocket connection that sends out events as they happen to all connected clients. This module monitors the gateway and parses events, although once connected it largely reverts to simply passing the contents of each message to the appropriate callback function, as defined by the user.

The connection process goes a little like this:

1. Request a Gateway URL to connect to a. Seems to always return the same URL now, but in the past it looks like they had multiple URLs and servers.
2. Open a websocket connection to the URL received in Step 1.
3. Once connected, send an IDENTIFY message to the server containing info about who we are (Application-wise)
4. Gateway sends us a READY message containing (potentially) a ton of information about our user identity, the servers we are connected to, a heartbeat interval, and so on.
5. Use the Heartbeat Interval supplied in Step 4 to send a HEARTBEAT message to the server periodically. This lets the server know we are still there, and it will close our connection if we do not send it.

Now that we're connected and sending a heartbeat, all we have to do is listen for incoming messages and pass them off to the correct handler and callback functions.

Mojo::Discord::REST

The REST module exists for when you want your bot to take some kind of action. It's a fairly simple JSON API, you just need to include your bot token in the header for calls.

This module will implement calls for sending messages, indicating the user has started typing, and maybe a few other things that a text chat bot needs to be able to do.

Mojo::Discord::Auth

This module was created to implement parts of the OAuth2 authentication method for Discord. It is far from complete and still requires some copy/pasting, but it functions. Since OAuth is not required for bot clients, this module may not be included in the Mojo::Discord wrapper. Using it directly might make more sense.

Creating a new Mojo::Discord::Auth object takes the same arguments as above, but also requires an Application ID, Shared Secret, and the Auth Code received from the browser.

The only function implemented so far is request_token, which sends the auth code to the token endpoint and returns

• Access Token
• Refresh Token
• Expiration Time
• Token Type
• Access Scope

Example Code:

#!/usr/bin/env perl

use v5.10;
use warnings;
use strict;

use Mojo::UserAgent;
use Mojo::Discord::Auth;
use Data::Dumper

my $params = {
    'name' => 'Your Application Name',
    'url' => 'https://yourwebsite.com',
    'version' => '0.1',
    'code'  => $ARGV[0],
    'id'    => 'your_application_id',
    'secret' => 'your_application_secret',
};

my $auth = Mojo::Discord::Auth->new($params);

my $token_hash = $auth->request_token();

# Do something with the result
print Dumper($token_hash);