Messages

Send, update, delete, and receive messages in a chat room with any number of participants. Users subscribe to messages by registering a listener, and send messages to all users that are subscribed to receive them.

A user can also update or delete a message, all users that are subscribed to the room will be notified of the changes.

JavaScriptReactSwiftKotlin
Kotlin v1.2

val subscription = room.messages.subscribe { messageEvent: MessageEvent ->
    println(messageEvent.message.toString())
}

Copy
Copied!

The following is the structure of a message:

{
  "serial": "01826232498871-001@abcdefghij:001",
  "clientId": "basketLover014",
  "roomId": "basketball-stream",
  "text": "What a shot!",
  "headers": {},
  "metadata": {},
  "createdAt": new Date("2024-06-12T11:37:59.988Z"),
  "action": "message.create",
  "version": "01826232498871-001@abcdefghij:001",
  "timestamp": new Date("2024-06-12T11:37:59.988Z"),
  "operation": {},
}

Copy
Copied!

The following are the properties of a message:

See below for more information on how to apply deterministic global ordering to the chat messages in your application.

JavaScriptKotlin
Kotlin v1.2

subscription.unsubscribe()

Copy
Copied!

JavaScriptReactSwiftKotlin
Kotlin v1.2

room.messages.send(text = "hello")

Copy
Copied!

JavaScriptReactSwiftKotlin
Kotlin v1.2

val originalMessage: Message
val updatedMessage = room.messages.update(
  originalMessage.copy(text = "my updated text"),
  operationDescription = "Message update by user",
)

Copy
Copied!

JavaScriptReactSwiftKotlin
Kotlin v1.2

val myMessageList: List<Messages>
val messagesSubscription = room.messages.subscribe { event ->
  when (event.type) {
    MessageEventType.Created -> println("Received message: ${event.message}")
    MessageEventType.Updated -> myMessageList.find {
      event.message.serial == it.serial && event.message.version > it.version
    }?.let { println("Message updated: ${event.message}") }
    else -> {}
  }
}

Copy
Copied!

See below for more information on how to deterministically apply ordering to update events in your application.

The following is the structure of an updated message:

{
  "serial": "01726232498871-001@abcdefghij:001",
  "clientId": "basketLover014",
  "roomId": "basketball-stream",
  "text": "What a shot! Edit: I meant to say 'What a dunk!'",
  "headers": {},
  "metadata": {},
  "createdAt": new Date("2024-06-12T11:37:59.988Z")S,
  "action": "message.update",
  "version": "01826232498871-001@abcdefghij:001",
  "timestamp": new Date("2024-11-21T15:49:25.425Z"),
  "operation": {
    "clientId": "basketLover014",
    "description": "Message updated by client",
    "metadata": {}
  },
}

Copy
Copied!

The updated message response is identical to the structure of a message, with the following differences:

JavaScriptReactSwiftKotlin
Kotlin v1.2

val messageToDelete: Message
val deletedMessage = room().messages.delete(
  messageToDelete,
  operationDescription = "Message deleted by user",
)

Copy
Copied!

JavaScriptReactSwiftKotlin
Kotlin v1.2

val myMessageList: List<Messages>
val messagesSubscription = room.messages.subscribe { event ->
  when (event.type) {
    MessageEventType.Created -> println("Received message: ${event.message}")
    MessageEventType.Deleted -> myMessageList.find {
      event.message.serial == it.serial && event.message.version > it.version
    }?.let { println("Message deleted: ${event.message}") }
    else -> {}
  }
}

Copy
Copied!

See below for more information on how to deterministically apply ordering to delete events in your application.

The following is the structure of a deleted message:

{
  "serial": "01726232498871-001@abcdefghij:001",
  "clientId": "basketLover014",
  "roomId": "basketball-stream",
  "text": "What a shot!",
  "headers": {},
  "metadata": {},
  "createdAt": new Date("2024-06-12T11:37:59.988Z"),
  "action": "message.delete",
  "version": "01826232498871-001@abcdefghij:001",
  "timestamp": new Date("2024-11-21T15:49:25.425Z"),
  "operation": {
    "clientId": "basketLover014",
    "description": "Message deleted by client",
    "metadata": {}
  },
}

Copy
Copied!

The deleted message response is identical to the structure of a message, with the following differences:

Chat messages and update events are delivered in realtime to clients connected to a particular region in the order in which that region receives them. The order in which a given region receives these events may be different from the “global” order of events, i.e. the true time-based order in which events happened.

Chat messages are uniquely identified by their serial and may have multiple versions as a result of edit and delete operations. Both serial and version are lexicographically sortable strings. This means they can be used to enforce a deterministic global ordering based on string comparison.

If the serial of one message occurs before another when lexicographically sorted, the first message is considered to have occurred before the other. If the serial values are identical, the messages are the same message.

The Message object also has convenience methods before, after and equal which provide the same comparison.

Applying an action to a message produces a new version, which is uniquely identified by the version property. When two message instances share the same serial they represent the same chat message, but they can represent different versions. Lexicographically sorting the two message instances by the version property gives the global order of the message versions: the message instance with a greater version is newer, the message instance with a lower version is older, and if their version is equal then they are the same version.

The Message object also has convenience methods isOlderVersionOf, isNewerVersionOf and isSameVersionAs which provide the same comparison.

Update and Delete events provide the message payload without message reactions. To correctly use message reactions, always use the with() method to apply the event to the message instance.

The Message object has a method with that takes a MessageEvent, automatically compares versions, and returns the newest Message instance. For updates and deletes, if with is called with an event that is older than the message, the message is returned. If it is called with a newer event, the message from the event is returned. For message reaction events, the reactions will be correctly applied to the returned message.

Message.with() also ensures that reactions from existing messages are copied over to the new message instance in the case of UPDATEs or DELETEs.

Example usage to keep a list of messages updated:

JavaScriptReact
Select...

import { MessageEvents, Message } from '@ably/chat';
let myMessageList: Message[];


// For messages (create, update, delete)
room.messages.subscribe((event) => {
  switch (event.type) {
    case MessageEvents.Created:
      myMessageList.push(event.message);
      break;
    case MessageEvents.Updated:
    case MessageEvents.Deleted:
      const idx = myMessageList.findIndex((msg) => msg.serial === event.message.serial);
      if (idx !== -1) {
        myMessageList[idx] = myMessageList[idx].with(event);
      }
      break;
    default:
      break;
  }
});


// And for message reactions
room.messages.reactions.subscribe((event) => {
  const idx = myMessageList.findIndex((msg) => msg.serial === event.summary.messageSerial);
  if (idx !== -1) {
    myMessageList[idx] = myMessageList[idx].with(event);
  }
});

Copy
Copied!