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.

Subscribe to receive messages in a room by registering a listener. Use the messages.subscribe() method in a room to receive all messages that are sent to it:

Select...
const {unsubscribe} = room.messages.subscribe((event) => { console.log(event.message); });
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": {}, }
Copied!

The following are the properties of a message:

Property Description Type
serial An Ably-generated ID used to uniquely identify the message. By comparing it to others it provides a deterministic global ordering of messages. String
clientId The client identifier of the user that created the message. String
roomId The name of the room the message was created in. String
text The message contents. String
headers Optional headers for adding additional information to a message, such as the relative timestamp of a livestream video, or flagging a message as important. Do not use the headers for authoritative information. There is no server-side validation. When reading headers treat them like user input. Object
metadata Optional additional metadata about the message, such as animations, effects or links to other resources such as images. This information is not read by Ably. Do not use metadata for authoritative information. There is no server-side validation. When reading metadata treat it like user input. Object
createdAt The time the message was created. Date
action The latest action performed on this message, such as message.create, message.update or message.delete. String
version An Ably-generated ID used to uniquely identify the version of the message. It provides a deterministic global ordering of message versions. The version is identical to serial if the action is message.create. String
timestamp The time the action was performed. It will be identical to createdAt if the action is a message.create. Date
operation For updates and deletions, this provides additional details about the action. It may contain the following properties: Object or undefined
clientId: The client identifier of the user associated with the action. String or undefined
description: Optional description for the action. String or undefined
metadata: Optional additional metadata about the action. Object or undefined

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

Use the unsubscribe() function returned in the subscribe() response to remove a chat message listener:

Select...
// Initial subscription const { unsubscribe } = room.messages.subscribe((event) => console.log(event.message)); // To remove the listener unsubscribe();
Copied!

Use the messages.unsubscribeAll() method to deregister all chat message listeners in a room:

Select...
await room.messages.unsubscribeAll();
Copied!

Use the messages.send() method to send a message in a chat room. All users that are subscribed to messages on that room will receive it:

Select...
await room.messages.send({text: 'hello'});
Copied!

Use the messages.update() method to update a message in a chat room. All users that are subscribed to messages on that room will receive the update:

Select...
import { Message } from '@ably/chat'; const messageToUpdate: Message await room.messages.update(messageToUpdate, { text: "my updated text" }, { description: "Message update by user" });
Copied!

Use the messages.subscribe() method to receive messages in a room. To filter for updated messages, provide a listener that checks the type property of the message event:

Select...
import { MessageEvents } from '@ably/chat'; const {unsubscribe} = room.messages.subscribe((event) => { switch (event.type) { case MessageEvents.Created: console.log('Received message: ', event.message); break; case MessageEvents.Updated: const existing = myMessageList.find(event.message); if (existing && event.message.versionBefore(existing)) { // We've already received a more recent update, so this one can be discarded. return; } console.log('Message updated: ', event.message); break; default: break; } });
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": {} }, }
Copied!

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

Property Description
action Set to message.update.
version Set to the serial of the update action.
timestamp Set to the time the message was updated.
operation Set to the details the actioning client provided in the request.

Use the messages.delete() method to delete a message in a chat room. All users that are subscribed to messages on that room will receive the deletion:

Select...
import { Message } from '@ably/chat'; const messageToDelete: Message await room.messages.delete(messageToDelete, { description: 'Message deleted by user' });
Copied!

Use the messages.subscribe() method to receive messages in a room. To filter for deleted messages, provide a listener that checks the type property of the message event:

Select...
import { MessageEvents } from '@ably/chat'; const {unsubscribe} = room.messages.subscribe((event) => { switch (event.type) { case MessageEvents.Created: console.log('Received message: ', event.message); break; case MessageEvents.Deleted: const existing = myMessageList.find(event.message); if (existing && event.message.versionBefore(existing)) { // We've already received a more recent update, so this one can be discarded. return; } console.log('Message deleted: ', event.message); break; default: break; } });
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": {} }, }
Copied!

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

Property Description
action Set to message.delete.
version Set to the serial of the deletion action.
timestamp Set to the time the message was deleted.
operation Set to the details the actioning client provided in the request.

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 versionBefore, versionAfter and versionEqual which provide the same comparison.

Update and Delete events provide the full message payload, so may be used to replace the entire earlier version of the message.

Subscribe to messages
v2.0