Client events

Een client event gaat rechtstreeks van één geabonneerde client naar de andere clients op hetzelfde channel. Je backend ontvangt alleen een kopie als je het abonneert op de client-events webhook-groep.

Gebruik client events voor kortlevende signalen zoals typindicatoren, cursorposities of activiteitsheartbeats. Ze vermijden een retour via je API.

Gebruik client events niet als gezaghebbende state. De Realtime edge valideert hun payloads niet, dus ontvangers kunnen de inhoud niet vertrouwen. Stuur opgeslagen chatberichten, statuswijzigingen en rechtensgevoelige acties via je server met Publishing events.

Client events inschakelen

Schakel Client Events in voor de app op de pagina Realtime apps. Je kunt ook client_events op true zetten via de Realtime API. De instelling geldt voor de hele app. Zolang je het niet inschakelt, weigert de Realtime edge client events.

Vereisten voor client events

De Realtime edge hanteert drie regels:

De naam begint met client-. Dit gereserveerde voorvoegsel identificeert client events. Clients weigeren eventnamen zonder dit voorvoegsel.
Het channel is private of presence. Een public channel wordt geweigerd, en dat is precies de bedoeling: de app key staat in je pagina, dus iedereen kan zich abonneren op een public channel en erin schrijven. Autorisatie maakt een client betrouwbaar genoeg om te broadcasten, en alleen private en presence channels hebben dat.
De afzender is geabonneerd. De verbinding moet al op het channel zitten waarnaar het triggert, zodat een client niet kan schrijven naar een ruimte waar het nooit is toegelaten.

Als een event een van deze regels overtreedt, retourneert de edge een fout op verbindingsniveau. Bind de fout tijdens het ontwikkelen:

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

Verzenden

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

De optionele payload kan een string, object of array zijn. trigger retourneert true na het verzenden van het frame en false als het channel niet geabonneerd is. Om direct na het joinen te verzenden, wacht je op bird:subscription_succeeded.

Swift en Kotlin nemen de payload als de JSON-waarde van hun taal: Any? gecodeerd met JSONSerialization in Swift, JsonElement in Kotlin.

Ontvangen

Bind de naam die je hebt gestuurd, op hetzelfde channel, precies zoals een door de server gepublisht event:

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

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

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

De verzendende verbinding ontvangt het eigen event niet. Andere verbindingen van dezelfde persoon ontvangen het wel, dus filter die kopieën waar nodig.

Limieten

Elke verbinding kan maximaal 10 client events per seconde versturen. Dezelfde limiet geldt voor elke verbinding op de app.

Wanneer een verbinding de limiet overschrijdt, laat de edge het event vallen en rapporteert een fout zonder de verbinding te sluiten. Bind het error-event van de verbinding en throttle hoogfrequente invoer zoals cursorbewegingen.

Client events ontvangen op je server

Om client events op je server te ontvangen, abonneer je een endpoint op de realtime.client_events-groep. De type van elke webhook voegt het realtime.-voorvoegsel toe aan de naam van het client event, dus client-typing wordt realtime.client-typing:

Codevoorbeeld

{
  "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 verschijnt bij presence channels en ontbreekt bij private channels. Hoogfrequente signalen zoals cursorposities produceren één webhook per client event. Zie Realtime webhooks voor het foutantwoord, de handtekening en andere groepen.

Volgende stappen

Realtime webhooks behandelt het ontvangen van client events en channelactiviteit op je eigen endpoint.
Presence channels geven client events een ledenidentiteit en de ledenlijst om ze tegen weer te geven.
Publishing events is het server-side pad, voor alles waarvoor een client niet vertrouwd mag worden.

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Ontdek de mogelijkheidRealtime Volg het leerpadBuild your first integration ImplementatiegidsSend your first realtime event

Probeer de oefening en ontvang een implementatieoverzicht