Referencia del Editor de widgets

Abrir en el panel

Esta página lista lo que tu código puede usar en un widget del Editor de widgets de KickBot: los eventos widgetEvent, el objeto globalValues, el objeto userVariables y las funciones de ayuda de window.kickbotWidget. Cada widget es HTML, CSS y JavaScript normal que se ejecuta como fuente de navegador en OBS. KickBot se conecta a Kick por ti y envía los eventos a tu código.

Cuando OBS abre la URL del widget, KickBot:

Carga la página del widget con un fondo transparente.
Añade tu CSS en un elemento <style> y pone tu HTML en la página.
Carga en globalValues los datos de tu canal desde Kick (número de seguidores, número de espectadores, estado del stream y chat reciente).
Ejecuta tu JavaScript. Se ejecuta una vez, después del paso 3, así que globalValues ya está listo cuando empieza tu código.
Envía los eventos en vivo a tu código como eventos widgetEvent en document.

Tu JavaScript puede leer dos objetos sin importar nada: globalValues y userVariables. Las funciones de ayuda están en window.kickbotWidget.

Límites:

Elemento	Límite
Ancho y alto	Se ajustan en Ajustes básicos. Un widget nuevo en blanco mide 800 × 600. La ventana Nuevo widget acepta hasta 7680 × 4320.
HTML, CSS y JavaScript	Hasta 2,000,000 caracteres por archivo
Nombre del widget	Hasta 500 caracteres
Archivos para variables de usuario	Hasta 25 MB por archivo
Widgets del editor en el plan Gratis	10 (sin límite con Premium)

Escucha los eventos

Añade un listener de widgetEvent en document. Cada evento tiene event.detail con tres campos:

Campo	Tipo	Valor
`event_name`	string	El evento, por ejemplo `followEvent`
`source`	string	Siempre `kick`
`data`	object	Los datos del evento (ver abajo)

document.addEventListener('widgetEvent', (event) => {
    const { event_name, data } = event.detail;

    if (event_name === 'followEvent') {
        showAlert(data.user.username + ' followed!');
    }
    if (event_name === 'subEvent') {
        showAlert(data.username + ' subscribed for ' + data.months + ' months');
    }
});

Lista de eventos

Nombre del evento	Cuándo se dispara	Botón de prueba
`subEvent`	Un espectador se suscribe	Sub
`subGiftEvent`	Un espectador regala subs	Sub regalado
`kicksEvent`	Un espectador envía KICKs	KICKs
`followEvent`	Un espectador te sigue	Follow
`unfollowEvent`	Un espectador deja de seguirte	Unfollow
`chatMessageEvent`	Se envía un mensaje en el chat	Mensaje
`chatMessageDeletedEvent`	Un moderador elimina un mensaje	Mensaje eliminado
`chatMessagePinnedEvent`	Se fija un mensaje	Mensaje fijado
`chatMessageUnpinnedEvent`	Se quita el mensaje fijado	Mensaje desfijado
`chatClearedEvent`	Un moderador limpia el chat	Chat limpiado
`followerCountUpdatedEvent`	Kick envía un nuevo número de seguidores	Recuento de followers actualizado
`subCountUpdatedEvent`	Cambió el número de subs en Kick	Recuento de subs actualizado
`viewerCountUpdatedEvent`	Kick envía un nuevo número de espectadores	Recuento de espectadores actualizado
`raidEvent`	Otro canal te hace un raid (host)	Raid
`streamOnline`	Empieza tu stream	Stream en directo
`streamOffline`	Termina tu stream	Stream offline

No hay un evento de propina. Para las alertas de propina, usa el widget de alertas de propina.

Datos de los eventos

Estos son los datos que llegan en event.detail.data. Coinciden con los eventos de prueba del editor. Los eventos reales pueden tener más campos. Los nombres, números e IDs de aquí son ejemplos.

subEvent

{
    months: 1,
    username: 'viewer_one',
    chatroom_id: 3847194
}

subGiftEvent

{
    chatroom_id: 3847194,
    gifted_usernames: ['viewer_one', 'viewer_two', 'viewer_three'],
    gifter_username: 'big_gifter'
}

kicksEvent

{
    message: 'Great stream!',
    sender: { id: 12345678, username: 'viewer_one', username_color: '#93EBE0' },
    gift: {
        gift_id: 'full_send',
        name: 'Full Send',
        amount: 100,
        type: 'BASIC',
        tier: 'BASIC',
        character_limit: 0,
        pinned_time: 0
    },
    channel: 'channel_3984507'
}

followEvent y unfollowEvent (misma forma; followers_count es el número nuevo)

{
    id: 'd4e5f6a7-89b0-12c3-d456-78901e2f3a4b',
    channel: { id: 3984507, slug: 'kickbotdev' },
    user: { id: 14873539, slug: 'viewer_one', username: 'viewer_one' },
    followers_count: 36,
    created_at: '2024-05-13T22:19:07+00:00'
}

chatMessageEvent

{
    id: '85c884b3-7377-478c-b6aa-22b7db752b93',
    chatroom_id: 3974112,
    content: 'hello [emote:37226:KEKW]',
    type: 'message',
    created_at: '2024-05-13T22:29:52+00:00',
    sender: {
        id: 4063326,
        username: 'viewer_one',
        slug: 'viewer_one',
        identity: {
            color: '#72ACED',
            badges: [{ type: 'subscriber', text: 'Subscriber', count: 3 }]
        }
    }
}

Los emotes de Kick están en content como [emote:ID:NAME]. Usa createChatMessageFragment (consulta Muestra el texto del chat de forma segura) para convertirlos en imágenes.

chatMessageDeletedEvent

{
    id: '9cd3788a-ecd2-4051-a162-a7ea9be8ce7a',
    message: { id: '89d6be86-63db-4581-922e-14a6c4a9c2e6' }
}

Usa data.message.id para encontrar y quitar el mensaje que mostraste.

chatMessagePinnedEvent (data.message tiene la misma forma que los datos de un chatMessageEvent)

{
    message: {
        id: '5d798a38-ad17-45e4-8169-bda2faa85b79',
        chatroom_id: 3974112,
        content: 'This is a pinned message!',
        type: 'message',
        created_at: '2024-05-13T22:30:41+00:00',
        sender: { id: 4063326, username: 'kickbotdev', slug: 'kickbotdev', identity: { color: '#72ACED', badges: [] } }
    }
}

chatMessageUnpinnedEvent: data es un array vacío ([]).

chatClearedEvent

{ id: '47e3596f-0274-46e0-85b1-029fa3bfc5ea' }

followerCountUpdatedEvent (fíjate en el camelCase de followersCount)

{ followersCount: 1532, channel_id: 4599, created_at: 1715639984 }

subCountUpdatedEvent

{ subscriber_count: 184, channel_id: 4599 }

viewerCountUpdatedEvent

{ viewer_count: 320, channel_id: 5937485 }

raidEvent

{
    chatroom_id: 839485,
    optional_message: 'gg stream',
    number_viewers: 150,
    host_username: 'raiding_channel'
}

streamOnline

{
    livestream: {
        id: 3984507,
        channel_id: 3984507,
        session_title: 'Test stream!',
        created_at: '2024-05-13T22:30:41+00:00'
    }
}

streamOffline

{
    livestream: {
        id: 3984507,
        channel: { id: 3984507, is_banned: false }
    }
}

Valores globales

globalValues guarda el estado actual de tu canal. KickBot lo rellena antes de que se ejecute tu código y lo mantiene al día a medida que llegan eventos. Úsalo para dibujar tu widget al principio, antes de que llegue ningún evento.

globalValues = {
    subCount: 184,
    followerCount: 1532,
    viewerCount: 320,
    lastFollower: { /* the last follow */ },
    lastSub: { /* the last sub, for example { username, months } */ },
    lastGiftedSub: { /* the last gift, for example { gifter_username, gifted_usernames } */ },
    chatMessages: [ /* chatMessageEvent payloads */ ],
    streamerInfo: {
        kick: {
            username: 'KickBotDev',
            slug: 'kickbotdev',
            profile_picture: 'https://files.kick.com/images/user/.../fullsize.webp',
            user_id: '4063326',
            channel_id: '3984507',
            chatroom_id: '3974112',
            bio: 'Channel bio',
            subscriber_badges: [ /* your channel's sub badges from Kick */ ]
        }
    },
    currentStream: {
        is_live: true,
        title: 'Stream title',
        started_at: '2026-10-24 18:00:00'
    }
}

Valor	Cómo se actualiza
`subCount`	Se carga desde Kick. Sube 1 con cada `subEvent` y 1 con cada sub regalado, y `subCountUpdatedEvent` lo vuelve a fijar.
`followerCount`	Se carga desde Kick. Lo fijan `followEvent`, `unfollowEvent` y `followerCountUpdatedEvent`.
`viewerCount`	Se carga desde Kick (0 cuando no estás en vivo). Lo fija `viewerCountUpdatedEvent`.
`lastFollower`, `lastSub`, `lastGiftedSub`	El último que KickBot vio en tu canal, o `null`. Se actualiza con el evento correspondiente.
`chatMessages`	El chat reciente de Kick cuando carga el widget, y después cada mensaje nuevo. Guarda los 100 más recientes. `chatClearedEvent` lo vacía. Para ocultar los mensajes eliminados, gestiona `chatMessageDeletedEvent` en tu propio código.
`streamerInfo.kick`	Tu perfil de Kick. No cambia mientras el widget se ejecuta.
`currentStream`	Se carga desde Kick cuando carga el widget. `streamOnline` y `streamOffline` no lo actualizan. Escucha esos eventos si necesitas saber si estás en vivo en cada momento.

Variables de usuario

Las variables de usuario son los ajustes que ven los streamers cuando abren tu widget en Widgets guardados. Las añades en Variables de usuario, en el editor. En tu código, lee el valor con userVariables.<variable name>.value.

const goal = Number(userVariables.follower_goal.value);
document.body.style.color = userVariables.text_color.value;

Campos de una variable:

Campo	Qué es
Título	El nombre que ven los streamers.
Nombre de la variable	El nombre en tu código. Solo letras, números y `_`. No puedes cambiarlo después de crear la variable.
Tooltip	Texto de ayuda extra debajo del título.
Tipo de variable	Consulta la tabla de abajo.
Valor por defecto	El valor antes de que el streamer lo cambie. Puede estar vacío.
Obligatoria	Los streamers tienen que escribir un valor antes de poder guardar.

Tipo	Lo que ve el streamer	`value` en tu código
Texto	Un cuadro de texto	Un string
Número	Un cuadro numérico	Un número o un string numérico. Usa `Number()` para ir sobre seguro.
Color	Un selector de color	Un string con un color hex, por ejemplo `#ffffff`
Desplegable	Un menú con tus opciones	La opción elegida como string. Por defecto es la primera opción.
Interruptor	Un interruptor de activar y desactivar	`true` o `false`
Imagen/GIF	Un cuadro de URL y un botón para subir	Una URL al archivo
Vídeo	Un cuadro de URL y un botón para subir	Una URL al archivo
Audio	Un cuadro de URL y un botón para subir	Una URL al archivo

KickBot guarda los archivos subidos, y value es la URL del archivo. Usa el menú junto a una variable para subirla o bajarla, editarla o eliminarla. El orden en el editor es el orden que ven los streamers.

Muestra el texto del chat de forma segura

Trata cada campo de un evento y cada variable de usuario como texto de un desconocido. KickBot limpia el texto del chat y de los eventos antes de que llegue a tu código, así que es seguro como texto HTML, pero no como URL, CSS o script. No pongas campos de eventos sin procesar en innerHTML. Usa estas funciones de ayuda:

Función de ayuda	Qué hace
`window.kickbotWidget.createChatMessageFragment(content, font_size)`	Devuelve un `DocumentFragment` con nodos de texto e imágenes de los emotes de Kick. Los emotes miden `font_size + 3` píxeles. `font_size` es 20 por defecto.
`window.kickbotWidget.createTextNode(value)`	Devuelve un nodo de texto para cualquier valor.
`window.kickbotWidget.escapeHtmlText(value)`	Escapa el texto para usarlo entre etiquetas HTML cuando tienes que construir un string de HTML. No lo uses para URLs, CSS ni scripts.

document.addEventListener('widgetEvent', (event) => {
    if (event.detail.event_name !== 'chatMessageEvent') return;
    const data = event.detail.data;

    const line = document.createElement('div');
    line.id = 'msg-' + data.id;
    const name = document.createElement('strong');
    name.style.color = data.sender.identity.color;
    name.append(window.kickbotWidget.createTextNode(data.sender.username + ': '));
    line.append(name);
    line.append(window.kickbotWidget.createChatMessageFragment(data.content, 20));
    document.getElementById('chat').append(line);
});

Para otros textos, usa textContent o createTextNode.

La vista previa

La vista previa del editor funciona como OBS, con algunas diferencias para hacer pruebas:

Cuando cambias el código o una variable de usuario, la vista previa vuelve a ejecutar tu JavaScript. Antes, KickBot quita los listeners de widgetEvent de la ejecución anterior. Los temporizadores de setInterval y setTimeout no se quitan, así que haz clic en el botón de recargar si se acumulan.
Cuando cambias el ancho o el alto, la vista previa se recarga.
Los eventos de prueba solo van a la vista previa. Un Follow de prueba suma 1 a globalValues.followerCount, y Unfollow resta 1. Recuento de espectadores actualizado envía un número de ejemplo. Mensaje eliminado quita un mensaje al azar del chat de la vista previa.
Si tu canal todavía no tiene un último seguidor, sub o sub regalado, la vista previa usa datos de ejemplo para lastFollower, lastSub y lastGiftedSub.
Para ver la salida de console.log y los errores, haz clic en el botón de ventana aparte y abre las herramientas de desarrollador en esa ventana.

Ejemplo: meta de seguidores

Esta es una meta de seguidores corta. Usa un listener de eventos, globalValues y dos variables de usuario: follower_goal (Número) y bar_color (Color).

HTML:

<div class="goal">
    <span id="count"></span> / <span id="target"></span>
    <div class="bar"><div class="fill"></div></div>
</div>

CSS:

body { margin: 0; font-family: Arial, sans-serif; color: #fff; }
.goal { padding: 12px; background: #100c28; border-radius: 16px; font-size: 32px; font-weight: bold; }
.bar { height: 24px; margin-top: 8px; background: #3d3957; border-radius: 12px; overflow: hidden; }
.fill { height: 100%; width: 0; transition: width 0.3s ease; }

JavaScript:

const target = Number(userVariables.follower_goal.value) || 100;
document.getElementById('target').textContent = target;
document.querySelector('.fill').style.background = userVariables.bar_color.value;

function update(count) {
    document.getElementById('count').textContent = count;
    document.querySelector('.fill').style.width = Math.min((count / target) * 100, 100) + '%';
}

document.addEventListener('widgetEvent', (event) => {
    const { event_name, data } = event.detail;
    if (event_name === 'followEvent' || event_name === 'unfollowEvent') update(data.followers_count);
    if (event_name === 'followerCountUpdatedEvent') update(data.followersCount);
});

update(globalValues.followerCount);

Para una versión completa con más ajustes, empieza un widget nuevo desde la plantilla Simple Follower Goal.

Consejos

Dibuja el primer estado desde globalValues y después cámbialo con los eventos. Un widget que espera un evento se ve vacío hasta que pasa algo.
Widgets guardados solo muestra botones de prueba para los nombres de eventos que aparecen en tu JavaScript. Escribe el nombre completo del evento (por ejemplo 'followEvent') en tu código para que los streamers puedan probar tu widget.
Deja el fondo transparente, salvo que el fondo sea parte del diseño, para que el widget quede encima de la escena.
También puedes gestionar los widgets del editor con la API de KickBot. Consulta la referencia de la API de widgets.