How to display Discord online members on your website (Discoverse Widget)

Comparing ways to show Discord stats on a website

When owners want live community numbers on their own site, they usually choose one of three approaches:

Why use the Discoverse widget

• Zero application code: drop-in custom element `<discoverse-card>`.
• Live stats from the Discoverse API (online members, total members, invite).
• CSS-friendly theming (`theme`, `primary-color`, `layout`, `language`).
• Works on static sites, WordPress HTML blocks, Webflow embeds, and SPAs.
• Same live data source as discoverse.net listings.

Quick integration (copy-paste)

Replace `YOUR_SERVER_ID` with the Discord snowflake of a server listed on Discoverse (bot present), or with an active premium vanity slug.

<discoverse-card
  server-id="YOUR_SERVER_ID"
  theme="dark"
  show-members="true"
  show-online="true"
  show-join="true"
  layout="card"
  language="en"
  primary-color="#5865F2"
></discoverse-card>
<script src="https://discoverse.net/widget/v1/embed.js" async></script>

Load `embed.js` once per page. You may place multiple `<discoverse-card>` elements with different `server-id` values. Each card always shows a Discoverse attribution link.

Where to find `server-id`

Open your community page on Discoverse (`/discord/servers/...`). The numeric Discord ID is the snowflake; premium communities may also use their vanity segment. The ID must resolve to a listed guild with the Discoverse bot present.

Required Discoverse attribution

Using the free Discoverse widget requires a visible link back to Discoverse. The official embed always renders this credit; do not hide, cover, or remove it.

• The widget always displays a “Powered by Discoverse” link pointing to the community listing on discoverse.net (or the docs if the card failed to load).
• There is no attribute to disable attribution. Custom UIs built on the Cards API must include an equivalent visible link to the listing `url` returned by the API.
• Removing or obscuring the credit is not allowed under the free widget terms.

Customization attributes

All attributes are HTML attributes on `<discoverse-card>`.

Technical specification — Cards REST API

The embed fetches JSON from the public Cards API. You can call the same endpoint from your own backend or edge worker. If you render your own UI, you must still show a visible link to the returned `url`.

Base URLs

Production (same origin as the site):
`GET https://discoverse.net/api/v1/cards/{serverId}`

Dedicated API host (rewrites to the same handler):
`GET https://api.discoverse.net/v1/cards/{serverId}`

Example request

GET /api/v1/cards/123456789012345678 HTTP/1.1
Host: discoverse.net
Accept: application/json

Example JSON response

{
  "id": "123456789012345678",
  "kind": "discord",
  "name": "Example Community",
  "online_members": 142,
  "total_members": 8120,
  "icon_url": "https://cdn.discordapp.com/icons/.../icon.png?size=128",
  "invite_url": "https://discord.gg/xxxxxx",
  "status": "online",
  "url": "https://discoverse.net/discord/servers/123456789012345678",
  "updated_at": "2026-09-18T18:00:00.000Z"
}

Response fields

• `id` (string) — Discord snowflake.
• `kind` (string) — currently `discord`.
• `name` (string) — display name.
• `online_members` (number | null) — live online count when available.
• `total_members` (number | null) — total members when available.
• `icon_url` (string) — CDN icon URL (fallback avatar if missing).
• `invite_url` (string | null) — Discord invite when configured on Discoverse.
• `status` — `online` | `idle` | `offline` | `unknown` (derived from online count).
• `url` (string) — canonical Discoverse listing URL (required attribution target for custom UIs).
• `updated_at` (ISO-8601) — response generation time.

CORS, caching, and requirements

The Cards endpoint sends `Access-Control-Allow-Origin: *` so browsers can call it from third-party sites. Responses are cacheable for ~30–60 seconds (`Cache-Control` / `CDN-Cache-Control`). Treat the API as a public, read-only, best-effort live feed — not a substitute for Discord’s privileged APIs.

Requirements

• The Discord server must be listed on Discoverse with the Discoverse bot present.
• Keep the widget’s Discoverse attribution link visible (mandatory).
• For a working Join button, configure an invite URL in the Discoverse dashboard when possible.
• Modern browsers with Custom Elements + Shadow DOM (all current evergreen browsers).

Error responses

`400 invalid_server_id` — missing/invalid id.
`404 not_found` — no listed guild matches (not listed, blacklisted, or bot absent).
The Web Component shows a localized “Unavailable” state on failure (attribution link still shown).

FAQ

Is this the official Discord widget?

No. It is the Discoverse embed. It uses Discoverse live stats and branding themes you control.

Do I need to host a bot?

No. Discoverse already runs the bot infrastructure for listed communities.

Can I hide the Discoverse link?

No. Attribution is required and built into `embed.js`. Custom Cards API UIs must include an equivalent visible link to `url`.

Does it support game servers?

v1 Cards API documents Discord communities. Game-server cards can reuse the same embed pattern in a later API version; watch this docs page for updates.

How often do numbers update?

The widget fetches on mount. HTTP caching is short (tens of seconds). Underlying Discoverse live stats refresh on the platform’s activity pipeline.