Lanyard: Expose Discord Presence to REST and WebSocket APIs in Seconds

For developers seeking to integrate real-time user status data into web applications, Lanyard offers a streamlined solution. This open-source service allows users to export their live Discord presence to a RESTful API endpoint and a WebSocket connection with minimal setup. By bridging the gap between Discord's internal state and external web environments, Lanyard enables the creation of dynamic personal websites, dashboards, and automated bots that react to user activity in real time.

Core Functionality and Setup

The primary value proposition of Lanyard is its simplicity. Users can join the official Lanyard Discord server, and their presence data will immediately become accessible via a public API endpoint. The standard endpoint follows the format api.lanyard.rest/v1/users/:your_id. This allows developers to retrieve detailed information about a user's current status, such as whether they are online, idle, or in a specific voice channel.

Beyond basic presence tracking, Lanyard functions as a globally accessible, real-time Key-Value (KV) store. This feature is particularly useful for automation tools and bots that need to persist or share small amounts of dynamic data. Users can update this KV store directly through the Lanyard Discord bot or via the Lanyard API, providing a flexible backend for custom applications.

Just join this Discord server and your presence will start showing up when you GET api.lanyard.rest/v1/users/:your_id . It's that easy.

Real-Time Data via WebSocket

While REST APIs are suitable for polling data at intervals, Lanyard also provides a WebSocket connection for true real-time updates. The WebSocket endpoint is available at wss://api.lanyard.rest/socket. This connection allows applications to subscribe to presence changes for specific users or all monitored users, ensuring that data is pushed to the client the moment it changes.

The WebSocket protocol used by Lanyard follows a structured handshake process. Upon connection, the server sends a Hello opcode containing the heartbeat_interval. Clients must then send an Initialize opcode to specify which user IDs they wish to subscribe to. This mechanism ensures efficient data delivery and allows developers to build responsive interfaces that update live without the latency associated with frequent HTTP requests.

Managing the Key-Value Store

The Lanyard KV store is integrated into the user API response, meaning any update to a KV pair triggers a PRESENCE_UPDATE event through the WebSocket. To interact with this store, users must first obtain an API key by DMing the Lanyard bot with the command .apikey. This key is then used in the Authorization header for subsequent API requests.

Developers can use standard HTTP methods to manage this data:

• PUT: Sets a specific key to a new value. The body of the request contains the data, which is string-encoded in the store.
• PATCH: Merges a new set of key-value pairs into the existing store. Conflicting keys are overwritten, and the body must be a flat object with a maximum depth of one.
• DELETE: Removes a specific key from the user's KV store.

Community Ecosystem and Integrations

The Lanyard project has fostered a vibrant community of developers who have created numerous libraries and tools to extend its functionality. These integrations cover a wide range of front-end and back-end technologies, making it easy to incorporate Lanyard data into existing projects.

For React developers, the use-lanyard library is the recommended choice. It subscribes over the WebSocket, allowing multiple hooks across an application to share a single connection. This reduces overhead and ensures that presence data updates live across the entire app. Similarly, vue-lanyard and svelte-lanyard provide support for Vue and Svelte, respectively, offering both REST and WebSocket methods.

Other notable community projects include:

• lanyard-profile-readme: A tool that utilizes Lanyard to display Discord presence directly on GitHub profile READMEs.
• lanyard-visualizer: A project focused on beautifully displaying Discord presence on websites.
• lanyard-graphql: A GraphQL port of the Lanyard API, catering to developers who prefer GraphQL over REST.
• lanyard.py: A modern, fully asynchronous wrapper for the Lanyard API written in Python 3.12+.

Practical Impact for Developers

The availability of Lanyard lowers the barrier to entry for creating personalized web experiences. For instance, developers can display what a user is listening to on Spotify on their personal website, or create automated bots that change behavior based on a user's Discord status. The self-hosting option, while requiring a bit of configuration, offers those who need greater control over their data the ability to deploy the service on their own infrastructure.

For teams building automation tools, the combination of a RESTful API and a real-time WebSocket provides a robust foundation. The KV store allows for the persistence of state without the need for a full-fledged database, making it ideal for lightweight applications and bots that require quick data access and updates.

What to Watch Next

As the Lanyard community continues to grow, developers should keep an eye on new integrations and potential updates to the API. The project's open-source nature means that contributions from the community are actively encouraged, with new projects being added regularly. For those looking to extend functionality, submitting a pull request to add a new project to the Lanyard ecosystem is a straightforward way to contribute.

With its focus on simplicity, real-time performance, and broad language support, Lanyard stands out as a essential tool for any developer looking to integrate Discord presence into their web applications or automation workflows.