PawSharp

Build Discord bots without fighting your framework.

Docs · Examples · Changelog · NuGet · Discord

---

We're at 1.1.0-alpha.4 - core pieces work, things are still settling.

Why PawSharp?

PawSharp is built for modern .NET from the ground up - modular packages, async-first APIs, source-generated JSON for native AOT, and a fluent builder that's actually pleasant to configure.

• Modular packages - install only what you need. Use the full client for traditional bots, or compose just PawSharp.API + PawSharp.Cache for a lightweight REST-only setup.
• async-first - every public API returns Task<T> or ValueTask<T>. No .Result, no .Wait(), no sync-over-async footguns.
• Typed events - gateway events map to strongly-typed C# classes with proper nullable annotations. No guessing what a JToken contains.
• Automatic rate limiting - built into the REST client with bucket tracking, global rate limit detection, and configurable retry. Handled transparently.
• Fluent builder - configure with .WithToken(), .WithIntents(), .UseConsoleLogging() instead of a wall of constructor arguments.
• Native AOT ready - source-generated JsonSerializerContext for every serializable type. No runtime reflection for JSON. Trimming-safe.
• Pure .NET voice - Opus via Concentus (no native DLLs). DAVE E2EE encrypted voice (MLS / RFC 9420).

---

Quickstart

dotnet add package PawSharp.Client --version 1.1.0-alpha.4

using PawSharp.Client;
using PawSharp.Core.Enums;

var token = Environment.GetEnvironmentVariable("DISCORD_TOKEN")
    ?? throw new InvalidOperationException("Set DISCORD_TOKEN before running.");

var client = new PawSharpClientBuilder()
    .WithToken(token)
    .WithIntents(GatewayIntents.AllNonPrivileged | GatewayIntents.MessageContent)
    .UseConsoleLogging()
    .Build();

client.OnMessageCreated(async evt =>
{
    if (evt.Author?.IsBot == true) return;
    if (evt.Content == "!ping")
        await client.SendMessageAsync(evt.ChannelId, "Pong!");
});

await client.ConnectAsync();
await Task.Delay(Timeout.Infinite);

$ DISCORD_TOKEN="your-token" dotnet run
> !ping
< Pong!

This example shows: configuring a client, connecting to Discord, listening for events, sending a message.

---

Which package do I need?

If you want to...	Install
Build a normal Discord bot	PawSharp.Client
Use only the REST API	PawSharp.API
Add slash commands	PawSharp.Commands + PawSharp.Interactions
Add voice support	PawSharp.Voice
Add caching	PawSharp.Cache

PawSharp.Client already includes the packages most bots need - you're done with one dotnet add package.

---

What's in the box

REST API - channels, messages, guilds, members, roles, webhooks, threads, slash commands, audit logs, auto-moderation, scheduled events, stage instances, stickers, soundboard, polls, and entitlements. Rate limits are handled automatically.

Gateway - WebSocket client with resume, heartbeat monitoring, and backoff reconnection. Sharding is built-in. Events map to typed C# objects.

Commands - attribute-based prefix commands with middleware, type conversion, and preconditions (permissions, roles, cooldowns). Module auto-discovery is one method call.

Interactions - slash commands, buttons, select menus, modals, autocomplete, context menus. The interaction handler routes them with error recovery so users don't see "This interaction failed."

Interactivity - pagination, confirmation dialogs, input prompts, polls. Async and timeout-based.

Voice - join voice channels, play and receive audio. Pure .NET Opus via Concentus, no native dependencies. DAVE E2EE (MLS / RFC 9420) for encrypted voice. See the voice guide.

Caching - in-memory or Redis, per-entity TTL, eviction, health checks. Providers can be swapped at runtime.

---

Working examples

The examples/ directory has bots you can run:

• ModerationBot - REST operations, gateway events, basic moderation. Uses the low-level API.
• MusicBot - DI setup, commands, voice. Shows the module pattern.
• DashboardBot - ASP.NET integration, interaction handlers, webhook verification.

Each has its own README.

---

Learn more

• Getting Started
• REST API
• Gateway Events
• Commands & Interactions
• Voice
• Caching
• Patterns & Best Practices
• Error Handling
• Migration Guide
• Troubleshooting

---

Versioning

We follow SemVer. Until 1.0.0, minor bumps may include breaking changes. The changelog and migration guide track everything.

---

Contributing

Pull requests welcome. Read CONTRIBUTING.md first.

---

Community

Join our Discord - questions, ideas, or just to hang out.

---

License

MIT. See LICENSE.

---