Custom Emojis Extension • Versia API Reference

The Custom Emojis extension lets an entity carry its own emoji images, so that a name such as :happy_face: in its text can be shown as an image.

Definition

CustomEmoji

Fields

name string Required

Emoji name, surrounded by identification characters (for example, colons: :happy_face:).

The following characters are allowed:

a-z
A-Z
0-9
_, -

Identification characters MUST NOT be any of the characters allowed above. A name MUST have exactly two identification characters, one at the beginning and one at the end.

content Media Required

Emoji image. MUST be an image (image/*).

{
    "name": ":happy_face:",
    "content": {
        "url": "https://cdn.example.com/emojis/happy_face.webp",
        "media_type": "image/webp",
        "description": "A happy emoji smiling."
    }
}

Extension

Custom Emojis can be added to any entity with text content. The extension name is pub.versia:custom_emojis.

Extension ID: pub.versia:custom_emojis

Fields

emojis CustomEmoji[] Required

Custom emojis used in the entity.

{
    "id": "033mcbcsyt000",
    "type": "pub.versia:social/Note",
    "created_at": "2024-04-09T01:38:51Z",
    "content": "<p>Hello, world :happy_face:!</p>",
    "visibility": "public",
    // ...
    "extensions": {
        "pub.versia:custom_emojis": {
            "emojis": [
                {
                    "name": ":happy_face:",
                    "content": {
                        "url": "https://cdn.example.com/emojis/happy_face.webp",
                        "media_type": "image/webp",
                        "description": "A happy emoji smiling."
                    }
                }
            ]
        }
    }
}

Behavior

To render custom emojis, clients SHOULD perform the following steps:

Find all instances of custom emoji names in the text content. In RichText, names are only found in text, not inside attribute values.
Replace the custom emoji names with the corresponding emoji images in text.

If custom emojis are not supported, clients SHOULD leave the custom emoji names as-is. Images SHOULD have any associated alt text for accessibility.

<style>
img.emoji {
    display: inline;
    height: 1em;
}
</style>

<p>
    Hello, world <img src="https://cdn.example.com/emojis/happy_face.webp" alt="A happy emoji smiling." class="emoji" />!
</p>

Emojis SHOULD be displayed at a fixed height (such as 1em), but their width SHOULD be allowed to be flexible.