Lanyard Documentation

Lanyard KV is a dynamic, real-time key-value store integrated into the user API response. When a KV pair is updated, a PRESENCE_UPDATE event is emitted through the Lanyard WebSocket.

Constraints:

• Keys and values must be strings.
• Maximum value length: 30,000 characters.
• Key format: Letters, numbers, and underscores (a-zA-Z0-9_) only. Max 255 characters.
• Maximum pairs per user: 512.

The Lanyard WebSocket is available at wss://api.lanyard.rest/socket. You can request compression by appending ?compression=zlib_json to the URL.

Connection Lifecycle:

1. Connect: Upon connection, you will receive Opcode 1: Hello. This message contains a heartbeat_interval in the d field.
2. Heartbeat: You must send Opcode 3: Heartbeat repeatedly at the interval specified by the heartbeat_interval received in the Hello message.
3. Initialize: Immediately after receiving Opcode 1: Hello, you must send Opcode 2: Initialize to subscribe to presences.

The recommended way to use Lanyard in React is via the use-lanyard library. It uses a WebSocket connection to provide live updates, and multiple hooks can share a single connection.

Note: The hook returns undefined until the first presence data arrives. You can pass a single Discord ID or an array of IDs to subscribe to multiple users.

import { useLanyard } from 'use-lanyard';

export function App() {
	const presence = useLanyard(YOUR_DISCORD_ID);
	return <p>Hi, I'm {presence?.discord_user.username}!</p>;
}

Lanyard allows you to export your live Discord presence to a RESTful API and WebSocket. To start using it immediately without any deployment or configuration:

1. Join the Lanyard Discord server.
2. Your presence will automatically become available via GET api.lanyard.rest/v1/users/:your_id.

The Lanyard.KV.Interface module provides a Key-Value (KV) store for associating data with a specific Discord user ID. This allows you to persist small amounts of custom data that is synchronized with the user's presence.

Constraints:

• Key Count Limit: A single user can have a maximum of 512 keys.
• Key Length Limit: Keys must be 255 characters or less.
• Key Format: Keys must be alphanumeric (including underscores: a-zA-Z0-9_).
• Value Length Limit: Values must be 30000 characters or less.

The Lanyard Discord bot allows you to store and manage custom data on your Lanyard profile via Discord commands. Commands are prefixed by the configured command prefix (defaulting to whatever is set in the :lanyard, :command_prefix application environment variable).

Available commands:

• `prefixget <key>`: Get the value of a specific key.
• `prefixset <key> <value>`: Set a key to a specific value.
• `prefixdel <key>`: Delete a specific key.
• `prefixkv`: List all of your current keys.
• `prefixapikey`: Get (or regenerate) your Lanyard API key. This key will be sent to you via Direct Message (DM).

You can generate a unique API key for managing your Lanyard Key/Value (K/V) store by interacting with the Lanyard Discord bot.

Important Security Notes:

• Do not share or post this key anywhere. It is a secret key that allows anyone to manage your Lanyard K/V.
• Do not use this key in a front-end application or website.
• To access your public data, use your Discord user ID with the public endpoint: #{Application.get_env(:lanyard, :external_url)}/v1/users/{your_discord_user_id}.

Usage:

1. Open a Direct Message (DM) with the Lanyard bot.
2. Run the .apikey command.
3. The bot will send you an embed containing your new key. You must click the key to reveal it.

If you accidentally post your API key in a public channel or believe it has been compromised, you must regenerate it immediately.

Automatic Regeneration: If you use your API key within a K/V command in a public channel, the bot will detect it, warn you, and automatically regenerate a new key, sending the new one to your DMs.

Manual Regeneration: To manually trigger a regeneration, send the .apikey command within your Direct Messages with the Lanyard bot.

To stop receiving PRESENCE_UPDATE events for specific users, send Opcode 4: Unsubscribe. You can unsubscribe in three ways:

• Specific Users: Use unsubscribe_from_id (string) for one user, or unsubscribe_from_ids (string[]) for multiple users.
• All Users: Use unsubscribe_from_all: true to stop receiving updates for all currently subscribed users and remove yourself from the global subscriber list.

{
  op: 4,
  d: {
    // unsubscribe_from_id should be a single user ID (string) you no longer want to receive updates for
    unsubscribe_from_id: "94490510688792576"
  }
}

{
  op: 4,
  d: {
    unsubscribe_from_ids: ["94490510688792576", "156114103033790464"]
  }
}

{
  op: 4,
  d: {
    unsubscribe_from_all: true
  }
}