Eventos de cliente

Un evento de cliente viaja directamente de un cliente suscrito a los demás en el mismo canal. Tu backend recibe una copia solo si lo suscribes al grupo de webhooks client-events.

Usa eventos de cliente para señales efímeras como indicadores de escritura, posiciones de cursor o latidos de actividad. Evitan un viaje de ida y vuelta a través de tu API.

No uses eventos de cliente como estado autoritativo. El edge de Realtime no valida sus payloads, así que los receptores no pueden confiar en su contenido. Envía mensajes de chat almacenados, cambios de estado y acciones sensibles a permisos a través de tu servidor con Publicar eventos.

Habilitar eventos de cliente

Habilita Client Events para la app en la página de Realtime apps. También puedes establecer client_events en true a través de la API de Realtime. La configuración se aplica a toda la app. Hasta que la habilites, el edge de Realtime rechaza los eventos de cliente.

Requisitos de los eventos de cliente

El edge de Realtime aplica tres reglas:

El nombre empieza con client-. Este prefijo reservado identifica los eventos de cliente. Los clientes rechazan nombres de evento que lo omitan.
El canal es privado o de presencia. Un canal público se rechaza, y ese es el objetivo: la clave de la app se incluye en tu página, así que cualquiera podría suscribirse a un canal público y empezar a escribir en él. La autorización es lo que hace que un cliente sea lo suficientemente confiable para transmitir, y solo los canales privados y de presencia la tienen.
El emisor está suscrito. La conexión ya tiene que estar en el canal al que dispara, de modo que un cliente no pueda escribir en una sala a la que nunca fue admitido.

Si un evento incumple una de estas reglas, el edge devuelve un error a nivel de conexión. Vincula el error durante el desarrollo:

bird.connection.bind("error", (e) => console.warn("edge refused:", e.message));

bird.onError { error in
    print("edge refused:", error.message)
}

bird.onError { error ->
    println("edge refused: ${error.message}")
}

Envío

import { BirdRealtime } from "@messagebird/realtime";

const bird = new BirdRealtime({
  appKey: "your-app-key",
  region: "us1",
  authEndpoint: "/bird/auth",
});

const room = bird.subscribe("presence-room-1");

input.addEventListener("input", () => {
  room.trigger("client-typing", { at: Date.now() });
});

let room = bird.subscribe("presence-room-1")

// From whatever your UI calls on a keystroke.
func typingChanged() throws {
    guard room.subscribed else { return }
    try room.trigger("client-typing", data: ["at": Date().timeIntervalSince1970])
}

val room = bird.subscribe("presence-room-1")

// From whatever your UI calls on a keystroke.
fun typingChanged() {
    if (!room.subscribed) return
    room.trigger("client-typing", buildJsonObject { put("at", System.currentTimeMillis()) })
}

El payload opcional puede ser una cadena, un objeto o un arreglo. trigger devuelve true después de enviar el frame y false si el canal no está suscrito. Para enviar inmediatamente después de unirte, espera a bird:subscription_succeeded.

Swift y Kotlin toman el payload como el valor JSON de su lenguaje: Any? codificado con JSONSerialization en Swift, JsonElement en Kotlin.

Recepción

Vincula el nombre que enviaste, en el mismo canal, exactamente como un evento publicado por el servidor:

room.bind("client-typing", (data) => showTypingIndicator(data));

room.bind("client-typing") { data in
    showTypingIndicator(data)
}

room.bind("client-typing") { data ->
    showTypingIndicator(data)
}

La conexión que envía no recibe su propio evento. Otras conexiones que pertenecen a la misma persona sí lo reciben, así que filtra esas copias cuando sea necesario.

Límites de frecuencia

Cada conexión puede enviar hasta 10 eventos de cliente por segundo. El mismo límite se aplica a cada conexión en la app.

Cuando una conexión excede el límite, el edge descarta el evento y reporta un error sin cerrar la conexión. Vincula el evento error de la conexión y limita las entradas de alta frecuencia como el movimiento del cursor.

Recibir eventos de cliente en tu servidor

Para recibir eventos de cliente en tu servidor, suscribe un endpoint al grupo realtime.client_events. El type de cada webhook agrega el prefijo realtime. al nombre del evento de cliente, así que client-typing se convierte en realtime.client-typing:

Ejemplo de código

{
  "data": {
    "channel_name": "presence-room-1",
    "event": "client-typing",
    "data": "{\"at\":1785495600000}",
    "connection_id": "26896.319537",
    "member_id": "u_42"
  },
  "timestamp": "2026-07-31T09:00:00Z",
  "type": "realtime.client-typing"
}

member_id aparece para canales de presencia y está ausente para canales privados. Las señales de alto volumen como las posiciones de cursor producen un webhook por cada evento de cliente. Consulta Webhooks de Realtime para el sobre, la firma y otros grupos.

Próximos pasos

Webhooks de Realtime cubre la recepción de eventos de cliente y la actividad de canales en tu propio endpoint.
Canales de presencia dan a los eventos de cliente una identidad de miembro, y la lista de miembros contra la cual representarlos.
Publicar eventos es la ruta del lado del servidor, para todo aquello en lo que no se debe confiar a un cliente.

Recursos relacionados

Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.

Explorar la funcionalidadRealtime Seguir la ruta de aprendizajeBuild your first integration Guía de implementaciónSend your first realtime event

Prueba el ejercicio y obtén un resumen de implementación