From fa78688f57c0b2d79fdac39c4ead757fdf484927 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Wed, 14 Jan 2026 10:15:24 +0100 Subject: [PATCH] Spec for MSC4356: Recently used emoji (#2291) Signed-off-by: Johannes Marbach Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- .../client_server/newsfragments/2291.feature | 1 + content/client-server-api/_index.md | 2 + .../client-server-api/modules/recent_emoji.md | 40 +++++++++++++++++++ .../definitions/recent_emoji.yaml | 29 ++++++++++++++ .../examples/m.recent_emoji.yaml | 16 ++++++++ data/event-schemas/schema/m.recent_emoji.yaml | 29 ++++++++++++++ 6 files changed, 117 insertions(+) create mode 100644 changelogs/client_server/newsfragments/2291.feature create mode 100644 content/client-server-api/modules/recent_emoji.md create mode 100644 data/api/client-server/definitions/recent_emoji.yaml create mode 100644 data/event-schemas/examples/m.recent_emoji.yaml create mode 100644 data/event-schemas/schema/m.recent_emoji.yaml diff --git a/changelogs/client_server/newsfragments/2291.feature b/changelogs/client_server/newsfragments/2291.feature new file mode 100644 index 00000000..93a509dc --- /dev/null +++ b/changelogs/client_server/newsfragments/2291.feature @@ -0,0 +1 @@ +Add `m.recent_emoji` account data event to track recently used emoji as per [MSC4356](https://github.com/matrix-org/matrix-spec-proposals/pull/4356). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 8f8092b5..9a64b41b 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -3898,6 +3898,7 @@ that profile. | [Guest Access](#guest-access) | Optional | Optional | Optional | Optional | Optional | | [Moderation Policy Lists](#moderation-policy-lists) | Optional | Optional | Optional | Optional | Optional | | [OpenID](#openid) | Optional | Optional | Optional | Optional | Optional | +| [Recently used emoji](#recently-used-emoji) | Optional | Optional | Optional | Optional | Optional | | [Reference Relations](#reference-relations) | Optional | Optional | Optional | Optional | Optional | | [Reporting Content](#reporting-content) | Optional | Optional | Optional | Optional | Optional | | [Rich replies](#rich-replies) | Optional | Optional | Optional | Optional | Optional | @@ -3999,5 +4000,6 @@ systems. {{% cs-module name="Spaces" filename="spaces" %}} {{% cs-module name="Event replacements" filename="event_replacements" %}} {{% cs-module name="Event annotations and reactions" filename="event_annotations" %}} +{{% cs-module name="Recently used emoji" filename="recent_emoji" %}} {{% cs-module name="Threading" filename="threading" %}} {{% cs-module name="Reference relations" filename="reference_relations" %}} diff --git a/content/client-server-api/modules/recent_emoji.md b/content/client-server-api/modules/recent_emoji.md new file mode 100644 index 00000000..77c0c12b --- /dev/null +++ b/content/client-server-api/modules/recent_emoji.md @@ -0,0 +1,40 @@ +### Recently used emoji + +{{% added-in v="1.18" %}} + +This module enables clients to track a user's cumulated emoji usage across different +devices. The data is stored in the [`m.recent_emoji`](#mrecent_emoji) +global [account data](#client-config) and can, among other things, be used to +generate recommendations in emoji pickers. + +#### Events + +{{% event event="m.recent_emoji" %}} + +#### Client behaviour + +What exactly constitutes trackable emoji usage is left as an implementation detail +for clients. It is RECOMMENDED to include sending emoji in both messages and +annotations. + +When an emoji is used, the sending client moves (or adds) it to the beginning of +the `recent_emoji` array and increments (or initializes) its counter. This keeps +the array ordered by last usage time which facilitates evaluating the data. How +exactly the client evaluates and uses the collected data is deliberately left +unspecified. + +To prevent excessive growth of the event as new emoji are being used, clients +SHOULD limit the length of the `recent_emoji` array by dropping elements from +its end. A RECOMMENDED maximum length is 100 emoji. + +To enable future extension, clients MUST tolerate and preserve array elements +within `recent_emoji` regardless of whether they understand or support the +contained `emoji` value. This means ignoring entries with unrecognised values +of `emoji` when deciding what to display to the user while retaining them when +modifying the array (unless the modification is for truncation). + +To prevent undefined behavior, clients SHOULD remove array elements that +don't conform to the event schema such as elements with negative counters. + + + diff --git a/data/api/client-server/definitions/recent_emoji.yaml b/data/api/client-server/definitions/recent_emoji.yaml new file mode 100644 index 00000000..c2deab94 --- /dev/null +++ b/data/api/client-server/definitions/recent_emoji.yaml @@ -0,0 +1,29 @@ +# Copyright 2026 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +title: Recent Emoji +type: object +properties: + emoji: + type: string + description: The Unicode emoji as string. + example: 🚀 + total: + type: number + description: |- + The number of times the emoji has been used. + MUST be non-negative and smaller than 2^53. +required: + - emoji + - total diff --git a/data/event-schemas/examples/m.recent_emoji.yaml b/data/event-schemas/examples/m.recent_emoji.yaml new file mode 100644 index 00000000..85b15cc6 --- /dev/null +++ b/data/event-schemas/examples/m.recent_emoji.yaml @@ -0,0 +1,16 @@ +{ + "$ref": "core/event.json", + "type": "m.recent_emoji", + "content": { + "recent_emoji": [{ + "emoji": "🤔", + "total": 19 + }, { + "emoji": "👍", + "total": 7 + }, { + "emoji": "😅", + "total": 84 + }] + } +} diff --git a/data/event-schemas/schema/m.recent_emoji.yaml b/data/event-schemas/schema/m.recent_emoji.yaml new file mode 100644 index 00000000..8db49a48 --- /dev/null +++ b/data/event-schemas/schema/m.recent_emoji.yaml @@ -0,0 +1,29 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "title": "Recent Emoji Event", + "description": "Lets clients maintain a list of recently used emoji.", + "allOf": [{ + "$ref": "core-event-schema/event.yaml" + }], + "properties": { + "type": { + "type": "string", + "enum": ["m.recent_emoji"] + }, + "content": { + "type": "object", + "properties": { + "recent_emoji": { + "description": "The list of recently used emoji. Elements in the list are ordered descendingly by last usage time.", + "type": "array", + "items": { + "$ref": "../../api/client-server/definitions/recent_emoji.yaml" + }, + } + }, + "required": ["recent_emoji"] + } + }, + "required": ["type", "content"] +}