Documentación de @uStreamersBOT

¿Qué hace hoy en tu canal?

• Anuncia alertas de voz aprobadas: cada vez que aceptás el audio de un espectador en tu panel u OBS, el bot avisa en el chat quién envió la nota de voz y cuántos segundos dura.
• Comandos integrados: responde consultas estándar de la comunidad como !followage, !uptime, !game, !title, !accountage y !commands.
• Comandos personalizados: creá respuestas automáticas (como !discord, !redes o !pc) con permisos específicos, alias, cooldowns y variables en tiempo real.
• Contadores numéricos: llevá la cuenta exacta de muertes, victorias o momentos del directo con incrementos atómicos desde la app o el chat.
• Timers automáticos: emití mensajes periódicos con rotación de avisos únicamente cuando estés en vivo y tu chat registre actividad real.
• Gestión desde el chat: tus moderadores pueden crear, modificar y eliminar comandos o ajustar contadores sin salir del directo.
• Migración asistida: importá tu configuración previa de Nightbot, StreamElements, Botrix o archivos CSV/JSON con vista previa y conversión de variables.
• IA del chat (uStreamers Plus+, opcional): si la encendés desde Studio, responde con inteligencia artificial las preguntas que tu comunidad escriba con el comando que elijas (por defecto !ia), siempre marcadas con 🤖.
• Dibujos con IA (uStreamers Plus+ o MAX, opcional): si activás el comando (por defecto !dibujo), le responde en el chat a cada pedido de dibujo: si va en camino, si pasa antes por tus moderadores o por qué no se puede. Ver dibujos y personajes con IA.
• Anuncia regalos de planes: si alguien le regala Plus+ o MAX a un espectador desde su tarjeta en el chat de tu canal, el bot lo anuncia. Lo apagás con «Anunciar regalos de planes» en sus ajustes.

• Solo procesa mensajes con prefijo !: el bot ignora por completo las conversaciones normales del chat. Únicamente analiza los mensajes que comienzan con el carácter de comando (ej. !redes, !uptime).
• Conteo de actividad para timers sin guardar contenido: para calcular si se alcanzó el mínimo de líneas de chat que requiere un timer periódico, el sistema utiliza un acumulador numérico en memoria (un número entero que suma 1 por línea). No se guarda el texto del mensaje, ni quién lo escribió, ni las conversaciones. Al disparar el timer, el contador vuelve a cero.
• Sin interacción en chats compartidos (Streamear Juntos / Shared Chat): si tu canal participa de una transmisión compartida con otro streamer, el bot detecta los mensajes originados en el canal invitado y los ignora en silencio. Nadie de otro canal puede activar comandos ni modificar ajustes en el tuyo.
• Anti-bucle e ignorar otros bots: el bot ignora automáticamente a otros bots reconocidos de la industria (Nightbot, StreamElements, Botrix, etc.) y a su propia cuenta para imposibilitar respuestas infinitas o bucles de spam.
• Datos de seguidores en Kick: la API oficial de Kick no proporciona un endpoint público para consultar desde qué fecha sigue un espectador al canal. Por esa razón, cuando un usuario sigue tu canal de Kick, uStreamers registra mediante webhook oficial el ID de Kick, su nombre de usuario y la fecha en que comenzó a seguirte. Esos datos se conservan exclusivamente para que el comando !followage pueda responder con certeza en Kick.
• IA del chat (sólo si la encendés, con uStreamers Plus+): junto con el de los dibujos, es el único comando cuyo texto sale de uStreamers hacia un proveedor externo. Cuando alguien escribe el comando de la IA (por defecto !ia), su pregunta y su nombre visible se envían a OpenAI para generar y moderar la respuesta y, si hace falta un dato reciente, una consulta breve de palabras clave, sin el nombre de quien preguntó, se envía a Brave o a Perplexity. No guardamos las preguntas ni las respuestas, y cada respuesta sale marcada con 🤖. Detalle en la sección 17 de la Política de Privacidad.
• Dibujos con IA (sólo si los activás, con uStreamers Plus+ o MAX): cuando alguien escribe el comando de los dibujos (por defecto !dibujo), el texto del pedido se envía a OpenAI, sin el nombre de quien lo pidió, para revisarlo y generar la imagen. El pedido se borra cuando el dibujo termina. Los globos del escenario de personajes no pasan por el bot: los muestra la fuente de OBS en el momento y no se guardan. Detalle en la sección 23 de la Política de Privacidad.

Campos del editor de comandos

• Nombre del comando: entre 1 y 32 caracteres en minúsculas. Se admiten letras (a-z), números (0-9), guiones bajos (_) y caracteres con tilde o eñe (á, é, í, ó, ú, ü, ñ). No incluyas el signo !, la app lo gestiona automáticamente.
• Respuesta: texto que enviará el bot, de 1 a 500 caracteres. Podés combinar texto plano con variables dinámicas entre llaves (ej. {user}).
• Alias (opcional): hasta 5 nombres alternativos que disparen la misma respuesta (ej. dc para !discord). Tienen las mismas reglas de validación que el nombre principal.
• Permiso requerido: restringe quién puede ejecutar el comando en el chat:
  • Todos (Everyone): cualquier espectador.
  • Suscriptores (Subscriber): suscriptores y fundadores (más VIPs, mods y streamer).
  • VIPs (Vip): usuarios con insignia VIP (más mods y streamer).
  • Moderadores (Moderator): moderadores del canal y streamer.
  • Solo streamer (Broadcaster): exclusivamente el creador del canal.
• Cooldown global: tiempo mínimo en segundos que debe transcurrir entre usos del comando por cualquier espectador (0 a 3.600 segundos; valor por defecto: 5 segundos).
• Cooldown por usuario: tiempo en segundos que debe esperar un mismo espectador antes de volver a usarlo (0 a 3.600 segundos; valor por defecto: 15 segundos).
• Plataformas: elegí si responderá en Twitch, Kick o Ambas simultáneamente.
• Solo en vivo: si está marcado, el bot ignorará el comando si el directo está apagado en esa plataforma.
• Habilitado: interruptor para pausar o reactivar el comando en cualquier momento sin necesidad de borrarlo.

Sintaxis y comandos disponibles

• Crear comando:
  !addcom <nombre> [-cd=segundos] [-ul=nivel] [-a=alias1,alias2] <respuesta>
  Ejemplo simple: !addcom discord Unite a discord.gg/comunidad
  Ejemplo avanzado: !addcom sorteo -cd=30 -ul=sub -a=giveaway,premio ¡Sorteo activo para subs!
• Editar comando existente:
  !editcom <nombre> [-cd=segundos] [-ul=nivel] [-a=alias1,alias2] <respuesta>
  Ejemplo: !editcom discord Nuevo enlace actualizado: discord.gg/nuevo
• Eliminar comando:
  !delcom <nombre>
  Ejemplo: !delcom sorteo
• Sintaxis alternativa compatible con Nightbot:
  También se aceptan !commands add <nombre> ..., !commands edit <nombre> ... y !commands delete <nombre> (o !commands del).
• Gestión de contadores:
  !counter <nombre> → Lee el valor actual.
  !counter <nombre> +N o -N (o + / -) → Suma o resta al contador.
  !counter <nombre> set <N> → Fija el contador en un valor numérico específico.

Cómo funcionan

• Desde la app móvil: entrá a la sección Contadores para ver la lista de todos tus contadores, crear nuevos con su valor inicial, editar su valor manualmente con un toque o eliminarlos.
• Desde el chat: los moderadores pueden sumar, restar o fijar el número en cualquier momento con !counter <nombre> +1 o !counter <nombre> set 0.
• En tus propios comandos: utilizá {count:nombre} para incrementar en 1 y mostrar el nuevo número cada vez que alguien escriba el comando (ej: !morí), o {getcount:nombre} para consultar el total sin sumarle nada.
• Creación automática: si en una respuesta escribís {count:nuevo} y ese contador aún no existe, el bot lo creará automáticamente con valor 1.
• Seguridad y concurrencia: cada canal puede tener hasta 100 contadores personalizados. Los incrementos son atómicos a nivel de base de datos, por lo que nunca habrá pérdidas de conteo si dos personas ejecutan un comando al mismo tiempo.

Condiciones necesarias para que dispare un timer

Para evitar spammear un chat inactivo o enviar mensajes cuando no estás transmitiendo, el worker de uStreamers (que revisa cada 30 segundos) solo dispara un timer si se cumplen todas las siguientes condiciones simultáneamente:

1. Canal en vivo: tu canal debe estar transmitiendo en directo en esa plataforma específica.
2. Intervalo cumplido: deben haber transcurrido los minutos configurados en Intervalo (entre 5 y 240 minutos) desde el último disparo del timer (o desde el inicio de la transmisión si nunca disparó en esta sesión).
3. Líneas mínimas de chat: el chat debe haber registrado al menos la cantidad de mensajes indicada en Líneas mínimas (de 0 a 500 mensajes) de espectadores reales (no bots) desde el último disparo.

¿Qué pasa con 0 líneas mínimas? Si configurás 0 líneas mínimas, el timer disparará estrictamente al cumplirse el tiempo, sin importar si alguien habló en el chat.

Rotación y reglas operativas

• Rotación de 1 a 5 mensajes: podés agregar hasta 5 mensajes distintos dentro del mismo timer. El bot los enviará alternadamente en rueda (round-robin), uno en cada disparo.
• Separación inteligente de timers: si tenés varios timers configurados y dos coinciden en el mismo momento, el bot dispara uno y espera al próximo ciclo de 30 segundos para enviar el siguiente, evitando publicar dos mensajes pegados en el mismo segundo.
• Variables en timers: las variables que dependen de un espectador (como {user}, {touser} o {1}) no tienen sentido en un timer y se evalúan vacías. Sí podés usar variables de canal como {channel}, {uptime}, {game}, {title}, {time:...}, {random:...}, {pick:...} y contadores {getcount:...}.
• Límite: cada canal puede tener hasta 20 timers automáticos.

Orígenes de importación disponibles

• Nightbot (Conexión OAuth2 oficial):
  Conectás tu cuenta de Nightbot mediante autorización oficial. uStreamers únicamente solicita permisos de sólo lectura para comandos y timers. Por seguridad estricta, el token de acceso se utiliza una única vez en memoria para descargar tu lista y se destruye de inmediato; jamás se guarda en bases de datos ni se imprime en logs. Si la integración con Nightbot no está habilitada en el servidor, aparecerá indicada con la insignia "Pronto".
• StreamElements (Token JWT):
  Pegás tu token JWT personal de StreamElements. Lo encontrás en el panel de StreamElements → Ajustes de cuenta (Account Settings) → Canal (Channel) → Mostrar token (Show secrets / JWT Token).
  Aviso de seguridad: uStreamers nunca guarda ni loguea tu token JWT. Se usa exclusivamente en memoria durante la consulta. Recomendamos regenerar el token en StreamElements una vez finalizada la importación.
• Botrix / Archivo / Texto pegado:
  Podés pegar directamente tu lista de comandos en 4 formatos reconocidos:
  !nombre respuesta
!nombre - respuesta
!nombre: respuesta
!nombre<TAB>respuesta
  También podés subir o pegar un archivo CSV (hasta 1.000 filas y 1 MB) con columnas name,response,userlevel,globalcooldown,usercooldown,aliases,platforms,onlywhenlive, o una copia de seguridad en formato JSON oficial de uStreamers (format: "ustreamers-bot", version: 1).

Vista previa y resolución de conflictos

Antes de aplicar cualquier cambio, la app te presenta una pantalla de previsualización detallada donde cada elemento muestra su estado:

• Listo: totalmente compatible y listo para importarse.
• Listo con avisos: compatible tras alguna adaptación automática (por ejemplo, recortar un texto a 500 caracteres, acotar un intervalo de timer al rango 5–240 minutos o convertir el nivel "Regular" de Nightbot a VIP).
• Ya existe (Conflicto): el nombre coincide con un comando, alias, contador o timer que ya tenés. Podés elegir entre tres estrategias:
  • Omitir (Skip): se mantiene el que ya tenías y se saltea el importado.
  • Sobrescribir (Overwrite): se actualiza tu comando con el texto y ajustes importados.
  • Renombrar con número (Rename): se le asigna automáticamente un sufijo numérico (ej. !redes_2).
• No compatible: el elemento no se puede importar y se descarta automáticamente.

¿Qué no se importa y por qué?

• Variables externas: llamadas como $(urlfetch), $(customapi), $(eval) o equivalentes de StreamElements y Botrix se descartan por seguridad (prevención de vulnerabilidades SSRF y ejecución de código ajeno).
• Palabras clave o expresiones regulares: en uStreamers todos los comandos inician con el prefijo !nombre.
• Susurros de StreamElements: pasan a responderse normalmente en el chat público.
• Timers exclusivamente offline: quedan descartados porque uStreamers solo emite timers en directo.

Vigencia y límites: la sesión de vista previa dura 30 minutos y se confirma una sola vez para evitar duplicados accidentales. Cada streamer cuenta con un límite de 10 importaciones por hora.

Tabla de equivalencias de variables

Esta tabla detalla exactamente las traducciones que el motor de importación realiza desde cada bot:

Estamos para ayudarte

Nuestro equipo de soporte revisa consultas a diario. Escribinos directamente por correo y te damos una mano con la configuración de tu canal.