A lightweight wrapper for Discord's HTTP interactions using py-cord and FastAPI. This library enables you to build Discord bots that work exclusively through Discord's HTTP interactions, without requiring a WebSocket gateway connection.

About

Pycord REST allows you to build Discord bots that respond to interactions via HTTP endpoints as described in Discord's interaction documentation and interaction overview.

This project is built on:

FastAPI - For handling the HTTP server
py-cord - Leveraging Discord command builders and interaction handling
uvicorn - ASGI server implementation

Installation

pip install pycord-rest-bot

Quick Start

from pycord_rest import App
import discord

app = App(intents=discord.Intents.default())

@app.slash_command(name="ping", description="Responds with pong!")
async def ping(ctx):
    await ctx.respond("Pong!")

if __name__ == "__main__":
    app.run(
        token="YOUR_BOT_TOKEN",
        public_key="YOUR_PUBLIC_KEY",  # From Discord Developer Portal
        uvicorn_options={
            "host": "0.0.0.0",
            "port": 8000
        }
    )

Usage

Setting up your bot on Discord

Create a bot on the Discord Developer Portal
Enable the "Interactions Endpoint URL" for your application
Set the URL to your public endpoint where your bot will receive interactions
Copy your public key from the Developer Portal to verify signatures

Features

Slash Commands
UI Components (buttons, select menus)
Modal interactions
Autocomplete for commands

Similarities to py-cord

Syntax is equivalent to py-cord, as it is what is being used under the hood, making it easy to adapt existing bots:

@app.slash_command(name="hello", description="Say hello")
async def hello(ctx, user: discord.Member = None):
    user = user or ctx.author
    await ctx.respond(f"Hello {user.mention}!")

@app.slash_command()
async def button(ctx):
    view = discord.ui.View()
    view.add_item(discord.ui.Button(label="Click me!", custom_id="my_button"))
    await ctx.respond("Press the button!", view=view)

Limitations

This library works differently than traditional bots because it does not use Discord's WebSocket gateway:

No Cache: Since there's no gateway connection, there's no cache of guilds, channels, users, etc.
Limited API Methods: Many standard py-cord methods that rely on cache won't work properly:
- app.get_channel(), app.get_guild(), app.get_user(), etc.
- Presence updates
- Voice support
- Member tracking
Event-Based Functions: Only interaction-based events work; message events, etc. don't work

Remember that this is an HTTP-only bot that responds exclusively to interactions triggered by users.

Configuration Options

app.run(
    token="YOUR_BOT_TOKEN",
    public_key="YOUR_PUBLIC_KEY",
    uvicorn_options={
        "host": "0.0.0.0",
        "port": 8000,
        "log_level": "info",
        # Any valid uvicorn server options
    },
    health=True  # Enable /health endpoint
)

Advanced Usage

Adding Custom FastAPI Routes

from fastapi import Request

@app.router.get("/custom")
async def custom_endpoint(request: Request):
    return {"message": "This is a custom endpoint"}

Contributing

Contributions are welcome! This project is in early development, so there might be bugs or unexpected behaviors.

Fork the repository
Create a feature branch
Make your changes
Run tests and linting: ruff check and ruff format
Submit a pull request

Development Tools

Ruff: For linting and formatting
HashiCorp Copywrite: For managing license headers
basedpyright: For type checking

Disclaimer

This is an early-stage project and may have unexpected behaviors or bugs. Please report any issues you encounter.

License

Made with ❤️ by Paillat-dev