SwiftDisc

A modern, Swift-native Discord API library for building powerful bots

Build Discord bots and integrations with the elegance of Swift — fully async, strongly typed, and production-ready.

SwiftDisc brings the power of modern Swift to Discord bot development. Whether you're building a simple utility bot or a complex multi-server application, SwiftDisc provides the tools you need with an API that feels natural to Swift developers.

• 🎯 Swift-First Design — Built from the ground up for Swift, leveraging async/await, actors, and structured concurrency
• 🔒 Type Safety — Comprehensive type-safe models that catch errors at compile time
• 🌍 Truly Cross-Platform — Deploy on iOS, macOS, tvOS, watchOS, and Windows with the same codebase
• ⚡ Production Ready — Automatic rate limiting, connection resilience, and sharding support out of the box
• 🎨 Developer Friendly — Intuitive APIs inspired by discord.py, adapted for Swift's strengths

• First-time bot developers looking for a modern, well-documented library
• Swift developers wanting to leverage their existing skills
• Cross-platform projects requiring deployment flexibility
• Production applications demanding reliability and performance

Get your first bot running in minutes:

import SwiftDisc

@main
struct MyFirstBot {
    static func main() async {
        let token = ProcessInfo.processInfo.environment["DISCORD_BOT_TOKEN"] ?? ""
        let client = DiscordClient(token: token)
        
        do {
            try await client.loginAndConnect(intents: [.guilds, .guildMessages, .messageContent])
            
            for await event in client.events {
                switch event {
                case .ready(let info):
                    print("✅ Bot is online as \(info.user.username)!")
                    
                case .messageCreate(let message) where message.content == "!hello":
                    try await client.sendMessage(
                        channelId: message.channel_id,
                        content: "👋 Hello, \(message.author.username)!"
                    )
                    
                default:
                    break
                }
            }
        } catch {
            print("❌ Error: \(error)")
        }
    }
}

// Create (image should be data URI string, e.g. "data:image/png;base64,<...>")
let created = try await client.createAppEmoji(
  applicationId: appId,
  name: "party",
  imageBase64: "data:image/png;base64,....",
  options: ["roles": .array([])] // optional extras
)

// Update
let updated = try await client.updateAppEmoji(
  applicationId: appId,
  emojiId: "1234567890",
  updates: ["name": .string("party_blob")] 
)

// Delete
try await client.deleteAppEmoji(
  applicationId: appId,
  emojiId: "1234567890"
)

// Create resource under your application scope
let res = try await client.createUserAppResource(
  applicationId: appId,
  relativePath: "directory/listings",
  payload: ["title": .string("My Awesome App"), "enabled": .bool(true)]
)

// Update resource
let upd = try await client.updateUserAppResource(
  applicationId: appId,
  relativePath: "directory/listings/abc",
  payload: ["enabled": .bool(false)]
)

// Delete resource
try await client.deleteUserAppResource(
  applicationId: appId,
  relativePath: "directory/listings/abc"
)

That's it! You now have a working Discord bot. 🎉

Add SwiftDisc to your Package.swift:

dependencies: [
    .package(url: "https://github.com/M1tsumi/SwiftDisc.git", from: "0.8.0")
]

Then include it in your target:

targets: [
    .target(name: "YourBot", dependencies: ["SwiftDisc"])
]

We've created comprehensive examples to help you get started:

Perfect for understanding the basics of event handling and message responses.

// Responds to "!ping" with the bot's latency
case .messageCreate(let message) where message.content == "!ping":
    try await client.sendMessage(
        channelId: message.channel_id,
        content: "🏓 Pong! Latency: 42ms"
    )

View Full Example →

Learn how to build a command system with prefix routing and help commands.

let router = CommandRouter(prefix: "!")
router.register("help") { context in
    try await context.reply("Available commands: !help, !userinfo, !serverinfo")
}

View Full Example →

Discover modern Discord interactions with slash commands and autocomplete.

let slash = SlashCommandRouter()
slash.register("greet") { interaction in
    try await interaction.reply("Hello from SwiftDisc! 👋")
}

Slash Bot →

Dynamic suggestions for command options using AutocompleteRouter.

Autocomplete Bot →

Multipart uploads with content-type detection and size guardrails.

File Upload Bot →

Listen to thread lifecycle and guild scheduled events.

Threads & Scheduled Events →

Our Wiki provides in-depth guides for:

• 🎯 Core Concepts — Understanding intents, events, and the Discord API
• 🔧 Configuration — Setting up your bot for development and production
• 🎨 Message Features — Embeds, components, attachments, and more
• ⚙️ Sharding — Scaling your bot across multiple servers
• 🚀 Deployment — Best practices for production environments

• 💬 Join our Discord Server — Get real-time support from the community
• 📖 Browse the Wiki — Detailed documentation and tutorials
• 🐛 Report Issues — Found a bug? Let us know!
• 💡 GitHub Discussions — Share your projects and ideas

• ✅ Full WebSocket gateway implementation
• ✅ Automatic heartbeat and session management
• ✅ Resume support for connection recovery
• ✅ Structured event system with AsyncSequence
• ✅ Presence updates and status management
• ✅ Threads and Scheduled Events (create/update/delete, members add/remove)
• ✅ 100% event visibility via DiscordEvent.raw(String, Data) fallback for unmodeled dispatches

• ✅ Channels — Create, modify, delete channels and threads
• ✅ Messages — Send, edit, delete with embeds and components
• ✅ Guilds — Full server management capabilities
• ✅ Members & Roles — User and permission management
• ✅ Slash Commands — Create and manage application commands
• ✅ Webhooks — Create and execute webhooks
• ✅ Auto Moderation — Configure moderation rules
• ✅ Scheduled Events — Create and manage server events
• ✅ Forum Channels — Create threads and posts
• ✅ Raw coverage helpers: rawGET/POST/PATCH/PUT/DELETE for any unsupported endpoint

// Timeout a member until a specific ISO8601 timestamp
let in10Min = Date().addingTimeInterval(10 * 60)
let updated: GuildMember = try await client.setMemberTimeout(guildId: guildId, userId: userId, until: in10Min)

// Clear timeout
let cleared: GuildMember = try await client.clearMemberTimeout(guildId: guildId, userId: userId)

• ✅ Per-route rate limit handling with automatic retries
• ✅ Global rate limit detection and backoff
• ✅ Sharding support with automatic shard count
• ✅ Health monitoring and shard management
• ✅ Typed command routing (prefix and slash) + Autocomplete router
• ✅ Rich embed builder and message components (buttons, select menus)
• ✅ File uploads: multipart with content-type detection and configurable guardrails (maxUploadBytes)
• ✅ Advanced caching: configurable TTLs and per-channel message LRU
• ✅ Extensions/Cogs: simple plugin protocol and Cog helper; DiscordClient.loadExtension(_:)
• ✅ Permissions utilities: effective permission calculator with channel overwrites

Use postMessage(channelId:payload:) with JSONValue to send Components V2 while keeping SwiftDisc zero-dependency and future-proof. Paste the payload from the Discord docs.

// Example skeleton – replace with the latest Components V2 JSON from docs
let payload: [String: JSONValue] = [
  "content": .string("Hello with Components V2"),
  "flags": .int(1 << 15), // if docs require enabling V2 via flag
  "components": .array([
    .object(["type": .int(1), "children": .array([ /* ... */ ])])
  ])
]
let msg = try await client.postMessage(channelId: channelId, payload: payload)

Typed envelope helper:

let v2 = V2MessagePayload(
  content: "Hello with V2",
  flags: 1 << 15, // if required by docs
  components: [
    .object(["type": .int(1), "children": .array([ /* ... */ ])])
  ]
)
let msg = try await client.sendComponentsV2Message(channelId: channelId, payload: v2)

Use createPollMessage(channelId:content:poll:flags:components:) with a poll object conforming to the Poll Resource schema.

// Example skeleton – replace with the Poll Resource JSON from docs
let poll: [String: JSONValue] = [
  "question": .object(["text": .string("Your favorite language?")]),
  "answers": .array([
    .object(["answer_id": .int(1), "poll_media": .object(["text": .string("Swift")])]),
    .object(["answer_id": .int(2), "poll_media": .object(["text": .string("Kotlin")])])
  ]),
  "allow_multiple": .bool(false),
  "duration": .int(600) // seconds
]
let msg = try await client.createPollMessage(channelId: channelId, content: "Vote now!", poll: poll)

Typed envelope helper:

let pollPayload = PollPayload(
  question: "Your favorite language?",
  answers: ["Swift", "Kotlin"],
  durationSeconds: 600,
  allowMultiple: false
)
let msg = try await client.createPollMessage(channelId: channelId, payload: pollPayload, content: "Vote now!")

Update command name/description localizations:

let updated = try await client.setCommandLocalizations(
  applicationId: appId,
  commandId: cmdId,
  nameLocalizations: [
    "en-US": "ping",
    "ja": "ピン"
  ],
  descriptionLocalizations: [
    "en-US": "Check latency",
    "ja": "レイテンシーを確認"
  ]
)

Post a message in another channel that references an existing message (portable forward):

let forwarded = try await client.forwardMessageByReference(
  targetChannelId: targetChannelId,
  sourceChannelId: sourceChannelId,
  messageId: messageId
)

Use these helpers to call application-scoped endpoints with JSONValue payloads. This keeps SwiftDisc current as Discord evolves.

// POST /applications/{appId}/{relativePath}
let createRes = try await client.postApplicationResource(
  applicationId: appId,
  relativePath: "some/feature",
  payload: ["key": .string("value")]
)

// PATCH /applications/{appId}/{relativePath}
let patchRes = try await client.patchApplicationResource(
  applicationId: appId,
  relativePath: "some/feature/id",
  payload: ["enabled": .bool(true)]
)

// DELETE /applications/{appId}/{relativePath}
try await client.deleteApplicationResource(
  applicationId: appId,
  relativePath: "some/feature/id"
)

• ✅ Mentions: Mentions.user(_:), Mentions.channel(_:), Mentions.role(_:), Mentions.slashCommand(name:id:)
• ✅ Emoji helpers: EmojiUtils.custom(name:id:animated:)
• ✅ Timestamps: DiscordTimestamp.format(date:style:), format(unixSeconds:style:)
• ✅ Escaping: MessageFormat.escapeSpecialCharacters(_:)

SwiftDisc is built for real-world applications:

• Automatic Reconnection — Handles network issues gracefully
• Rate Limit Compliance — Respects Discord's limits automatically
• Session Resume — Maintains connection state across reconnects

• Sharding Support — Built-in multi-shard management
• Health Monitoring — Track shard status and latency
• Graceful Shutdown — Clean disconnection handling

• Comprehensive Logging — Detailed logs for debugging
• Type-Safe APIs — Catch errors at compile time
• Clear Error Messages — Actionable error descriptions

// Automatic sharding for large bots
let manager = await ShardingGatewayManager(
    token: token,
    configuration: .init(
        shardCount: .automatic,
        connectionDelay: .staggered(interval: 1.5)
    ),
    intents: [.guilds, .guildMessages]
)

try await manager.connect()

// Monitor health across all shards
let health = await manager.healthCheck()
print("Ready shards: \(health.readyShards)/\(health.totalShards)")

We're building SwiftDisc together with the community! Whether you're a beginner looking to create your first bot or an experienced developer with feature requests, we'd love to have you.

We're actively developing SwiftDisc with these priorities:

• Autocomplete
• File uploads polish (MIME + guardrails)
• Gateway parity: Threads & Scheduled Events + raw fallback
• Advanced caching & permissions utilities
• Extensions/Cogs

• Voice support (optional module)
• Voice support (send‑only MVP)
• Performance optimizations

Want to influence the roadmap? Join the Discord server and share your ideas!

Initial voice support is available behind a configuration flag. This is a send-only implementation that connects to Discord Voice, performs UDP IP discovery, negotiates xsalsa20_poly1305, and can transmit Opus frames (no external dependencies required).

Enable and use:

let config = DiscordConfiguration(enableVoiceExperimental: true)
let client = DiscordClient(token: token, configuration: config)

try await client.joinVoice(guildId: guildId, channelId: channelId)

// Option A: Push individual Opus packets (20ms @ 48kHz)
try await client.playVoiceOpus(guildId: guildId, data: opusPacket)

// Option B: Stream from a VoiceAudioSource
struct MySource: VoiceAudioSource {
    func nextFrame() async throws -> OpusFrame? { /* return OpusFrame(data:packet,durationMs:20) */ }
}
try await client.play(source: MySource(), guildId: guildId)

try await client.leaveVoice(guildId: guildId)

What’s included:

• Voice Gateway handshake (Hello → Identify → Ready → Heartbeat)
• UDP IP discovery (Network.framework on Apple platforms)
• Protocol selection (xsalsa20_poly1305)
• Session Description key handling
• RTP packetization + pure-Swift Secretbox encryption (no SwiftPM deps)
• Speaking flag management

Requirements:

• Input must be Opus-encoded packets at 48kHz (20ms recommended). SwiftDisc does not bundle an Opus encoder or media demuxer to maintain zero dependencies.

macOS streaming with ffmpeg (no Swift dependencies):

Use an external ffmpeg (system-installed) to demux/encode your source (YouTube, SoundCloud, etc.) to raw Opus packets and pipe them into SwiftDisc. Implement a small wrapper to length-prefix packets (u32 LE) or use a helper that outputs framed Opus.

Example framing expected by PipeOpusSource:

• Frame format: [u32 little-endian length][<length> bytes] repeated.

Use PipeOpusSource:

import Foundation

let source = PipeOpusSource(handle: FileHandle.standardInput)
try await client.play(source: source, guildId: guildId)

Then run your bot and feed framed Opus via stdin. For example, you can create a small CLI that transforms ffmpeg output to the framed format and pipe to the bot. This keeps SwiftDisc zero-dependency.

iOS guidance:

• iOS cannot spawn ffmpeg. Provide Opus packets from your app/backend over your own transport (e.g., HTTPS/WebSocket) and feed them to a VoiceAudioSource.

Security and correctness:

• SwiftDisc vendors a pure-Swift Secretbox (XSalsa20-Poly1305) implementation with Poly1305 MAC and Salsa20 core. Nonce derivation follows the Discord RTP header convention. We recommend validating with your own test vectors as part of your CI.

Contributions make SwiftDisc better for everyone! Here's how you can help:

• 🐛 Report Bugs — Found an issue? Open an issue
• 💡 Suggest Features — Have an idea? Start a discussion
• 📝 Improve Docs — Documentation improvements are always welcome
• 🔧 Submit PRs — Code contributions are appreciated!

Check our Contributing Guidelines for more details.

SwiftDisc is released under the MIT License. See LICENSE for details.

In short: You're free to use SwiftDisc for personal and commercial projects, with attribution.