Documentación

API de usuarios online

Permite que tu hotel reporte cuántos usuarios están conectados para mostrarlo en HabboLibre junto al estado del servidor.

Script PHP Ejemplo .env

Cómo funciona

1Tu servidor cuenta los usuarios conectados en su propia base de datos.
2Envía ese número a HabboLibre usando tu Pingback Secret como API key.
3HabboLibre muestra el conteo solo si fue reportado recientemente. Los datos vencen después de 10 minutos.

Antes de empezar

Slug del hotel

Es el texto final de la URL pública, por ejemplo mi-hotel en /hotels/mi-hotel.

Pingback Secret

Lo encuentras en Mis hoteles -> Editar -> Votaciones e integraciones. Es privado; no lo publiques.

Endpoint

Envía un POST al endpoint de presencia de tu hotel:

POST https://api.habbolibre.org/api/v1/hotels/mi-hotel/presence
Authorization: Bearer TU_PINGBACK_SECRET
Content-Type: application/json

{
  "users_online": 42,
  "status": "online"
}

users_online

Número entre 0 y 65535. Es obligatorio.

status

Opcional: online u offline. Si envías offline, el conteo se guarda como 0.

Respuesta exitosa (200):

{
  "success": true,
  "message": "Presence reportada.",
  "hotel_slug": "mi-hotel",
  "is_online": true,
  "users_online": 42,
  "reported_at": "2026-05-06T19:00:03+00:00",
  "fresh_for_seconds": 600
}

fresh_for_seconds indica por cuánto tiempo más HabboLibre considerará el reporte vigente. Si tu reporter no envía otro reporte antes de que expire, el contador desaparecerá del listado público.

Rate limit

El endpoint acepta máximo 60 requests/minuto por IP. Reportar cada minuto desde un solo cron va sobrado; mantente por debajo de eso si el reporter corre en varios servidores.

Kit PHP

El kit descargable incluye un script PHP y un ejemplo de configuración. La idea es ejecutarlo por cron cada minuto. Por seguridad el script se descarga como .txt; renómbralo a .php en tu servidor. El archivo de variables puede renombrarse a .env.habbolibre y colocarse junto al script.

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="password"
HL_ONLINE_COUNT_SQL="SELECT COUNT(*) FROM users WHERE online = 1"

Modo de prueba

Usa HL_DRY_RUN=1 para validar la lectura de la base de datos sin enviar nada a HabboLibre.

Cron sin solapes

El script usa un lock local para evitar dos ejecuciones al mismo tiempo. Puedes cambiar la ruta con HL_LOCK_PATH.

Log de diagnóstico

Define HL_LOG_FILE=/var/log/hl-presence.log para que el script registre cada ejecución. Útil para depurar problemas de cron sin acceso al stdout.

Comportamiento ante fallos de DB

Por defecto, si la consulta SQL falla el script aborta. Define HL_REPORT_OFFLINE_ON_DB_ERROR=1 para que reporte 0 usuarios + status=offline en su lugar — útil si quieres que tu hotel se muestre offline cuando la DB está caída.

Timeouts HTTP

Ajusta con HL_TIMEOUT_SECONDS (total, por defecto 8) y HL_CONNECT_TIMEOUT_SECONDS (conexión, por defecto 4) si tu servidor tiene latencia alta.

Cron recomendado:

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

Validar instalación

Primero ejecuta HL_DRY_RUN=1 php habbolibre-presence-reporter.php para confirmar que el SQL devuelve un número.
Ejecuta el script manualmente una vez desde SSH y confirma que imprime Reported N users online.
Abre la página pública del hotel en HabboLibre; el contador debe aparecer junto al estado online.
Si el contador desaparece, el reporte venció. Revisa cron, credenciales de base de datos y el Pingback Secret.

Atajo desde el dashboard

En Dashboard → Editar hotel → Integraciones hay un botón Probar API que dispara el endpoint POST /presence/test y te devuelve los headers + payload exactos que el reporter debe enviar, sin alterar el estado real del hotel. Útil para validar tu setup antes del primer envío real.

Consultas comunes

Si tu emulador no usa users.online, cambia HL_ONLINE_COUNT_SQL por una consulta que devuelva una sola columna numérica.

# Tabla users con columna online
HL_ONLINE_COUNT_SQL="SELECT COUNT(*) FROM users WHERE online = 1"

# Tabla users con columna online como texto
HL_ONLINE_COUNT_SQL="SELECT COUNT(*) FROM users WHERE online = '1'"

# Tabla de sesiones activas
HL_ONLINE_COUNT_SQL="SELECT COUNT(*) FROM user_sessions WHERE last_activity >= UNIX_TIMESTAMP() - 120"

Ejemplo cURL

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

Seguridad

No pongas tu Pingback Secret en código público ni en el frontend.
Coloca el script y .env.habbolibre fuera de la carpeta pública del hotel si tu hosting lo permite.
Ejecuta el reporter desde el backend o cron del hotel, nunca desde el navegador.
Si sospechas que tu secret se filtró, genera uno nuevo desde administración antes de publicar la integración.
HabboLibre nunca muestra la IP ni el puerto del hotel al público; solo muestra estado y conteo reportado.