Message Format and Metadata

Messages contain the data that a client is communicating, such as the contents of a chat message. Clients publish messages on channels, and these messages are received by clients that have subscribed to them.

Message properties

The following are the properties of a message:

Property	Description
name	The name of the message
data	The contents of the message. Also known as the message payload
id	Each message sent through Ably is assigned a unique ID, unless you provide your own ID, which serves as the idempotency key
clientId	The ID of the client that published the message
connectionId	The ID of the connection used to publish the message
timestamp	The timestamp of when the message was first received by Ably, as milliseconds since the Unix epoch
extras	A JSON object of arbitrary key-value pairs that may contain metadata, and/or ancillary payloads. Valid payloads include those related to Push Notifications, deltas and headers
encoding	This is typically empty, as all messages received from Ably are automatically decoded client-side using this value

Accessing message properties

When you receive a message, you can access all its properties:

Message data types

The data property of a message can contain different types of data:

String data

JSON objects

Binary data

Message extras

The extras field allows you to include additional metadata with your messages:

Push notification extras

When publishing push notifications, use the extras field to include push-specific data:

Message idempotency

You can provide your own message ID to ensure idempotent publishing. If you publish a message with the same ID twice, only one message will be delivered:

This is useful for ensuring messages aren’t duplicated during retries or network issues.

Message encoding

Ably automatically handles encoding and decoding of messages:

• JSON objects are automatically serialized and deserialized
• Binary data is properly encoded
• String data is UTF-8 encoded

The encoding property tells you what transformations were applied to the message data. In most cases, this will be empty as the SDK handles decoding automatically.

Message size limits

Messages have the following size limits:

• Maximum message size: 65,536 bytes (64 KiB)
• Messages are counted in 5 KiB chunks for billing purposes

Next steps

• Learn how to publish messages
• Learn how to subscribe to messages
• Explore message history
• Understand message delivery tracking