Message

Open in

The Message interface represents a single message in a chat room. Messages are received through the messages.subscribe() method or retrieved via messages.history().

Properties

The Message interface has the following properties:

serialString

The unique identifier of the message.

clientIdString

The client ID of the user who created the message.

textString

The text content of the message.

timestampDate

The timestamp at which the message was created.

metadataMessageMetadata

Extra information attached to the message for features like animations or linking to external resources. Always set; empty object if no metadata was provided.

headersMessageHeaders

Additional information in Ably realtime message extras, usable for features like livestream timestamping or message flagging. Always set; empty object if none provided.

actionChatMessageAction

The action type indicating if the message was created, updated, or deleted.

versionMessageVersion

Information about the current version of this message.

reactionsMessageReactionSummary

The reactions summary for this message.

Apply an event to a message

message.with(event: ChatMessageEvent | Message | MessageReactionSummaryEvent): Message

Creates a new message instance with an event applied. This is useful for updating a local message state when receiving update or delete events. Returns the same instance if the event would be a no-op (e.g., applying an older version).

JavaScript

const updatedMessage = message.with(updateEvent);

Parameters

The with() method takes the following parameters:

eventrequiredMessage or ChatMessageEvent or MessageReactionSummaryEvent

The event to apply to the message.

Returns

Message

Returns a new message instance with the event applied, or the same instance if the event would be a no-op.

Copy a message

message.copy(params?: MessageCopyParams): Message

Creates a copy of the message with specified fields replaced.

JavaScript

const messageCopy = message.copy({ text: 'New text' });

Parameters

The copy() method takes the following parameters:

paramsoptionalMessageCopyParams

The fields to replace in the copy.

Returns

Message

Returns a new message instance with the specified fields replaced.

Example

JavaScript

import { ChatMessageAction } from '@ably/chat';

// Subscribe to messages and handle different actions
room.messages.subscribe((event) => {
  const message = event.message;

  console.log('Serial:', message.serial);
  console.log('From:', message.clientId);
  console.log('Text:', message.text);
  console.log('Sent at:', message.timestamp);
  console.log('Action:', message.action);

  // Check if message has metadata
  if (Object.keys(message.metadata).length > 0) {
    console.log('Metadata:', message.metadata);
  }

  // Check message version for updates or deletions
  if (message.action === ChatMessageAction.MessageUpdate) {
    console.log('Updated by:', message.version.clientId);
    console.log('Update reason:', message.version.description);
  }

  if (message.action === ChatMessageAction.MessageDelete) {
    console.log('Deleted by:', message.version.clientId);
    console.log('Delete reason:', message.version.description);
  }

  // Check reaction summary
  for (const [name, summary] of Object.entries(message.reactions.distinct)) {
    console.log(`${name}: ${summary.total} reactions from ${summary.clientIds.length} clients`);
  }
});