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 messages

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:

Message structure

The following is the structure of a message:

JSON

The following are the properties of a message:

PropertyDescriptionType
serialAn Ably-generated ID used to uniquely identify the message. By comparing it to others it provides a deterministic global ordering of messages.String
clientIdThe client identifier of the user that created the message.String
roomIdThe name of the room the message was created in.String
textThe message contents.String
headersOptional 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
metadataOptional 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
createdAtThe time the message was created.Date
actionThe latest action performed on this message, such as message.create, message.update or message.delete.String
versionAn 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
timestampThe time the action was performed. It will be identical to createdAt if the action is a message.create.Date
operationFor 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.

Unsubscribe from messages

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

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

JavaScript

Send a message

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

Update a message

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:

Filter for updates

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:

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

Message update structure

The following is the structure of an updated message:

JSON

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

PropertyDescription
actionSet to message.update.
versionSet to the serial of the update action.
timestampSet to the time the message was updated.
operationSet to the details the actioning client provided in the request.

Delete a message

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:

Filter for deletes

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:

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

Message deletion structure

The following is the structure of a deleted message:

JSON

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

PropertyDescription
actionSet to message.delete.
versionSet to the serial of the deletion action.
timestampSet to the time the message was deleted.
operationSet to the details the actioning client provided in the request.

Ordering chat message events

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.

Ordering new messages

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.

Ordering updates and deletes

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.

Keep messages updated using with()

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:

Select...