zigcord

A Discord API library written in Zig.

zigcord provides a native, high-performance implementation of the Discord Gateway and REST APIs using pure Zig, with zero external dependencies and complete control over memory, threading, and performance.

• Current version: 0.1.0 ("Gateway Starter")
• Zig target: 0.16.0-dev (latest master branch)
• License: Apache-2.0

Features

• Complete WebSocket implementation over TLS (RFC 6455)
• Full Discord Gateway v10 support, including heartbeating, identification, and dispatch routing
• Event callbacks for READY and MESSAGE_CREATE
• Threaded heartbeat with ACK tracking and zombie connection detection
• Session ID and resume URL caching with reconnect detection
• Working example bot with CLI token support

The library is under active development. See the roadmap below for planned features and current status.

Quick Start

Prerequisites

• Zig 0.16.0 development build (latest master from ziglang.org/download)
• A Discord bot token (obtain one from the Discord Developer Portal)

Building and Running the Example

git clone https://github.com/razen-core/zigcord.git
cd zigcord
zig build run-example-ping-bot -- <your-bot-token>

Alternatively, export the token and run:

DISCORD_TOKEN=your_token_here zig build run-example-ping-bot

The example bot logs in, prints your bot’s username and session ID on READY, and responds to the !ping command in text channels. Full REST-based replies will be available in v0.2.0.

Using as a Dependency (These will not work as the 0.1.0 version is in development, Sorry for inconvineince.)

In your build.zig.zon:

.dependencies = .{
    .zigcord = .{
        .url = "https://github.com/razen-core/zigcord/archive/refs/tags/v0.1.0.tar.gz",
        .hash = "...",  // run `zig fetch` or let `zig build` compute it
    },
},

In your build.zig:

const zigcord = b.dependency("zigcord", .{});
exe.root_module.addImport("zigcord", zigcord.module("zigcord"));

Note: In Zig 0.16.0+, dependencies are automatically fetched into a local zig-pkg directory next to your build.zig. Add zig-pkg/ to your .gitignore.

Documentation

Generate API documentation with:

zig build docs

Comprehensive reference documentation will be available at v1.0.0.

Roadmap

v0.1.0 — Gateway Starter (Complete)

• Core project structure and module system
• Core types (Snowflake, User, Message, ReadyData, etc.)
• Full WebSocket client with TLS, frame parsing, masking, and size limits
• Gateway connection with Identify, heartbeating, dispatch routing, and reconnect detection
• Public Client API with event callbacks
• Working ping_bot example

v0.2.0 — REST API Basics (In Progress)

• REST client with rate limiting and retry handling
• sendMessage, getChannel, getGuild
• Integration into event callbacks
• Functional replies in the ping bot example

v0.3.0 — Slash Commands

• Application command registration (global and guild-scoped)
• INTERACTION_CREATE handling
• Interaction responses and deferred replies

v0.4.0 — Reconnect & Session Resume

• Graceful Op 7 Reconnect handling
• Op 6 Resume with session ID and sequence number
• Exponential backoff and attempt limiting

v0.5.0 — Compression

• zlib-stream and optional zstd transport compression
• Configurable via ClientConfig

v0.6.0 — Sharding

• Shard management and Identify payload support
• Session start limit tracking

v0.7.0 — Caching Layer

• In-memory cache for guilds, channels, and users
• Configurable cache policies

v0.8.0 — Additional Events

• Guild, channel, message, reaction, presence, and voice events

v0.9.0 — Voice (Stretch Goal)

• Voice Gateway and UDP audio support

v1.0.0 — Stable Release

• Stabilized public API surface
• Complete inline documentation
• Conformance test suite with mock Gateway
• Publication to the Zig package index

For the full detailed roadmap including technical tasks and known issues, see ROADMAP.md.

Known Issues

• std.crypto.tls.Client API may see minor changes in ongoing 0.16.0-dev nightlies
• No Gateway send rate limiting yet
• Callback string lifetimes are tied to the internal JSON arena (freed after callback returns)
• Minor thread-safety notes on shared configuration fields (documented in source)

License

zigcord is licensed under the Apache License, Version 2.0. See the LICENSE file for the full text.

Copyright 2026 Razen Core & Prathmesh Barot

---

Repository: https://github.com/razen-core/zigcord
Issues and contributions are welcome. Please follow the guidelines in CONTRIBUTING.md.