Eventos de cliente

Um evento de cliente viaja diretamente de um cliente inscrito para os demais no mesmo canal. Seu backend recebe uma cópia apenas se você inscrevê-lo no grupo de webhooks client-events.

Use eventos de cliente para sinais de curta duração, como indicadores de digitação, posições de cursor ou heartbeats de atividade. Eles evitam uma ida e volta pelo seu API.

Não use eventos de cliente como estado autoritativo. O edge do Realtime não valida os payloads deles, então os destinatários não podem confiar no conteúdo. Envie mensagens de chat armazenadas, mudanças de estado e ações sensíveis a permissão pelo seu servidor com Publicação de eventos.

Ativar eventos de cliente

Ative Client Events para o app na página Realtime apps. Você também pode definir client_events como true pela API do Realtime. A configuração se aplica ao app inteiro. Até que você a ative, o edge do Realtime rejeita eventos de cliente.

Requisitos de eventos de cliente

O edge do Realtime aplica três regras:

O nome começa com client-. Esse prefixo reservado identifica eventos de cliente. Os clientes rejeitam nomes de evento que o omitem.
O canal é privado ou de presença. Um canal público é recusado, e esse é justamente o ponto: a chave do app está na sua página, então qualquer pessoa poderia se inscrever em um canal público e começar a escrever nele. Autorização é o que torna um cliente confiável o suficiente para transmitir, e apenas canais privados e de presença a possuem.
O remetente está inscrito. A conexão já precisa estar no canal em que dispara o evento, de modo que um cliente não pode escrever em uma sala na qual nunca foi admitido.

Se um evento quebrar uma dessas regras, o edge retorna um erro no nível da conexão. Vincule o erro durante o desenvolvimento:

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}")
}

Envio

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()) })
}

O payload opcional pode ser uma string, objeto ou array. trigger retorna true após enviar o frame e false se o canal não estiver inscrito. Para enviar imediatamente após entrar, aguarde bird:subscription_succeeded.

Swift e Kotlin recebem o payload como o valor JSON da respectiva linguagem: Any? codificado com JSONSerialization em Swift, JsonElement em Kotlin.

Recebimento

Vincule o nome que você enviou, no mesmo canal, exatamente como um evento publicado pelo servidor:

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

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

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

A conexão que envia não recebe o próprio evento. Outras conexões que pertencem à mesma pessoa recebem, então filtre essas cópias quando necessário.

Limites de requisições

Cada conexão pode enviar até 10 eventos de cliente por segundo. O mesmo limite se aplica a todas as conexões do app.

Quando uma conexão excede o limite, o edge descarta o evento e reporta um erro sem fechar a conexão. Vincule o evento error da conexão e controle entradas de alta frequência, como movimentação de cursor.

Receber eventos de cliente no seu servidor

Para receber eventos de cliente no seu servidor, inscreva um endpoint no grupo realtime.client_events. O type de cada webhook adiciona o prefixo realtime. ao nome do evento de cliente, então client-typing se torna realtime.client-typing:

Exemplo 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 canais de presença e está ausente para canais privados. Sinais de alto volume, como posições de cursor, produzem um webhook por evento de cliente. Consulte Webhooks do Realtime para o envelope, assinatura e outros grupos.

Próximos passos

Webhooks do Realtime aborda o recebimento de eventos de cliente e atividade de canal no seu próprio endpoint.
Canais de presença dão aos eventos de cliente uma identidade de membro e a lista de membros para renderizá-los.
Publicação de eventos é o caminho do lado do servidor, para tudo em que um cliente não deve ser considerado confiável.

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Explore a funcionalidadeRealtime Siga o percurso de aprendizagemBuild your first integration Guia de implementaçãoSend your first realtime event

Experimente na prática e obtenha um resumo de implementação