Matter Cluster 151 — Messages Cluster

Cluster Identity

Revision history

Shadow Path Format

Cluster 151 values in the device shadow use this format:

endpoint_id / 151 / attribute_id

Example:

{
  "1/151/0": []
}

Cluster 151 Features

The FeatureMap attribute (1/151/65532) is a bitmap. Each bit set means the device implements that feature and the attributes and commands that depend on it.

Example: FeatureMap = 0 means no optional feature is enabled; 15 means every feature listed above is enabled.

Data Types

FutureMessagePreferenceEnum

A display device may include this preference in the MessageComplete event as a hint to clients about how to handle future similar messages.

MessagePriorityEnum

Priority should be used to decide which messages to show when the number of eligible messages is larger than the device's capacity to present them.

MessageControlBitmap (bitmap)

This data type is derived from map16, and indicates control information related to a message.

MessageResponseOptionStruct (struct)

This represents a possible response to a message.

MessageStruct (struct) — fabric-scoped

This represents a single message.

Cluster 151 Attributes

Cluster 151 defines 2 attributes plus the global attributes. Conformance: M mandatory, O optional, a feature code means "mandatory when that feature is present", square brackets mean "optional when …".

Global attributes

Attribute Details

Attribute 0 / 0x0000 — Messages

Path example:

1/151/0

Indicates a list of queued messages. In addition to filtering based upon fabric, to preserve user privacy, the server may further limit the set of messages returned in a read request. At minimum, the server returns to a client those messages that the client itself created/submitted.

Each entry is a MessageStruct (see Data Types).

Example:

{
  "1/151/0": []
}

Attribute 1 / 0x0001 — ActiveMessageIDs

Path example:

1/151/1

No condensed specification text is available for ActiveMessageIDs; use the type, conformance and constraint below together with the cluster description above.

Example:

{
  "1/151/1": []
}

Cluster 151 Commands

Cluster 151 has 2 client-to-server commands and 0 responses.

AcceptedCommandList

The AcceptedCommandList attribute lists the command IDs the endpoint actually implements:

endpoint_id / 151 / 65529

{
  "1/151/65529": [
    0,
    1
  ]
}

Bridge Command Payload Format

The bridge accepts Matter commands in this structure:

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 151,
    "command_name": "PresentMessagesRequest",
    "payload": {},
    "timed_request_timeout_ms": 1000
  }
}

For Cluster 151, always use "cluster_id": 151. Payload keys are the command field names in lowerCamelCase. Octet-string fields are base64-encoded. timed_request_timeout_ms is required for timed commands and ignored otherwise.

Command: PresentMessagesRequest

Purpose

On receipt, this must cause the message in the passed fields to be appended to the Messages attribute. If appending the message would cause the number of messages to be greater than the capacity of the list, the device must NOT append any message to Messages, and returns a status code of RESOURCE_EXHAUSTED. When displaying a message in response to this command, an indication (ex. visual) of the origin node of the command is provided. This could be in the form of a friendly name label which uniquely identifies the node to the user.

Command Identity

Payload Fields

Priority values (MessagePriorityEnum): 0 = Low, 1 = Medium, 2 = High, 3 = Critical

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 151,
    "command_name": "PresentMessagesRequest",
    "payload": {
      "messageID": 0,
      "priority": 0,
      "messageControl": 0,
      "startTime": 0,
      "duration": 1,
      "messageText": "example"
    }
  }
}

Command: CancelMessagesRequest

Purpose

This command will cancel the message IDs specified.

Command Identity

Payload Fields

Bridge Command Example

{
  "message_id": "1",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 151,
    "command_name": "CancelMessagesRequest",
    "payload": {
      "messageIDs": []
    }
  }
}

Cluster 151 Events

Event 0 — MessageQueued

This event is generated when a message is added to the messages attribute.

Event 1 — MessagePresented

This event is generated when the message is presented to the user.

Event 2 — MessageComplete

This event is generated when the message is confirmed by the user, or when the Duration field of the message has elapsed without confirmation.

SmartphoneKey Notes

• Cluster 151 is not currently exposed by SmartphoneKey devices. This page documents the Matter 1.6.1 specification so that future devices can be interpreted without changes to the backend.
• Shadow paths follow endpoint/151/attribute; attribute values that the device reports as unreadable are written as n/a.
• Attribute IDs, command IDs and enum values on this page come from the CSA Matter 1.6.1 data model; descriptions are condensed from the specification text.