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.
- Paso 1: Tu base de datosEl script cuenta los usuarios conectados en la base de datos del emulador.
- Paso 2: Un reporte por minutoEl cron envía el número a HabboLibre con la clave de tu hotel.
- Paso 3: HabboLibre lo validaComprueba la clave y guarda el dato durante 10 minutos.
- 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.
RequisitosKit 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 pasosTu propio código
Envía un POST desde el lenguaje que uses: el emulador, un bot de Discord, un cron en Node o Python.
Si reportas por la API, tu reporte manda: mientras esté vigente no leemos tu CMS.
Inicio rápido con el kit PHP
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.
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.phpy.env.habbolibre. Se descargan como.txtpara que tu navegador no intente abrirlos.Paso 3: Configúralo
Edita
.env.habbolibrecon 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.Paso 4: Pruébalo sin enviar nada
Terminal HL_DRY_RUN=1 php habbolibre-presence-reporter.phpDebe 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"}Paso 5: Envía el primer reporte y prográmalo
Terminal php habbolibre-presence-reporter.phpSalida 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>&1Usa rutas absolutas: el cron no carga tu
PATH.which phpte dice dónde está PHP.
Referencia del endpoint
https://api.habbolibre.org/api/v1/hotels/mi-hotel/presenceCabeceras
AuthorizationObligatorioBearerseguido de tu Pingback Secret:Bearer TU_PINGBACK_SECRET.Content-TypeObligatorioapplication/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.
statustextoOpcionalonlineuoffline. Conofflinetu hotel sale desconectado y el número se guarda como 0, envíes lo que envíes. Por defecto:online
Ejemplo
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)
{
"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_onlinebooleanofalsesi enviastestatus: 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.
Respuestas de error
Todas las respuestas son JSON. Qué significa cada código y qué hacer:
HTTP 401Invalid API key.- Falta la cabecera
Authorizationo 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, ostatusno esonlinenioffline.errorsdice 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
1cuenta 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 ystatus: offlineen 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:
# 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() - 120Qué 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:
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=401Comprobar 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 -ly que use rutas absolutas. - Activa
HL_LOG_FILEy mira el códigohttp=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.habbolibrefuera 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.
