Watchtime

Consulta el tiempo de permanencia o seguimiento de un viewer en tu canal con un mensaje enfocado en el tiempo que lleva viéndote. La respuesta es texto plano lista para bots como Nightbot, StreamElements, etc.

GEThttps://ttv.losperris.dev/api/watchtime

AutenticaciónTodos los endpoints requieren el parámetro apiKey en la query. Obtén la tuya desde el panel.›

Límites

Rate limit y caché

Usa el límite general de tu rol (30–120 req/min). Las respuestas se cachean según el rol (Default 60 s → Partner 240 s). Se guarda la fecha inicial; en cada acierto de caché el tiempo se recalcula en tiempo real, sin llamar otra vez a Twitch.

Parámetros

Parámetro	Tipo	Requerido	Descripción
channel	String	Sí	Canal de Twitch donde se ejecuta el comando.
user	String	Sí	Usuario cuyo tiempo se consulta.
apiKey	String	Sí	Clave de API de tu cuenta.
lang	String	No	Idioma de respuesta (es, en, pt). Por defecto es.
template	String	No	Plantilla personalizada con {user}, {time} y {channel}.

Ejemplo de petición

Con cURL o URL la respuesta muestra solo el mensaje. Con cURL -i ves cabeceras HTTP + cuerpo.

cURLcURL -iURL

curl --request GET \
  --url 'https://ttv.losperris.dev/api/watchtime?channel=losperris&user=viewer123&apiKey=TU_API_KEY' \
  --header 'Accept: text/plain'

curl -i --request GET \
  --url 'https://ttv.losperris.dev/api/watchtime?channel=losperris&user=viewer123&apiKey=TU_API_KEY' \
  --header 'Accept: text/plain'

https://ttv.losperris.dev/api/watchtime?channel=losperris&user=viewer123&apiKey=TU_API_KEY

Plantillas personalizadas

Añade template para controlar el mensaje del bot. Placeholders: {user}, {time} y {channel}.

cURLcURL -iURL

curl --request GET \
  --url 'https://ttv.losperris.dev/api/watchtime?channel=losperris&user=viewer123&apiKey=TU_API_KEY&template=%7Buser%7D+lleva+%7Btime%7D+viendo+a+%7Bchannel%7D' \
  --header 'Accept: text/plain'

curl -i --request GET \
  --url 'https://ttv.losperris.dev/api/watchtime?channel=losperris&user=viewer123&apiKey=TU_API_KEY&template=%7Buser%7D+lleva+%7Btime%7D+viendo+a+%7Bchannel%7D' \
  --header 'Accept: text/plain'

https://ttv.losperris.dev/api/watchtime?channel=losperris&user=viewer123&apiKey=TU_API_KEY&template=%7Buser%7D+lleva+%7Btime%7D+viendo+a+%7Bchannel%7D

Respuestas

200Sin follow/tiempoKey inválida (200)429

viewer123 lleva 2 años y 3 meses viendo a losperris.

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Cache-Control: public, s-maxage=10, stale-while-revalidate
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1710000060

viewer123 lleva 2 años y 3 meses viendo a losperris.

viewer123 no sigue a losperris, así que no hay watchtime que mostrar.

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Cache-Control: public, s-maxage=10, stale-while-revalidate
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1710000060

viewer123 no sigue a losperris, así que no hay watchtime que mostrar.

Error de autenticación. Clave API inválida o expirada. Regenerala o pide ayuda a Ponss 🦆

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Cache-Control: public, s-maxage=10, stale-while-revalidate
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1710000060

Error de autenticación. Clave API inválida o expirada. Regenerala o pide ayuda a Ponss 🦆

(sin contenido)

HTTP/1.1 429 Too Many Requests
Content-Type: text/plain; charset=utf-8
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1710000060

Comportamiento en bots

Errores de API Key y de negocio devuelven **HTTP 200** con el mensaje en el cuerpo (así Nightbot y StreamElements lo muestran en el chat). El rate limit (**429**) devuelve **cuerpo vacío**.