Client-Events

Ein Client-Event wird direkt von einem abonnierten Client an die anderen auf demselben Channel übertragen. Ihr Backend erhält eine Kopie nur dann, wenn Sie es für die Webhook-Gruppe „client-events

Verwenden Sie Client-Events für kurzlebige Signale wie Tippindikatoren, Cursorpositionen oder Aktivitäts-Heartbeats. Sie vermeiden einen Roundtrip über Ihren API.

Verwenden Sie Client-Events nicht als verbindlichen Zustand. Die Realtime-Edge validiert deren Payloads nicht, sodass Empfänger dem Inhalt nicht vertrauen können. Senden Sie gespeicherte Chat-Nachrichten, Zustandsänderungen und berechtigungsrelevante Aktionen über Ihren Server mit Events veröffentlichen.

Client-Events aktivieren

Aktivieren Sie Client Events für die App auf der Seite Realtime apps. Sie können auch client_events über die Realtime-API auf true setzen. Die Einstellung gilt für die gesamte App. Bis Sie sie aktivieren, lehnt die Realtime-Edge Client-Events ab.

Anforderungen an Client-Events

Die Realtime-Edge erzwingt drei Regeln:

Der Name beginnt mit client-. Dieses reservierte Präfix kennzeichnet Client-Events. Clients lehnen Event-Namen ab, die es weglassen.
Der Channel ist private oder presence. Ein öffentlicher Channel wird abgelehnt, und genau das ist beabsichtigt: Der App-Key ist in Ihrer Seite enthalten, sodass jeder einen öffentlichen Channel abonnieren und darauf schreiben könnte. Autorisierung macht einen Client vertrauenswürdig genug zum Senden, und nur private- und presence-Channels haben sie.
Der Sender ist abonniert. Die Verbindung muss bereits auf dem Channel sein, in den sie auslöst. Ein Client kann also nicht in einen Raum schreiben, zu dem er nie zugelassen wurde.

Wenn ein Event eine dieser Regeln verletzt, gibt die Edge einen Fehler auf Verbindungsebene zurück. Binden Sie den Fehler während der Entwicklung:

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

Senden

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

Der optionale Payload kann ein String, ein Objekt oder ein Array sein. trigger gibt true nach dem Senden des Frames zurück und false, wenn der Channel nicht abonniert ist. Um sofort nach dem Beitreten zu senden, warten Sie auf bird:subscription_succeeded.

Swift und Kotlin nehmen den Payload als JSON-Wert ihrer Sprache entgegen: Any?, kodiert mit JSONSerialization in Swift, JsonElement in Kotlin.

Empfangen

Binden Sie den gesendeten Namen auf demselben Channel, genau wie ein vom Server veröffentlichtes Event:

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

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

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

Die sendende Verbindung empfängt ihr eigenes Event nicht. Andere Verbindungen derselben Person empfangen es, filtern Sie diese Kopien also bei Bedarf.

Ratenlimits

Jede Verbindung kann bis zu 10 Client-Events pro Sekunde senden. Dasselbe Limit gilt für jede Verbindung der App.

Wenn eine Verbindung das Limit überschreitet, verwirft die Edge das Event und meldet einen Fehler, ohne die Verbindung zu schließen. Binden Sie das error-Event der Verbindung und drosseln Sie hochfrequente Eingaben wie Cursorbewegungen.

Client-Events auf Ihrem Server empfangen

Um Client-Events auf Ihrem Server zu empfangen, abonnieren Sie einen Endpunkt für die realtime.client_events-Gruppe. Das type jedes Webhooks fügt dem Client-Event-Namen das Präfix realtime. hinzu, sodass client-typing zu realtime.client-typing wird:

Codebeispiel

{
  "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 erscheint bei Presence-Channels und fehlt bei Private-Channels. Hochfrequente Signale wie Cursorpositionen erzeugen einen Webhook pro Client-Event. Siehe Realtime-Webhooks für die Envelope-Struktur, Signatur und weitere Gruppen.

Nächste Schritte

Realtime-Webhooks behandelt den Empfang von Client-Events und Channel-Aktivität auf Ihrem eigenen Endpunkt.
Presence-Channels geben Client-Events eine Mitgliedsidentität und die Mitgliederliste, gegen die Sie sie darstellen können.
Events veröffentlichen ist der serverseitige Weg für alles, womit ein Client nicht betraut werden sollte.

Related resources

Continue with the documentation, guides and examples for this topic. Resources are in English.

Explore the capabilityRealtime Follow the learning pathBuild your first integration Implementation guideSend your first realtime event

Try the practice and get an implementation brief