Api Reference

Multi User

Multi-user Presence

⚠️

Consent is per user

A batch response contains only approved members. An absent ID should never be displayed as offline or used to infer consent.

Build a team roster or contributor wall without opening a separate API request for every Discord ID. PresenceKit can fetch or subscribe to 1–25 explicitly named users per request/stream.

Requirements

Each person must independently join the official PresenceKit Discord server, run /confirm, and keep sharing enabled. There is no “all users” endpoint, and the API intentionally omits accounts that are unapproved or no longer eligible.

Step 1 — Fetch a batch

example.tstypescript

import { createPresenceClient } from "@iconical/presence";

const client = createPresenceClient();
const ids = ["123456789012345678", "222222222222222222"];

try {
  const batch = await client.getPresences(ids);

  for (const [id, member] of Object.entries(batch.presences)) {
    console.log(id, member.profile.displayName);
    console.log(member.presence?.status ?? "Waiting for update");
  }
} catch (error) {
  console.error("Team presence unavailable", error);
}

A PresenceBatchResult has the shape { ok: true, presences: Record }. Do not assume every requested ID is present. Absent entries are not evidence of an account's online state.

One batch subscription

graph TD
  A[Website roster] --> B[subscribePresences]
  B --> C[One batch stream]
  C --> D[Approved members only]
  D --> E[UI updates]
  C --> F[Revocation event]
  F --> G[Remove member]

Step 2 — Observe updates

example.tstypescript

const stop = client.subscribePresences(
  ids,
  {
    onUpdate(batch) {
      console.log("Visible team members:", Object.keys(batch.presences));
    },
    onError(error) {
      console.error("Team stream error:", error.message);
    },
  },
  { transport: "auto" },
);

// Disconnect when the roster is removed.
stop();

A batch SSE stream begins with a snapshot, sends presence updates for individual members, and sends revoked when a member's sharing ends. The SDK removes revoked entries from the roster. If SSE fails under auto, it uses one batch REST poll and later retries streaming.

Step 3 — React example

example.tsxtsx

"use client";
import { usePresences } from "@iconical/presence/react";

export function Team() {
  const { data, loading, error } = usePresences({
    userIds: ["123456789012345678", "222222222222222222"],
  });

  if (loading) return <p>Loading team…</p>;
  if (error) return <p>Team presence unavailable</p>;

  return (
    <ul>
      {Object.entries(data?.presences ?? {}).map(([id, user]) => (
        <li key={id}>
          {user.profile.displayName}: {user.presence?.status ?? "Pending"}
        </li>
      ))}
    </ul>
  );
}

Vue has usePresences({ userIds }); Svelte has createPresencesStore({ userIds }).

Limits and privacy

Low-level batch endpoints require 1–25 valid numeric Discord user IDs.
Batch results omit revoked, unconfirmed and unverified accounts.
A 404 can mean the batch contains no eligible members; 503 is a temporary service interruption.
Application UI must remove data after revoked instead of retaining a stale profile.
The API does not support discovery, wildcards, username search, or bulk monitoring.

If different components show overlapping members, use Shared connections to reduce duplicate streams.

Was this page helpful?

Api Reference Shared Connections