Événements client

Un événement client voyage directement d'un client abonné aux autres sur le même canal. Votre backend n'en reçoit une copie que si vous l'abonnez au groupe de webhooks client-events.

Utilisez les événements client pour les signaux éphémères tels que les indicateurs de saisie, les positions de curseur ou les battements d'activité. Ils évitent un aller-retour par votre API.

N'utilisez pas les événements client comme état faisant autorité. Le edge Realtime ne valide pas leur contenu, les destinataires ne peuvent donc pas s'y fier. Envoyez les messages de chat stockés, les changements d'état et les actions sensibles aux permissions via votre serveur avec Publication d'événements.

Activer les événements client

Activez Client Events pour l'application sur la page Realtime apps. Vous pouvez aussi définir client_events à true via l'API Realtime. Le paramètre s'applique à l'ensemble de l'application. Tant que vous ne l'activez pas, le edge Realtime rejette les événements client.

Exigences des événements client

Le edge Realtime applique trois règles :

Le nom commence par client-. Ce préfixe réservé identifie les événements client. Les clients rejettent les noms d'événements qui l'omettent.
Le canal est privé ou de présence. Un canal public est refusé, et c'est précisément le but : la clé de l'application est présente dans votre page, n'importe qui pourrait donc s'abonner à un canal public et y écrire. L'autorisation est ce qui rend un client suffisamment fiable pour diffuser, et seuls les canaux privés et de présence en disposent.
L'expéditeur est abonné. La connexion doit déjà être présente sur le canal dans lequel elle déclenche l'événement, un client ne peut donc pas écrire dans un salon où il n'a jamais été admis.

Si un événement enfreint l'une de ces règles, le edge renvoie une erreur au niveau de la connexion. Bindez l'erreur pendant le développement :

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

Envoi

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

Le payload optionnel peut être une chaîne, un objet ou un tableau. trigger renvoie true après l'envoi de la trame et false si le canal n'est pas souscrit. Pour envoyer immédiatement après avoir rejoint le canal, attendez bird:subscription_succeeded.

Swift et Kotlin acceptent le payload sous la forme de la valeur JSON de leur langage : Any? encodé avec JSONSerialization en Swift, JsonElement en Kotlin.

Réception

Bindez le nom que vous avez envoyé, sur le même canal, exactement comme un événement publié par le serveur :

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

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

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

La connexion émettrice ne reçoit pas son propre événement. Les autres connexions appartenant à la même personne le reçoivent, filtrez donc ces copies si nécessaire.

Limites de débit

Chaque connexion peut envoyer jusqu'à 10 événements client par seconde. La même limite s'applique à chaque connexion de l'application.

Lorsqu'une connexion dépasse la limite, le edge abandonne l'événement et signale une erreur sans fermer la connexion. Bindez l'événement error de la connexion et limitez les entrées à haute fréquence comme les mouvements de curseur.

Recevoir les événements client sur votre serveur

Pour recevoir les événements client sur votre serveur, abonnez un endpoint au groupe realtime.client_events. Le type de chaque webhook ajoute le préfixe realtime. au nom de l'événement client, donc client-typing devient realtime.client-typing :

Exemple de code

{
  "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 apparaît pour les canaux de présence et est absent pour les canaux privés. Les signaux à haut volume comme les positions de curseur produisent un webhook par événement client. Consultez Webhooks Realtime pour l'enveloppe, la signature et les autres groupes.

Étapes suivantes

Webhooks Realtime couvre la réception des événements client et de l'activité des canaux sur votre propre endpoint.
Canaux de présence donnent aux événements client une identité de membre, ainsi que la liste des membres pour les afficher.
Publication d'événements est le chemin côté serveur, pour tout ce qui ne devrait pas être confié à un client.

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Explorer la fonctionnalitéRealtime Suivre le parcours d'apprentissageBuild your first integration Guide d'implémentationSend your first realtime event

Essayez la pratique et obtenez un guide d'implémentation