Documentación para desarrolladores · Widget v1

Cómo mostrar miembros en línea de Discord en tu sitio web (Widget Discoverse)

Discoverse ofrece un Web Component / widget listo para usar que muestra estadísticas en vivo de la comunidad — miembros en línea, total de miembros, estado y enlace de invitación — en cualquier sitio de terceros. Basta con pegar dos líneas de HTML. Sin bot personalizado, sin backend que alojar; las estadísticas se actualizan a través de la API pública Cards de Discoverse.

Esta página es la referencia técnica pública para integrar el widget Discoverse y la API REST Cards.

Formas de mostrar estadísticas de Discord en un sitio web

Cuando los propietarios quieren números en vivo de su comunidad en su propio sitio, suelen elegir uno de estos tres enfoques:

Criterio	Widget oficial de Discord	Bot de Discord personalizado	Widget / Web Component Discoverse
Esfuerzo de configuración	Bajo — activar el widget del servidor Discord	Alto — código, hosting, secretos, disponibilidad	Casi nulo — pegar un fragmento HTML
Personalización visual	Chrome de Discord limitado	Control total si construyes la UI	Temas, color principal, diseños, idioma
Conteos en vivo online / miembros	Parcial / controlado por Discord	Sí, si consultas Gateway/REST tú mismo	Sí — mediante el pipeline de stats en vivo de Discoverse
Backend que hay que alojar	No	Sí	No
Coste del embed básico	Gratis	Infraestructura + mantenimiento	Gratis para comunidades listadas
Atribución	Marca Discord	A tu elección	Enlace visible a Discoverse obligatorio (integrado en el widget)

Por qué usar el widget Discoverse

Cero código de aplicación: elemento personalizado `<discoverse-card>`.
Estadísticas en vivo desde la API Discoverse (miembros online, total, invitación).
Temas compatibles con CSS (`theme`, `primary-color`, `layout`, `language`).
Funciona en sitios estáticos, bloques HTML de WordPress, embeds de Webflow y SPAs.
La misma fuente de datos en vivo que los listados de discoverse.net.

Integración rápida (copiar y pegar)

Sustituye `YOUR_SERVER_ID` por el snowflake de Discord de un servidor listado en Discoverse (bot presente), o por un vanity premium activo.

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

Carga `embed.js` una vez por página. Puedes colocar varios elementos `<discoverse-card>` con distintos valores de `server-id`. Cada tarjeta siempre muestra un enlace de atribución a Discoverse.

Dónde encontrar `server-id`

Abre la página de tu comunidad en Discoverse (`/discord/servers/...`). El ID numérico de Discord es el snowflake; las comunidades premium también pueden usar su segmento vanity. El ID debe corresponder a un gremio listado con el bot Discoverse presente.

Atribución obligatoria a Discoverse

El uso gratuito del widget Discoverse exige un enlace visible de vuelta a Discoverse. El embed oficial siempre renderiza este crédito; no lo ocultes, cubras ni elimines.

El widget siempre muestra un enlace «Powered by Discoverse» que apunta al listado de la comunidad en discoverse.net (o a la documentación si la tarjeta no pudo cargarse).
No hay atributo para desactivar la atribución. Las interfaces personalizadas basadas en la API Cards deben incluir un enlace visible equivalente al `url` devuelto por la API.
Quitar u ocultar el crédito no está permitido según los términos del widget gratuito.

Atributos de personalización

Todos los atributos son atributos HTML en `<discoverse-card>`.

Atributo	Tipo	Predeterminado	Descripción
`server-id`	string (obligatorio)	—	Snowflake del gremio de Discord o id vanity listado.
`theme`	`dark` \| `light`	`dark`	Esquema de color de la tarjeta.
`primary-color`	color CSS	`#5865F2`	Color del botón Unirse / acento.
`layout`	`card` \| `compact` \| `banner`	`card`	Densidad y disposición de icono, estadísticas y CTA.
`language`	`en` \| `fr` \| `de` \| `es` \| `it` \| `ru`	`lang` de la página o `en`	Textos de la UI (En línea, Miembros, Unirse, atribución).
`show-members`	boolean	`true`	Mostrar el total de miembros.
`show-online`	boolean	`true`	Mostrar conteo en vivo online + punto de estado.
`show-join`	boolean	`true`	Mostrar botón Unirse (URL de invitación, si no página Discoverse).
`show-sparkline`	boolean	`true`	Mostrar la curva de miembros en línea de 2 horas (oculta en layout compacto).
`show-badges`	boolean	`true`	Mostrar hasta dos insignias de actividad en directo (🔥 rush, 🎙️ voz, 📈 en crecimiento…).

Especificación técnica — API REST Cards

El embed obtiene JSON de la API pública Cards. Puedes llamar al mismo endpoint desde tu backend o edge worker. Si renderizas tu propia UI, debes seguir mostrando un enlace visible al `url` devuelto.

URLs base

Producción (mismo origen que el sitio):
`GET https://discoverse.net/api/v1/cards/{serverId}`

Host API dedicado (reescribe al mismo handler):
`GET https://api.discoverse.net/v1/cards/{serverId}`

Ejemplo de solicitud

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

Ejemplo de respuesta JSON

{
  "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"
}

Campos de respuesta

`id` (string) — snowflake de Discord.
`kind` (string) — actualmente `discord`.
`name` (string) — nombre mostrado.
`online_members` (number | null) — conteo en vivo online cuando esté disponible.
`total_members` (number | null) — total de miembros cuando esté disponible.
`icon_url` (string) — URL de icono CDN (avatar alternativo si falta).
`invite_url` (string | null) — invitación de Discord si está configurada en Discoverse.
`status` — `online` | `idle` | `offline` | `unknown` (derivado del conteo online).
`url` (string) — URL canónica del listado Discoverse (destino de atribución obligatorio para UIs personalizadas).
`updated_at` (ISO-8601) — momento de generación de la respuesta.

CORS, caché y requisitos

El endpoint Cards envía `Access-Control-Allow-Origin: *` para que los navegadores lo llamen desde sitios de terceros. Las respuestas son cacheables ~30–60 s (`Cache-Control` / `CDN-Cache-Control`). Trata la API como un feed público, de solo lectura y best-effort en vivo — no sustituto de las APIs privilegiadas de Discord.

Requisitos

El servidor de Discord debe estar listado en Discoverse con el bot Discoverse presente.
Mantén visible el enlace de atribución a Discoverse del widget (obligatorio).
Para un botón Unirse funcional, configura una URL de invitación en el panel de Discoverse cuando sea posible.
Navegadores modernos con Custom Elements + Shadow DOM (todos los navegadores evergreen actuales).

Respuestas de error

`400 invalid_server_id` — id ausente o inválido.
`404 not_found` — ningún gremio listado coincide (no listado, en lista negra o bot ausente).
El Web Component muestra el estado localizado «No disponible» en caso de fallo (el enlace de atribución sigue visible).

FAQ

¿Es el widget oficial de Discord?: No. Es el embed de Discoverse. Usa estadísticas en vivo de Discoverse y temas que tú controlas.
¿Necesito alojar un bot?: No. Discoverse ya ejecuta la infraestructura del bot para comunidades listadas.
¿Puedo ocultar el enlace de Discoverse?: No. La atribución es obligatoria y está integrada en `embed.js`. Las UIs personalizadas con la API Cards deben incluir un enlace visible equivalente a `url`.
¿Admite servidores de juego?: La API Cards v1 documenta comunidades de Discord. Las tarjetas de servidores de juego pueden reutilizar el mismo patrón de embed en una versión posterior de la API; consulta esta página de docs para actualizaciones.
¿Con qué frecuencia se actualizan los números?: El widget hace fetch al montarse. La caché HTTP es breve (decenas de segundos). Las estadísticas en vivo subyacentes se actualizan con el pipeline de actividad de la plataforma.