Chat Events

Events are how your app learns that something happened in chat: a new message, someone typing, the connection dropping. You listen for the ones your UI cares about and update the screen when they fire. This page lists all 15 (from ChatEventMap in @livqeno/chat).

Where this fits: your app has connected with a chat token (see the Chat quickstart). Events only fire while connected. For what happened before that, load Message history.

These are client events, in your app. To tell your backend about chat activity (for push notifications, say), use Webhooks instead.

Which events does my UI need?

Listen to an event

In your app:

const unsubscribe = chat.on('message', (message) => {
  render(message.senderId, message.text);
});
 
unsubscribe();      // idempotent — calling it twice is safe

• chat.on() returns a function. Call it to stop listening, for example when the chat screen closes. Forgetting this leaks listeners, and you'll see each message rendered twice after the screen opens again.
• chat.off() also works, if you prefer it.
• This is different from room.on() in @livqeno/rtc, which returns the room.

Messages

Why you get your own messages back:

• sendMessage() finishing means the message is saved.
• The message event means it was delivered.
• Draw messages from the event. Then everyone, including the sender, sees the same order.

Reactions

Adding the same reaction twice is harmless. See Reactions.

Typing, presence, and read receipts

These are short-lived signals about people, not about messages.

• None of these are saved, except the read position.
• A user goes offline when their presence expires. A crashed browser shows offline within 45 seconds.
• Don't rely on a read event for your own read marks on this device; use the value that markAsRead() returns. Marks made on the same user's other devices do arrive as read events, and chat.inbox uses them to clear unread counts.

Moderation

See Moderation.

Connection

Phones lose signal and laptops sleep. These events let you show the user what's going on, while the SDK reconnects for you.

What happens when the network drops:

1. The state changes to reconnecting, and reconnecting fires with attempt 1, 2, 3…. (disconnected does not fire, because the SDK is still trying.)
2. When the network is back, reconnected fires.
3. The SDK fetches what was missed. Those messages arrive as normal message events, followed by any missed edits, deletes, reactions and moderation events, through their normal events.
4. recovered fires when catch-up is done.

About recovered: missed messages already came through message. Then check:

• summary.gap: some history was skipped. Reload the view.
• summary.errors: rooms that couldn't catch up. They retry on the next reconnect.
• summary.events: missed edits, deletes, reactions and moderation events applied.
• summary.resynced: rooms whose history was re-read (a resync fired for each).

reconnecting gives the attempt number, so you can show "Still trying (3)". RTC's version doesn't.

Errors

Listen for error in every app. A refused action (like a send without permission) is reported here, not as a missing message.

import { isLivqenoChatError } from '@livqeno/chat';
 
chat.on('error', (error) => {
  if (!isLivqenoChatError(error)) return;
  if (error.code === 'TOKEN_EXPIRED') refreshToken();
  if (error.code === 'RATE_LIMITED') backOff(error.retryAfterSeconds);
});

If a newer server sends an error code your client doesn't know, you still get a LivqenoChatError with that code. Older clients keep working.

All codes are in Errors.

Error subclasses

Every chat error is really a LivqenoChatError underneath, so checking instanceof LivqenoChatError (or calling isLivqenoChatError()) always catches all of them, no matter which kind it is. If you want to handle just one kind of error, use one of these more specific classes instead of checking error.code yourself:

There's also a second set of subclasses just for moderation — LivqenoModerationError, LivqenoSlowModeError, LivqenoMessageBlockedError, and LivqenoRateLimitError. See Moderation.

These map onto the wire

Each event comes from a WebSocket frame. For example, typing combines the typing.started and typing.stopped frames. Building a client in another language? See WebSocket protocol.

Other platforms

React gives you hooks that listen for you. Flutter gives you one stream per event type.

const { messages, send, loadMore, hasMore } = useMessages();
const { typingUsers, onInput } = useTyping();
const presence = usePresence();
const state = useChatConnectionState();
const error = useChatError();

chat.messages.listen((m) { });
chat.messageUpdates.listen((m) { });
chat.messageDeletions.listen((id) { });
chat.typing.listen((e) { });
chat.presence.listen((p) { });
chat.reactions.listen((e) { });
chat.readReceipts.listen((r) { });
chat.connectionStateChanges.listen((s) { });
chat.errors.listen((e) { });

Common mistakes

Next steps

• Messages · WebSocket protocol
• Event catalogue: every event across RTC, Chat, and webhooks.
• RTC events: the call-side equivalent.