Getting Started
Getting Started
Getting Started
[Overview](./)
Consent comes first
A Discord user must approve sharing with /confirm before their presence can be displayed. Never interpret pending or a 404 as an offline status.
In this tutorial, you will install PresenceKit, fetch one consent-approved Discord presence snapshot, and subscribe to live updates.
Before you begin: consent
The person whose presence you want to display must:
1. Join the Discord server where the official PresenceKit bot is available.
2. Run /confirm and approve the sharing notice.
3. Optionally run /status to verify their sharing status.
4. Provide their numeric Discord user ID for the integration.
A user can later run /disconnect or leave the server to revoke access. Merely joining the server does not make their presence public.
WARNING
Only use IDs of users who have agreed to share. Do not display an unapproved user's identity or infer their status from errors.
Install the SDK
bun add @iconical/presenceFetch the first snapshot
Create a client and request an opted-in user's Discord ID.Subscribe and clean up
Use `subscribePresence()` and call its returned function when no longer needed.Step 1 — Install the SDK
bun add @iconical/presenceYou can also use pnpm add, npm install, or yarn add. If npm installation is not available yet, follow the pre-release instructions.
Step 2 — Request a snapshot
import { createPresenceClient, getPlayingActivities } from "@iconical/presence";
const DISCORD_USER_ID = "123456789012345678"; // Replace with an opted-in ID.
const client = createPresenceClient();
try {
const result = await client.getPresence(DISCORD_USER_ID);
console.log("Profile:", result.profile.displayName);
if (result.availability === "pending") {
console.log("Approved, but waiting for a fresh Discord update.");
} else {
console.log("Status:", result.presence?.status);
console.log("Games:", getPlayingActivities(result.presence));
console.log("Spotify:", result.spotify?.song ?? "Nothing reported");
}
} catch (error) {
console.error("Unable to load presence:", error);
}The SDK sends requests to its fixed official API endpoint. Your application does not need a Discord login, bot token, or a custom baseUrl setting.
Step 3 — Listen for live changes
const stop = client.subscribePresence(
DISCORD_USER_ID,
{
onUpdate(result) {
if (result.availability === "pending") {
console.log("Waiting for a fresh snapshot");
return;
}
console.log("New status:", result.presence?.status);
},
onError(error) {
console.error("Presence unavailable:", error.message);
},
},
{ transport: "auto" },
);
// Call this when the component or page no longer needs updates.
stop();The returned function must be called on cleanup. auto uses SSE where available, then falls back to REST polling if streaming fails; environments without EventSource use polling. In a framework component, place the subscription inside the appropriate mount/unmount lifecycle.
Step 4 — Display the right state
| Situation | What to show |
|---|---|
availability: "live" | presence.status, current activities and optional Spotify data |
availability: "pending" | “Waiting for a Discord update” — not “Offline” |
presence.status: "offline" | “Offline” (when a live snapshot explicitly reports it) |
| HTTP 404 | “Presence unavailable” — approval or eligibility cannot be confirmed |
| HTTP 429 | “Temporarily rate limited” — retry conservatively |
| HTTP 503 | “Service temporarily unavailable” |
A successful PresenceResult has a profile, availability, nullable presence and nullable spotify. Never assume those latter two fields are populated.
Next steps
- Build a UI using React, Vue, Svelte, or vanilla JavaScript.
- Render ready-made React widgets.
- Follow multiple consenting accounts with multi-user subscriptions.
- Inspect methods and types in the API reference.
In this section
Was this page helpful?