Download the PHP package nwilging/laravel-discord-bot without Composer

Laravel Discord Bot

A robust Discord messaging integration for Laravel

About

This package provides a notification channel to send messages to Discord, as well as a suite of tools, services, and components that will help you to build rich-text messages as well as handle Discord Interactions.

Installation

Pre Requisites

1. Laravel v8+
2. PHP 7.4+
3. libsodium

Install with Composer

Configuration

1. Visit the Discord Developer Portal and create a new Application
2. Copy the Application ID and the Public Key
3. Create a Bot User
4. Reset the Bot User Token and copy it

Populate your .env:

Additional Configuration (optional)

When handling interactions the default response behavior is to "defer" - aka stop the loading process in the Discord app window and return no reply or other message. If you'd like to change this to "load" - which will show a loading message until your application sends a followup message - add the following to your .env:

Notification Channel Usage

Your notification class must implement the interface Nwilging\LaravelDiscordBot\Contracts\Notifications\DiscordNotificationContract, and include the toDiscord(): array method.

Example with Plain Text message

Example with Rich Text message

How to get a channelId

How to find Discord IDs

You must specify the actual ID of the channel when sending messages to the Discord API. This can be done directly in the Discord client application by enabling developer tools.

Interactions Usage

If you are sending messages that have components such as buttons, inputs, menus, etc, Discord will be prepared to send user interactions with these components as requests to a specified endpoint - essentially a webhook - with the interaction event payload.

Setting up interactions

First setup a controller and/or route that you plan to use as the callback URL for interactions. Within the controller for this route, inject the Nwilging\LaravelDiscordBot\Contracts\Services\DiscordInteractionServiceInterface.

You will call the handleInteractionRequest method on the aforementioned service. Example:

This will forward interactions requests from Discord through your app. You must forward requests through this interaction service: Discord requires signature verification, which this package performs automatically on every interactions request. Attempting to handle requests outside of this package is possible, but not recommended.

Listening for Interaction Events

When a user interacts with a component in your message - such as a button - this interaction is sent to your application. This package will handle that interaction request and will dispatch an event when a new message component interaction payload comes in.

This event is Nwilging\LaravelDiscordBot\Events\MessageComponentInteractionEvent, which contains a method getInteractionRequest, which will return the ParameterBag from the original request object. You may call ->all() on this to retrieve the array representation of the interaction payload.

Your listeners should implement ShouldQueue to prevent long-running synchronous processes from timing out the Discord interaction request and presenting an error to the user. You may use synchronous listeners, but be aware that if an error occurs during processing, the user will likely see a This interaction failed error message in Discord.

Extending the message component interaction handler

The MessageComponentInteractionHandler does not support extending its functionality directly. However, it does support the ability for your application to override the immediate response that is sent to Discord upon handling an interaction.

This is useful if you'd like to send a reply message when an interaction takes place or if you'd like to alter the default behavior of message component interactions specifically.

The MessageComponentInteractionHandler will check for any listeners in your application implementing the contract Nwilging\LaravelDiscordBot\Contracts\Listeners\MessageComponentInteractionEventListenerContract. To override the default response, your listener must implement this interface.

Since this is a listener, you do need to implement the handle method. It is recommended to combine this type of functionality with a listener you plan to use to handle the actual message component interaction event.

Application Commands

Discord Application Commands are versatile commands that your bot can offer to users and receive subsequent interactions from. This package provides both the ability to create, update, and delete commands as well as handle interactions from commands.

Command Builder

There are three types of commands available:

• Slash Command - Nwilging\LaravelDiscordBot\Support\Commands\SlashCommand
• Message Command - Nwilging\LaravelDiscordBot\Support\Commands\MessageCommand
• User Command - Nwilging\LaravelDiscordBot\Support\Commands\UserCommand

Command types have different options associated with them. For example, slash commands may specify "options" which are essentially "arguments".

Options for commands can be found in Nwilging\LaravelDiscordBot\Support\Commands\Options.

Here is an example of creating a SlashCommand:

To create this command on Discord, use the Nwilging\LaravelDiscordBot\Services\DiscordApplicationCommandService:

To update a command, you may either use the create methods or use the update methods.

Because commands have unique names within a type and scope, we treat POST requests for new commands as upserts. That means making a new command with an already-used name for your application will update the existing command.

Discord Docs

To delete a command you just need the command ID:

Listening for Command Interactions

Extending the application command handler is nearly identical to the Message Interaction Listener, see extending the interaction handler.

Your listeners should listen for Nwilging\LaravelDiscordBot\Events\ApplicationCommandInteractionEvent:

The event itself has a few helper methods to quickly get commonly used data from the interaction:

Command types are stored as constants on Nwilging\LaravelDiscordBot\Support\Command: