Home

Awesome

Mojo::Discord

A Perl wrapper for the Discord API, intended for use primarily with text-based chat bots.

This library was created to facilitate my own Discord Bot, Goose.

Modules

The primary modules involved are:

Below Mojo::Discord::Guild are smaller modules for various guild items such as channels, emoji, and roles.

Note: This is a spare-time project

Best intentions laid bare I have a lot of projects on the go and this one does not always receive the attention it deserves.

I have not abandoned the project nor do I have any intent to, but when my own needs are met (eg, Goose Bot is working) work on this library often stops.

You are welcome to submit pull requests if you want to build support parts of the API that I have not covered. The API is quite large and there are many aspects of it I have no plans to use and may not ever implement here myself (eg, Voice).

Pre-Requisites

These dependencies can be installed using cpanminus with the following command in the project root:

cpanm --installdeps .

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 all of the events it dispatches. The library stores information from some of these events to help it function and offer certain capabilities, but many of the events are simply re-emitted (Role::EventEmitter) to the client for it to use that information how it pleases. Clients can subscribe to these events if they wish to receive them.

The connection process goes a little like this:

  1. Request a Gateway URL to connect to
  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

Example Code:


#!/usr/bin/env perl

use v5.10;
use warnings;
use strict;

use Mojo::Discord;
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);