/lantern

Lantern makes it incredibly easy to reveal your live Discord status through a RESTful API and WebSocket connection in under 10 seconds.

Primary LanguageJavaScriptISC LicenseISC

🔦 Lantern: Illuminate Your Discord Presence with Real-Time API and WebSocket

Lantern is a powerful service designed to effortlessly broadcast your active Discord status to both a RESTful API endpoint (lantern.rest/api/v1/users/:your_id) and a WebSocket connection. Want to showcase your current Spotify tracks on your personal site? Lantern has you covered.

While Lantern is ready to use out-of-the-box without the need for any deployment, it also offers the flexibility for self-hosting with minimal setup. Enjoy seamless integration and real-time updates with Lantern.

API Docs

GET /api/v1/users/:id

Retrieve the data of a user with the specified ID.

Parameters
Name Type Description
id string The ID of the user to retrieve.
svg boolean Whether to return the user's avatar as an SVG image. Defaults to false.
theme string The theme to use for the user's card. Must be either light or dark.
borderRadius number The border radius to use for the user's card.
hideGlobalName number Whether to hide the user's global name. Must be either 0 or 1.
hideStatus number Whether to hide the user's status. Must be either 0 or 1.
hideBadges number Whether to hide the user's badges. Must be either 0 or 1.
hideActivity number Whether to hide the user's activity. Must be either 0 or 1.
Response
Example Response 
{
  // User metadata object
  "metadata": {
    "id": "123456789012345678",
    "username": "example",
    "discriminator": "0",
    "global_name": "example",
    "avatar": "abcdef1234567890",
    "avatar_url": "https://cdn.discordapp.com/avatars/123456789012345678/123456789012345678.png",
    "display_avatar_url": "https://cdn.discordapp.com/avatars/123456789012345678/123456789012345678.png",
    "bot": false,
    "flags": {
      "human_readable": ["DISCORD_EMPLOYEE"],
      "bitfield": 1
    },
    "monitoring_since": {
      "unix": 1620000000,
      "raw": "2021-05-03T00:00:00.000Z"
    }
  },
  "status": "online",
  // Active platforms object with current Spotify track
  "active_platforms": {
    "desktop": "online",
    "mobile": "offline",
    "web": "offline",
    "spotify": {
      "track_id": "abcdef1234567890",
      "song": "example",
      "artist": "example",
      "album": "example",
      "album_cover": "https://i.scdn.co/image/abcdef1234567890",
      "start_time": {
        "unix": 1620000000,
        "raw": "2021-05-03T00:00:00.000Z"
      },
      "end_time": {
        "unix": 1620000000,
        "raw": "2021-05-03T00:00:00.000Z"
      },
      "time": {
        "start_human_readable": "00:00",
        "end_human_readable": "00:00"
      }
    }
  },
  // Array of user activities
  "activities": [
    {
      "id": "abcdef1234567890",
      "name": "example",
      "type": "PLAYING",
      "state": "example",
      "details": "example",
      "application_id": "123456789012345678",
      "created_at": 1620000000,
      "assets": {
        "large_image": {
          "hash": "abcdef1234567890",
          "image_url": "https://cdn.discordapp.com/app-assets/123456789012345678/abcdef1234567890.png",
          "text": "example"
        },
        "small_image": {
          "hash": "abcdef1234567890",
          "image_url": "https://cdn.discordapp.com/app-assets/123456789012345678/abcdef1234567890.png",
          "text": "example"
        }
      },
      "start_time": {
        "unix": 1620000000,
        "raw": "2021-05-03T00:00:00.000Z"
      }
    }
  ]
}

WebSocket

The WebSocket connection is available at wss://lantern.rest/socket.

Once connected, you will receive Opcode 1: Hello which will contain heartbeat_interval in the data field.

You should set a repeating interval for the time specified in heartbeat_interval which should send Opcode 4: Heartbeat on the interval.

You should send Opcode 2: Initialize immediately after receiving Opcode 1: Hello with the following payload:

Subscribe to User 
{
  "op": 2,
  "d": {
    "user_id": "123456789012345678"
  }
}
Subscribe to Multiple Users 
{
  "op": 2,
  "d": {
    "user_ids": ["123456789012345678", "234567890123456789"]
  }
}
Subscribe to All Users 
{
  "op": 2,
  "d": {
    "user_id": "All"
  }
}

You will receive Opcode 3: Initialize Acknowledgement once the server has acknowledged your subscription and this will contain the all data for the user(s) you have subscribed to in the d field.

If any user you have subscribed to updates their presence, you will receive Opcode 6: Presence Update with the updated data in the d field.

If any user you have subscribed leaves the Lantern server, you will receive Opcode 7: User Left with the user ID in the d field. (when subscribing to multiple users, you will receive this for each user that leaves, if no users are left, you will receive Opcode 9: Disconnect)

List of Opcodes
Opcode Description Type
1 HELLO Server -> Client
2 INIT Client -> Server
3 INIT_ACK Server -> Client
4 HEARTBEAT Client -> Server
5 HEARTBEAT_ACK Server -> Client
6 PRESENCE_UPDATE Server -> Client
7 USER_LEFT Server -> Client
8 USER_JOINED Server -> Client
9 DISCONNECT Server -> Client
Example Payloads
Opcode 1: Hello 
{
  "t": "HELLO",
  "op": 1,
  "d": {
    "heartbeat_interval": 10000
  }
}
Opcode 2: Initialize 
{
  "t": "INIT",
  "op": 2,
  "d": {
    "user_id": "123456789012345678"
  }
}
Opcode 3: Initialize Acknowledgement 
{
  "t": "INIT_ACK",
  "op": 3
}
Opcode 4: Heartbeat 
{
  "t": "HEARTBEAT",
  "op": 4
}
Opcode 5: Heartbeat Acknowledgement 
{
  "t": "HEARTBEAT_ACK",
  "op": 5
}
Opcode 6: Presence Update 
{
  "t": "PRESENCE_UPDATE",
  "op": 6,
  "d": {
    // Updated user data
    // Can be array if multiple users are subscribed
  }
}
Opcode 7: User Left 
{
  "t": "USER_LEFT",
  "op": 7,
  "d": {
    "user_id": "123456789012345678"
  }
}
Opcode 8: User Joined 
{
  "t": "USER_JOINED",
  "op": 8,
  "d": {
    // User data
  }
}
Opcode 9: Disconnect 
{
  "t": "DISCONNECT",
  "op": 9,
  "d": {
    "reason": "Connection timed out."
  }
}

Self-Hosting

To self-host Lantern, you will need to have the following prerequisites installed on your system:

Once you have the prerequisites installed, follow these steps to self-host Lantern:

  1. Clone the repository to your local machine:
git clone
  1. Navigate to the cloned repository:
cd lantern/server
  1. Install the required dependencies:
npm install
  1. Create a .env file in the server directory with the following environment variables:
DISCORD_BOT_TOKEN=your_discord_bot_token
MONGODB_URI=your_mongodb_uri

# For GitHub Auto Deploy (not needed for local development)
GITHUB_WEBHOOK_SECRET=your_github_webhook_secret

# Logtail Source Token (for logging, not needed for local development)
LOGTAIL_SOURCE_TOKEN=your_logtail_source_token
  1. Fill these configuration values in the config.toml file with your own values:
base_guild_id = 'your_base_guild_id'

[server]
port = 8000
  1. Start the server:
npm start
  1. The server should now be running on http://localhost:8000. You can access the API and WebSocket connection from this URL.

Note

Make sure you enable these settings in your bot's application settings:

  • PRESENCE INTENT
  • GUILD MEMBERS INTENT

Contributing

We welcome contributions from the community! If you'd like to contribute to the project, please follow these guidelines:

  1. Fork the repository and clone it locally.
  2. Create a new branch for your feature or bug fix.
  3. Make your changes and ensure the code passes any existing tests.
  4. Commit your changes with descriptive commit messages.
  5. Push your changes to your fork and submit a pull request to the main branch of the original repository.

Please make sure to follow the Code of Conduct and Contributing Guidelines when contributing to this project.

Help

If you encounter any issues with the Lantern or have any questions, feel free to open an issue on this repository. We'll do our best to assist you!

License

This project is licensed under the ISC License.