Message operations

Every channel and every thread has messageOperations: the operations that send, retry, edit and delete a message, and add or remove a reaction. Each one changes the message list first, then sends the request, and settles the list when the server answers. The composer's MessageComposer.send() and MessageComposer.update() go through them.

const retryMessage = async (messageId: string) => {
  const localMessage = channel.messagePaginator.getItem(messageId);
  if (localMessage?.status !== "failed") return;

  try {
    await channel.messageOperations.retry({ localMessage });
  } catch {
    // The message is marked failed again, ready for another retry.
  }
};

Unlike the composer's MessageComposer.send(), the operations reject when the request fails. The list is already settled by then, so the rejection only tells the caller.

The SDK's message actions call these operations through useMessageOperations(): retrying a failed message, deleting a message, and adding or removing a reaction. They use the open thread's operations for a reply loaded in the thread, and the channel's otherwise. Deleting a message that failed to send removes it from the list without a request, because the server never had it.

Message statuses

A message on its way has one of three statuses in message.status:

• sending: shown in the list, the request is on its way.
• received: the server's copy is in the list.
• failed: the request failed. message.error holds the error. Retry a failed send with MessageOperations.retry({ localMessage }). A failed edit is saved by editing again with MessageOperations.update(), not by retrying.

These statuses describe the request, and don't match the statuses a UI shows on the user's own messages: sending, sent, delivered and read. MessageStatus shows a received message as sent until another member has it, and takes delivered and read from the other members' read state, as Read state, unread and receipts explains.

Each channel and each thread keeps the request of a failed send in memory for five minutes, for up to 100 messages, so a retry sends exactly what failed. After that, or after the app restarts, a retry rebuilds the request from the message. Both limits can be changed under messageOperations in Configuration.

If the server rejects a send because the message already exists, the earlier attempt did arrive. The message is marked received rather than failed, although the call still rejects.

The operations and what they take:

A thread sends its replies through thread.messageOperations. The requests go to the thread's channel with the thread's id as parent_id, and the reply lands in the thread's message list. channel.messageOperations and thread.messageOperations are reached through their channel and thread; the class isn't exported from stream-chat.

Calls such as Channel.sendMessage() or client.updateMessage() send the request and nothing else. They don't touch the list, as Raw API calls explains.

Optimistic updates

The operations change the list before the request goes out, and the server's copy replaces the local one when it answers. When a request fails, a send is marked failed, an edit is kept and marked failed, and a delete or a reaction is undone. Conversation actions, such as marking a channel read or archiving it, work the other way: their effect appears when the server's event arrives. What's optimistic and what isn't lists every action and what happens to it.

Offline

With offline support, every operation on this page that fails because the device is offline is kept as a pending task in the offline database, and sent after the next reconnect, in the order the operations were made. A request the server refuses for good, for example for missing permissions, isn't kept.

• A send is still marked failed, so the user can retry it, and the pending task sends it after the reconnect.
• An edit, a delete or a reaction isn't failed but pending: its change stays in the list until the pending task has been sent.

The operation rejects in both cases, as for any failed request.

Customizing requests

To change how a request is made, register a request handler in client.config. The operation then calls your handler instead of making the request itself, and hands it the default request, so the handler can still send the usual way:

import { StreamChat } from "stream-chat";
import type { OperationRequestFn } from "stream-chat";

const client = StreamChat.getInstance("YOUR_API_KEY");

const sendMessageRequest: OperationRequestFn<"send"> = (
  params,
  defaultRequest,
) =>
  defaultRequest({
    ...params,
    options: { ...params.options, skip_push: true },
  });

client.config.set({ channel: { requestHandlers: { sendMessageRequest } } });

updateMessageRequest and deleteMessageRequest change the options of an edit or a delete the same way.

Handlers are registered for the client and apply to every channel, the ones that exist and the ones created later. To treat channels differently, branch inside the handler, for example on params.localMessage.cid. There is no request function for a single call: every call goes through the registered handler.

The optimistic update happens before the handler runs, and settling the list happens after it, whatever the handler does.

Request handlers

In send and retry, message is the request body and localMessage the copy in the list. The message the handler resolves with is the server's copy, and it replaces the local one.

markReadRequest has no default request. To mark read the usual way, call Channel.markRead(options) in it. A direct Channel.markRead() call doesn't go through the handler. Marking read is explained on Read state and unread counts.

Wrapping the default request

The default request is the one the operation would make without a handler, and it's the second argument of every message handler. Call it to send the usual way, with the parameters as given or changed. Leave it out to send somewhere else:

import { StreamChat } from "stream-chat";
import type { OperationRequestFn } from "stream-chat";

const client = StreamChat.getInstance("YOUR_API_KEY");

const sendMessageRequest: OperationRequestFn<"send"> = async (
  params,
  defaultRequest,
) => {
  if (!params.localMessage.cid.startsWith("support:")) {
    return defaultRequest(params);
  }

  const response = await fetch("https://api.example.com/support/messages", {
    body: JSON.stringify(params.message),
    headers: { "Content-Type": "application/json" },
    method: "POST",
  });
  const { message } = await response.json();

  return { message };
};

client.config.set({ channel: { requestHandlers: { sendMessageRequest } } });

Here, messages in support channels go through the app's backend, which sends them to Stream and returns the server's copy. Every other channel sends the usual way.

A handler replaces the default request, so a request it sends some other way isn't kept as a pending task while the device is offline.

Threads use their channel's handlers

A thread reply is sent, retried, edited and deleted through the handlers registered under channel. The thread key takes one handler of its own, markReadRequest, which runs when a thread is marked read. It receives { thread, options }, where options already carries the thread's id, and resolves to null when nothing was sent:

import { AppState } from "react-native";
import { StreamChat } from "stream-chat";
import type { CustomThreadMarkReadRequestFn } from "stream-chat";

const client = StreamChat.getInstance("YOUR_API_KEY");

const markReadRequest: CustomThreadMarkReadRequestFn = async ({
  thread,
  options,
}) => {
  // Keep the thread unread while the app is in the background.
  if (AppState.currentState !== "active") return null;

  return thread.channel.markRead(options);
};

client.config.set({ thread: { requestHandlers: { markReadRequest } } });

Pitfalls

• Resolve with the server's message. A send handler that resolves without a message leaves the local copy as sending until the server's message.new event replaces it.
• Retrying a failed edit. MessageOperations.retry() sends the edited message as a new one. The server rejects it because the message exists, and the list then shows the edit as received, although the server kept the old text. Load the message into a composer and call MessageComposer.update() again.
• Options of an edit. An edit sends only skip_enrich_url and skip_push of its options, the ones MessageOperations.update() was called with or the ones an updateMessageRequest handler passes to the default request. The other options are dropped.
• Raw calls skip all of this. Channel.sendMessage() and the like neither show the message first nor mark it failed.

Used in

• Sending, editing and deleting
• Reactions
• Message actions
• Sending with pending uploads