Overview

PresenceKit Documentation

ℹ️

Before you begin

PresenceKit serves only Discord users who opted in with /confirm. Start with Getting Started if this is your first integration.

Add opt-in Discord profiles, online status, game activity, and Spotify listening information to a website with the @iconical/presence SDK. This documentation is written for developers integrating PresenceKit, from a first request to a multi-user live display.

IMPORTANT
PresenceKit only returns information for Discord users who have explicitly approved sharing with /confirm and remain eligible to share. pending means there is no fresh snapshot; it does not mean offline.

Documentation sections

Getting Started — first integration, installation and package overview.
Framework Integrations — JavaScript, React, Vue, Svelte and Angular.
API & Real-Time — REST, SSE, batches and shared subscriptions.
Features & Components — Spotify, activity artwork and React widgets.
Help & Security — consent, privacy and troubleshooting.
Development — local development and contributions.

Choose a starting point

Goal	Read
Display the first Discord status	Getting started
Install the package and select an import	Installation
Understand the SDK's features and exports	SDK overview
Look up client methods, response fields and errors	API reference

Framework integrations

Environment	Guide	Import
JavaScript, TypeScript, Node, Astro	JavaScript	`@iconical/presence`
React, Next.js	React	`@iconical/presence/react`
Vue, Nuxt	Vue	`@iconical/presence/vue`
Svelte, SvelteKit	Svelte	`@iconical/presence/svelte`
Angular	Angular	`@iconical/presence`

Work with presence data

Multi-user subscriptions — fetch or observe up to 25 users per API request/stream.
Shared connections — reuse connections across widgets and update a dynamic roster.
Spotify and activities — consume current Spotify metadata and activity helpers.
Activity artwork — safe image overrides and readable fallbacks.
React UI widgets — ready-to-use cards and theme customization.

Help and reference

Privacy and consent — what is shared, how revocation works and developer responsibilities.
Troubleshooting — fix missing data, SSE failures and package issues.
Contributing and development — run checks, build and validate the SDK.
Runnable examples — framework-specific sample applications.

System Flow

graph LR
  A[Discord user] --> B[Approve /confirm]
  B --> C[PresenceKit API]
  D[Website SDK] --> C
  C --> E[Approved snapshot]
  E --> F[Presence UI]

How PresenceKit works

1. A Discord user joins the official PresenceKit server, runs /confirm, and approves sharing.

2. An application requests that user's numeric Discord ID through the SDK.

3. The hosted API enforces consent, returns an approved snapshot, and can send live updates over Server-Sent Events (SSE).

4. The application renders the response and handles pending, errors, and revocation appropriately.

The npm SDK does not require a Discord bot token, OAuth secrets, or a configurable API base URL.

NOTE
The package may be in pre-release. Installation from npm works only after @iconical/presence is published. For unreleased versions, see the local archive workflow in Installation.

Was this page helpful?

Getting Started