Saltar al contenido principal
Documentación para hoteles

API de usuarios online

Publica cuántos jugadores hay conectados en tu hotel. HabboLibre muestra el número en el ranking y en la ficha de tu hotel mientras tenga menos de 10 minutos.

  1. Paso 1: Tu base de datosEl script cuenta los usuarios conectados en la base de datos del emulador.
  2. Paso 2: Un reporte por minutoEl cron envía el número a HabboLibre con la clave de tu hotel.
  3. Paso 3: HabboLibre lo validaComprueba la clave y guarda el dato durante 10 minutos.
  4. Paso 4: Se ve en tu fichaEl ranking y la ficha muestran tus usuarios online junto al estado del servidor.

Lo hace tu servidorLo hace HabboLibre

El final de la dirección de tu hotel: habbolibre.org/hotels/tu-slug. Los ejemplos de la página lo usan; tu clave nunca se escribe aquí.

Elige cómo publicarlos

Detección automática

No instalas nada si tu CMS ofrece una fuente compatible. Detectamos las API de Atom actuales, Cosmic (/api/online o /api/player/count), Brain (/onlinecount) y páginas que muestran un contador público compatible, como «personas dentro ahora». No requiere kit PHP cuando encontramos una fuente.

Al detectar una fuente, consultamos el conteo cada 5 minutos y lo mostramos como «según la web del hotel». Si aún no encontramos una, volvemos a comprobar cada 15 minutos. Un reporte reciente de tu propia API siempre tiene prioridad.

Requisitos

Kit PHP Recomendado

Un script listo que cuenta los usuarios en la base de datos de tu emulador y los envía cada minuto. Funciona con cualquier emulador con MySQL o MariaDB.

Instalarlo en 5 pasos

Tu propio código

Envía un POST desde el lenguaje que uses: el emulador, un bot de Discord, un cron en Node o Python.

Ver el endpoint

Si reportas por la API, tu reporte manda: mientras esté vigente no leemos tu CMS.

Inicio rápido con el kit PHP

  1. Paso 1: Copia tu clave

    En Mis hoteles → Editar → Votaciones e integraciones está tu Pingback Secret. Es la clave de tu hotel para esta API y para la de votos. Trátala como una contraseña.

  2. Paso 2: Descarga el kit

    Súbelos a la misma carpeta de tu servidor, fuera de la carpeta pública de la web, y renómbralos a habbolibre-presence-reporter.php y .env.habbolibre. Se descargan como .txt para que tu navegador no intente abrirlos.

  3. Paso 3: Configúralo

    Edita .env.habbolibre con tu clave y los datos de la base de datos del emulador:

    .env.habbolibre
    HL_HOTEL_SLUG="mi-hotel"
    HL_API_KEY="TU_PINGBACK_SECRET"
    HL_DB_DSN="mysql:host=127.0.0.1;dbname=hotel;charset=utf8mb4"
    HL_DB_USER="usuario"
    HL_DB_PASS="contraseña"
    HL_ONLINE_COUNT_SQL="SELECT COUNT(*) FROM users WHERE online = 1"

    Si tu emulador no usa users.online, cambia la consulta: tienes ejemplos en Configuración del kit.

  4. Paso 4: Pruébalo sin enviar nada

    Terminal
    HL_DRY_RUN=1 php habbolibre-presence-reporter.php

    Debe mostrar el número de usuarios que encontró y la petición que enviaría:

    Salida esperada
    Dry run: would POST to https://api.habbolibre.org/api/v1/hotels/mi-hotel/presence
    {"users_online":42,"status":"online"}
  5. Paso 5: Envía el primer reporte y prográmalo

    Terminal
    php habbolibre-presence-reporter.php
    Salida esperada
    Reported 42 users online to HabboLibre at 2026-11-07T19:00:03+00:00 (fresh for 600s)

    Si ves esa línea, añade el script al cron para que reporte cada minuto (crontab -e):

    crontab
    * * * * * /usr/bin/php /home/hotel/habbolibre/habbolibre-presence-reporter.php >/dev/null 2>&1

    Usa rutas absolutas: el cron no carga tu PATH. which php te dice dónde está PHP.

Referencia del endpoint

POSThttps://api.habbolibre.org/api/v1/hotels/mi-hotel/presence

Cabeceras

AuthorizationObligatorio
Bearer seguido de tu Pingback Secret: Bearer TU_PINGBACK_SECRET.
Content-TypeObligatorio
application/json.
User-AgentOpcional
Recomendado: un nombre propio, como MiHotel-Presence/1.0. Algunos clientes con el User-Agent por defecto reciben un 403 de Cloudflare.

Cuerpo (JSON)

users_onlineenteroObligatorio
Usuarios conectados ahora mismo, de 0 a 65535.
statustextoOpcional
online u offline. Con offline tu hotel sale desconectado y el número se guarda como 0, envíes lo que envíes. Por defecto: online

Ejemplo

Terminal
curl -X POST "https://api.habbolibre.org/api/v1/hotels/mi-hotel/presence" \
  -H "Authorization: Bearer TU_PINGBACK_SECRET" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MiHotel-Presence/1.0" \
  -d '{"users_online":42,"status":"online"}'

Respuesta correcta (HTTP 200)

Respuesta 200
{
  "success": true,
  "message": "Presencia actualizada.",
  "hotel_slug": "mi-hotel",
  "is_online": true,
  "users_online": 42,
  "reported_at": "2026-11-07T19:00:03+00:00",
  "fresh_for_seconds": 600
}
is_onlinebooleano
false si enviaste status: offline.
users_onlineentero
El número que quedó guardado (0 con offline).
reported_atfecha ISO 8601
Cuándo lo recibimos, en UTC.
fresh_for_secondsentero
Segundos que el dato seguirá visible si no envías otro: 600.
Envía un reporte cada minuto. Un dato con más de 10 minutos deja de mostrarse en HabboLibre y tu panel lo marca como vencido. El límite es de 60 peticiones por minuto por IP.

Respuestas de error

Todas las respuestas son JSON. Qué significa cada código y qué hacer:

HTTP 401Invalid API key.
Falta la cabecera Authorization o la clave no es la actual. Si regeneraste la clave, la anterior dejó de funcionar en ese momento.
HTTP 403Hotel has no API key configured.
Tu hotel no tiene clave. Pídela al equipo de HabboLibre.
HTTP 403error code: 1010 (texto)
Cloudflare rechazó tu User-Agent. Envía uno propio, como MiHotel-Presence/1.0.
HTTP 404Hotel not found.
El slug de la dirección no existe. Cópialo de la dirección de tu ficha en HabboLibre.
HTTP 422{"message", "errors"}
El cuerpo no es válido: falta users_online, no es un entero entre 0 y 65535, o status no es online ni offline. errors dice qué campo falló.
HTTP 429{"message", "retry_after_seconds"}
Más de 60 peticiones por minuto desde tu IP. Espera los segundos de retry_after_seconds. Con un reporte por minuto nunca llegarás.

Configuración del kit

El script lee .env.habbolibre de su misma carpeta. Las variables que ya existan en el entorno tienen prioridad, así que también puedes pasarlas desde el cron o desde tu panel de hosting.

HL_HOTEL_SLUGObligatorio
El slug de tu hotel en HabboLibre.
HL_API_KEYObligatorio
Tu Pingback Secret.
HL_DB_DSNObligatorio
Conexión PDO a la base de datos del emulador, por ejemplo mysql:host=127.0.0.1;dbname=hotel;charset=utf8mb4.
HL_DB_USEROpcional
Usuario de la base de datos. Basta con permiso de lectura.
HL_DB_PASSOpcional
Contraseña de ese usuario.
HL_ONLINE_COUNT_SQLOpcional
Consulta que devuelve el número de usuarios conectados. Por defecto: SELECT COUNT(*) FROM users WHERE online = 1
HL_DRY_RUNOpcional
Con 1 cuenta e imprime lo que enviaría, sin enviar nada. Por defecto: 0
HL_REPORT_OFFLINE_ON_DB_ERROROpcional
Con 1, si la base de datos falla reporta 0 usuarios y status: offline en vez de abortar. Por defecto: 0
HL_LOG_FILEOpcional
Archivo donde anotar cada ejecución, por ejemplo /var/log/hl-presence.log. Vacío, no anota nada.
HL_TIMEOUT_SECONDSOpcional
Tiempo máximo de la petición a HabboLibre, de 1 a 60 segundos. Por defecto: 8
HL_CONNECT_TIMEOUT_SECONDSOpcional
Tiempo máximo para conectar. Por defecto: 4
HL_LOCK_PATHOpcional
Archivo de bloqueo que impide dos ejecuciones a la vez. Por defecto: habbolibre-presence-<slug>.lock en la carpeta temporal del sistema
HL_API_BASEOpcional
Dirección de la API. No la cambies salvo que te lo pidamos. Por defecto: https://api.habbolibre.org/api/v1

Consultas para contar usuarios

HL_ONLINE_COUNT_SQL debe devolver una sola fila con un número. Usa la que encaje con tu emulador:

Consultas
# Columna online numérica (0 / 1)
SELECT COUNT(*) FROM users WHERE online = 1

# Columna online como texto o ENUM ('0' / '1')
SELECT COUNT(*) FROM users WHERE online = '1'

# Sin columna online: actividad de los últimos 2 minutos
SELECT COUNT(*) FROM user_sessions WHERE last_activity >= UNIX_TIMESTAMP() - 120

Qué imprime y cómo termina

Con éxito imprime Reported N users online… y sale con código 0, igual que en modo prueba o si otra ejecución sigue activa. Ante un error lo escribe en la salida de errores y sale con código 1. Con HL_LOG_FILE añade una línea por ejecución:

Registro
2026-11-07T19:00:03+00:00 | online | users_online=42 | http=200
2026-11-07T19:01:02+00:00 | online | users_online=40 | http=401

Comprobar que funciona

En Mis hoteles → Editar → Conexión tienes dos indicadores. Probar API comprueba tu configuración sin cambiar el número publicado, y Copiar cURL te da el comando listo con tu clave.

Usuarios online

Activo
Hay un reporte de menos de 10 minutos: el número se ve en HabboLibre.
Vencido
Hubo reportes, pero el último tiene más de 10 minutos.
Pendiente
Todavía no llega ningún reporte.
Sin secreto
Tu hotel no tiene clave: pídela al equipo de HabboLibre.

Salud del reporter

OK
El último reporte tiene 3 minutos o menos.
Lento
El último tiene entre 3 y 10 minutos: los reportes llegan con retraso.
Sin reportes
Más de 10 minutos sin reportar.
Sin configurar
Nunca llegó un reporte.

Después abre la ficha de tu hotel: el número aparece junto al estado del servidor.

Problemas frecuentes

El número aparece y a los minutos desaparece

El último reporte tiene más de 10 minutos: el cron dejó de ejecutar el script o el script falla.

  • Revisa que la línea siga en crontab -l y que use rutas absolutas.
  • Activa HL_LOG_FILE y mira el código http= de cada ejecución.
  • Si regeneraste la clave, la anterior dejó de funcionar: actualiza HL_API_KEY.
El script dice Missing HL_HOTEL_SLUG, HL_API_KEY or HL_DB_DSN

No encuentra la configuración. El archivo debe llamarse exactamente .env.habbolibre y estar en la misma carpeta que el script.

El script dice Database error

No pudo conectar o la consulta falló. Revisa HL_DB_DSN, usuario y contraseña, y prueba la consulta en tu cliente MySQL. Si prefieres que tu hotel salga desconectado cuando la base de datos cae, activa HL_REPORT_OFFLINE_ON_DB_ERROR=1.

El script dice PHP cURL extension is not enabled.

Instala o activa la extensión cURL de PHP (en Debian o Ubuntu, el paquete php-curl) y vuelve a probar.

Recibo HTTP 403 con el cuerpo error code: 1010

Cloudflare rechazó el User-Agent de tu cliente. Envía uno propio, por ejemplo User-Agent: MiHotel-Presence/1.0. El kit ya envía el suyo.

Recibo HTTP 403 con una página HTML

Si la respuesta trae la cabecera cf-mitigated: challenge, Cloudflare desafió la IP de tu servidor. Escríbenos con el valor de la cabecera cf-ray para revisarlo.

La detección automática no encuentra el número

La detección automática solo publica un conteo cuando encuentra una fuente compatible:

  • Un hotel aprobado, sin un cambio de dominio pendiente de revisión.
  • Una API compatible de Atom, Cosmic o Brain, o un contador público reconocible en la página principal del hotel.
  • Que tu firewall o tu Cloudflare dejen pasar a nuestro bot: HabboLibreBot/1.0.

Si la página requiere iniciar sesión, Cloudflare bloquea la lectura o no encontramos un formato compatible, mostramos el dato como no disponible; no suponemos que sea 0. Puedes dejar que la comprobación automática vuelva a intentarlo o usar el kit PHP/API para reportar directamente.

El número no coincide con el que veo dentro del hotel

Publicamos lo que cuenta tu consulta en ese momento y lo refrescamos con cada reporte. Si incluye bots o cuentas de staff ocultas, ajusta HL_ONLINE_COUNT_SQL para excluirlas.

Seguridad

  • Tu Pingback Secret solo va en tu servidor: nunca en JavaScript del navegador, en un repositorio público ni en capturas.
  • Deja el script y .env.habbolibre fuera de la carpeta pública de tu web, para que nadie pueda descargarlos.
  • Para leer la base de datos basta un usuario de solo lectura.
  • Si crees que tu clave se filtró, pulsa Regenerar clave en Mis hoteles → Editar. La anterior deja de funcionar en ese momento, así que actualiza tus scripts.
  • HabboLibre nunca publica la IP ni el puerto de tu servidor: solo el estado y el número de usuarios.