Skip to content

A full featured Discord WebSocket and REST API.

License

Notifications You must be signed in to change notification settings

amiga-500/Nebucord

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

69 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Nebucord - Discord WebSocket and REST API

GitHub Release GitHub Development Github commits (since latest release) GitHub license

This is another implementation of the Discord API. It implements an HTTP WebSocket client as well as a REST API.
An actual in use sample can be found on our Discord server: Nebulatien Discord

If you need help or have questions, don't hestiate to contact Me. Best done if you join the above mentioned Discord server or (if you found something) create an issue in Github. Also pull request for fixes of course are welcome.

Of course not fully finished is it still able to do the most important things. This includes:

  • Nebucord WebSocket API

    • Setup bot and run bot(s)
    • Set status for bots
    • Simple control commands
    • Callback classes to intercept Discord gateway events
    • Changing default internal command behaviours
    • Setting user id's for bot controlling
    • Configurable by parameter or by .ini file
    • Customable gateway intents
  • Nebucord REST API

    • Model oriented interface on data receiving
    • Sending messages to a channel or DM
    • Receiving roles
    • Receiving message(s)
    • Receiving guild members
    • many more...
  • What's missing

    • Some models for events
    • Some models and methods for interacting with REST
    • Some gateway events
    • Many error checking
    • Way more better logging and debugging options
    • OAuth 2.0 client implementation
    • Multithreading (if applicable, thanks to bitnykk for the idea)

Default and available parameters

Parameter Config name INI config name Default value
Bot token token bottoken (string)empty
ACL user snowflakes ctrluser acl (array)[]
WS connection retries wsretries websocket.retries (integer)3
Default GW intent bitmask* intents intents.* (integer)32509 / (boolean)true*

*Note:
The intent bitmask defaults to be everything is true except GUILD_MEMBERS and GUILD_PRESENCES. These two options has to be manual set to true and they have to be activated in the Bot preferences on the Discord application management webpage. The bitmask is 32767 if everything set to true or for config as parameter.

Note:
Configuration by parameter has priority to configuration by .ini file.

Requirements

Additional Composer packages are required in order to run Nebucord.
Of course these can also be installed without Composer, but you have to include the SPL autoloader of the packages as well.

The recommended way is to use Composer.

Package informations:

Install

By composer:

user@linux:~# composer require eurobertics/nebucord

By Docker (more information can be found on Nebucord Docker Hub):

user@linux:~# docker pull eurobertics/nebucord:latest

Note:
If you want use .ini configuration, you have to put your .ini File (nebucord.ini i. e.) in the mounted directory for your Docker instance and set the path to the path of the docker working directory. You can find more information about this on the Nebucord Docker Hub Page.


By GIT:
Simple clone this repository and use the native autoloader file in ./src Directory.

user@linux:~# git clone https://github.com/Eurobertics/Nebucord.git

Note: If you use the library without composer, you just can include the native autoloader:

include "src/nebucord_autoloader.php";

Example usage - WebSocket API

The WebSocket API is designed to run as a PHP CLI program.

Usage websocket API, minimalistic example:

<?php
include "vendor/autoload.php";

use Nebucord\Nebucord;

$nebucord = new Nebucord(['token' => 'your_bot_token', 'ctrlusr' => ['controluser-snowflake1', 'controluser-snowflake2']]);
$nebucord->bootstrap()->run();

'your_bot_token': The auth token of your bot (from the Discord Dev-Portal)

'controluser-snowflake': The snowflake of Discord user(s) who can issue control commands such like 'shutdown' to the bot.

Of course this only starts the bot and this one sits there and does nothing.

A more complex example:

<?php
include "vendor/autoload.php";

use Nebucord\Nebucord;

class MessageInterceptorClass {
    public function onMessageReceive($evt) {
        // $evt is a model with all data from the gateway if a message create
        // event is received
        
        echo $evt->content; // returns the message
    }
}

$nebucordEventTable = \Nebucord\Events\Nebucord_EventTable::create();
$nebucordEventTable->addEvent(new MessageInterceptorClass, "onMessageReceive", \Nebucord\Base\Nebucord_Status::GWEVT_MESSAGE_CREATE);

$nebucord = new Nebucord(['token' => 'your_bot_token', 'ctrlusr' => ['controluser-snowflake1', 'controluser-snowflake2']]);
$nebucord->bootstrap()
    ->setEventTable($nebucordEventTable)
    ->run();

The above example prints out every message which was seen by the bot (based on the bot roles on the Discord guild). "Seen" means all CREATE_MESSAGE events from the Discord gateway.

Now on a console:

user@linux:~# php -f <your_php_file>.php

Example usage - REST API

Basic usage for sending a message:

<?php
include "vendor/autoload.php";

use Nebucord\NebucordREST;

$nebucordREST = new NebucordREST(['token' => 'your_bot_token']);
$message_model = $nebucordREST->channel->createMessage(123123123123 /* channel id */, "message");

"$message_model" is an object with the answer from the REST gateway.

Basic usage for receiving guild channels:

Basic usage for sending a message:

<?php
include "vendor/autoload.php";

use Nebucord\NebucordREST;

$nebucordREST = new NebucordREST(['token' => 'your_bot_token']);
$channels = $nebucordREST->guild->getGuildChannels(123123123123123 /* guild id*/);

"$channels" is an array of channel models for processing.

More info

For more information see: Discord Developer Portal

About

A full featured Discord WebSocket and REST API.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • PHP 99.4%
  • Dockerfile 0.6%