What's optimistic and what isn't

An optimistic action shows its result before the server confirms it. In stream-chat, the message operations, poll votes and drafts are optimistic, and conversation actions aren't. This page lists which is which, and what happens when the server answers or a request fails. Use it to decide where your UI needs a pending state of its own: for the actions whose result appears only when the server answers.

Optimistic actions

The message operations change the message list before the request goes out: sending, retrying, editing and deleting a message, and adding or removing a reaction. Optimistic updates lists what each one shows at once and what's undone when its request fails. The composer's MessageComposer.send() and MessageComposer.update() go through them, so they behave the same way. The composer also clears itself before the request goes out. The SDK's message actions go through them too.

These actions are optimistic too:

Poll votes are sent one at a time, in the order they were made. The server's vote counts are shown once the events of all pending votes have arrived. If an event is lost, the client catches up after 3 seconds. When the user has already used all their votes, Poll.castVote() changes nothing and publishes a validation:poll:castVote:limit notification.

With offline support, an operation that fails because the device is offline waits in the offline queue and is sent after the next reconnect. An edit, a delete or a reaction that waits there isn't failed but pending, so its local change stays. A send that waits there is still marked failed, because retrying is how the user gets it out before the reconnect. A draft that waits there stays in the composer, as it does after any failure.

How each operation works is on Message operations.

Conversation actions

Actions on a channel, a membership or a user aren't optimistic, and neither is pinning a message. Their effect appears when the server's event or response arrives, not when the call is made.

Actions that wait for the server

If such a request fails, nothing has changed locally, so there is nothing to undo. While the device is offline, these actions fail and aren't kept for later. How read state and unread counts change is on Read state and unread counts.

The local-only exception

Channel.markReadLocally() changes local state and sends nothing. It sets the current user's unread count in the channel to zero by dispatching a message.read_locally event, which is handled like a message.read event.

It's for busy channels such as livestreams, where read events are best turned off, so the server doesn't count unread messages. With read events off and channel.readEvents.localUnreadCountEnabled set in client.config (see Configuration), the client counts unread messages itself. Channel.markReadViaReporter() then marks the channel read locally, by calling Channel.markReadLocally(). Automatic marking read goes through it too, and so does the SDK's own marking read. A registered markReadRequest handler takes precedence: it runs instead.

Showing a pending state

A UI that should react at once shows a pending state of its own: from the call until the event arrives, or until the request fails. Here a menu item shows "Archiving..." until the membership changes:

const setArchiving = (archiving: boolean) => {
  // Update your UI here, for example disable the menu item.
  console.log(archiving ? "Archiving..." : "Done");
};

const archiveChannel = async () => {
  setArchiving(true);

  const stop = channel.state.subscribeWithSelector(
    ({ membership }) => ({ archivedAt: membership.archived_at }),
    ({ archivedAt }, previous) => {
      // The first call reports the current value. Wait for the event to change it.
      if (!previous || !archivedAt) return;
      setArchiving(false);
      stop();
    },
  );

  try {
    await channel.archive();
  } catch (error) {
    setArchiving(false);
    stop();
    throw error;
  }
};

Raw API calls

Some calls send the request and nothing else: Channel.sendMessage(), client.sendReaction() and Channel.sendReaction(), client.updateMessage() and client.deleteMessage(). They don't change local state, before or after the request:

// Nothing appears in the list until the server's message.new event arrives.
await channel.sendMessage({ message: { text: "Hello" } });

In a watched channel, the server's events still reach the list: message.new, message.updated, message.deleted and the reaction events. But nothing is shown before them, and a failed request leaves no failed message to retry. Use them for scripts, or when you keep the local state yourself, and use channel.messageOperations or thread.messageOperations everywhere else.

Used in

• Sending, editing and deleting
• Reactions
• Channel lists
• Read state, unread and receipts
• Flagging, muting, blocking and bans