API Reference

The following section outlines the API of Erebus.

Note

This library uses Python logging module to log info, errors, debug messages and other diagnostics.

Starter Point

Client

class erebus.Client(app: Flask, application_public_key: str, **options: Any)

Represents a client that provides an interface for handling interactions sent by Discord. The focus of this class is to aid in handling interactions by abstracting away the steps like request validations etc. and also provide a rich decorator based interface to handle commands etc.

If you wish to have full control over the interactions, there is a lower level API that allows you to do that and you don’t need this class in that case.

Note

All parameters except app and application_public_key are keyword only and optional.

app: Flask

The main flask app that would be used.

application_public_key: str

The discord’s application public key, This can be obtained from Discord Developer Portal.

path: str

The path that would be used for interactions. Defaults to “/”

application_id: Optional[int]

The application ID of the application sending interactions. This can be None before the very first interaction.

handle_interaction() → Any

Verifies a request and handles an interaction sent by Discord.

This function is under-the-hood called inside on_request() and must also be called in case of overriding that method.

The request will be aborted with 401 if it is not verified to be a request from Discord.

on_request() → Any

The method called when a request is done on the set path.

This method shouldn’t generally be overridden as library provides a rich interface that doesn’t require you to manually handle the interactions.

Nevertheless, If you wish to override this method, You must call handle_interaction() in this method to handle the interactions properly otherwise library’s implementation of interactions handling wouldn’t work.

Low Level API

This part of documentation covers some lower level part of API that can be used to manually handle the interactions.

erebus.verify_key(application_public_key: str) → bool

Verifies the request and checks if it is actually sent by Discord. Returns a boolean that indicates whether the request is valid or not.

This is a lower level of handle_interaction() to provide more control over interactions and aid in manual handling of interactions.

application_public_key: str

The public key of your application.

bool

Whether the request is valid or not. False indicates that request is not valid.

Enumerations

The API provides some enumerations for certain types of strings to avoid the API from being stringly typed in case the strings change in the future.

These Enumerations are used in both cases whether you are using manually handling the interactions or even if you are using higher level API to handle them.

class erebus.InteractionType

Represents the type of an interaction.

PING

The interaction is a PING interaction. PING interactions are responded with InteractionCallbackType.PONG.

APPLICATION_COMMAND

The interaction is an application command interaction i.e slash commands etc.

MESSAGE_COMPONENT

The interaction is a message component interaction i.e a user clicked on a button.

APPLICATION_COMMAND_AUTOCOMPLETE

The interaction is a slash command option autocomplete interaction. Autocomplete is only valid for CommandType.USER_INPUT

COMMAND

An alias for APPLICATION_COMMAND

COMPONENT

An alias for MESSAGE_COMPONENT

AUTOCOMPLETE

An alias for APPLICATION_COMMAND_AUTOCOMPLETE

class erebus.InteractionCallbackType

Represents the response or callback type of an interaction.

PONG

The response is a PONG interaction to a PING interaction.

CHANNEL_MESSAGE_WITH_SOURCE

The response is a normal sending of message.

DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE

The response is acknowledment (deferring) of an interaction.

DEFERRED_UPDATE_MESSAGE

Only valid for InteractionType.COMPONENT The response is acknowledment (deferring) of a component interaction.

UPDATE_MESSAGE

The response is editing of original response.

APPLICATION_COMMAND_AUTOCOMPLETE_RESULT

The response is the result of an InteractionType.APPLICATION_COMMAND_AUTOCOMPLETE interaction.

class erebus.CommandType

Represents the type of an application command.

USER_INPUT

The command is a slash command or user input command.

USER

The command is a user context menu command.

MESSAGE

The command is a message context menu command.

SLASH_COMMAND

An alias for USER_INPUT

USER_COMMAND

An alias for USER

MESSAGE_COMMAND

An alias for MESSAGE

Discord Data Models

These are the data models that contain information sent by Discord like messages, users etc.

It is advised that you do not change the attributes of these classes as it might result in unexpected issues, Furthermore, For performance purposes, It is not possible to have dynamic attributes in these classes because every class has __slots__ which makes having dynamic attributes almost impossible.

Interaction

class erebus.Interaction(data: InteractionPayload, client: Client)

Represents an interaction sent by Discord.

An interaction occurs when a user interacts with your application like interact with a message component or use an application command. This class contains information sent by Discord in an interaction.

id: int

The unique snowflake ID of the interaction.

application_id: int

The unique snowflake ID of the application that this interaction belongs to, usually the ID of your bot.

type: InteractionType

The type of interaction as InteractionType enum.

token: str

The unique token of an interaction that can be used to send followup messages and respond to interaction. This token is valid for upto 15 minutes.

version: int

The version of interaction, this is usually 1

data: Dict[str, Any]

The raw data of interaction that depends upon the type of interaction. if no data is sent then this defaults to an empty dict.

guild_id: Optional[int]

The ID of guild in which this interaction was invoked. Could be None in case when an interaction occured within Direct messages or outside of a guild.

channel_id: Optional[int]

The channel ID of channel in which this interaction was invoked. Could be None in case when an interaction occured within Direct messages or outside of a guild channel.

user: User

The user that invoked the interaction. This is always present regardless of the channel in which interaction occured.

member: Member

The member that invoked the interaction in a guild. This could be None if interaction didn’t occur in a guild.

message: Message

The message that invoked the interaction, only available if Interaction.type is InteractionType.MESSAGE_COMPONENT

property response: erebus.interactions.InteractionResponse

InteractionResponse: Returns the class responsible for handling responses of this interaction.

InteractionResponse

class erebus.InteractionResponse(interaction: erebus.interactions.Interaction)

A class that aids in responding to interactions and handling different type of interaction responses i.e deferring, message creations and updates etc.

This class should NOT be initalized manually and the one and the only way of getting this class is by Interaction.response.

Note

You can respond to an interaction only once, further responses should be done using follow-up webhooks, See Interaction.followup for more information.