Custom emoji (NIP-30)

Shosho supports custom emoji in chat messages, reactions, and profiles. Custom emoji are images mapped to shortcodes (e.g. :pepe-happy:) that render inline. Two NIPs are involved:

• NIP-30  defines the emoji tag (["emoji", <shortcode>, <image-url>, <emoji-set-address>]) and the events it can be added to: kind 0 (profile), kind 1 (note), kind 7 (reaction), and kind 30315 (live status).
• NIP-51  defines the emoji set (kind 30030) and the user’s emoji list (kind 10030) — i.e. the events you bookmark and the events that hold the bookmarks.

Shosho also extends NIP-30’s emoji tag pattern to live-stream chat messages (kind 1311) and clip comments (kind 1111) — the same shortcode-and-tag mechanism applies.

Discover a custom emoji set

Browse and discover sets at emojito.meme  — a Nostr app for creating and finding emoji sets. Each set there is a kind 30030 event you can bookmark to your user’s emoji list.

Or query relays directly:

nak req -k 30030 -l 20 wss://relay.damus.io wss://nos.lol

A kind 30030 emoji set looks like:

{
  "kind": 30030,
  "tags": [
    ["d", "fun-reactions"],
    ["title", "Fun Reactions"],
    ["emoji", "blob-dance", "https://example.com/blob-dance.gif"],
    ["emoji", "pepe-happy", "https://example.com/pepe-happy.png"]
  ],
  "content": ""
}

Bookmark an emoji set to the user’s list

A user’s custom emoji are stored in a kind 10030 event. This event can contain direct emoji definitions and/or a tag references to kind 30030 sets. Kind 10030 is replaceable — publishing a new one replaces the old one entirely.

# 1. Fetch the user's current emoji list (if any)
nak req -k 10030 -a <hex_pubkey> -l 1 wss://relay.damus.io wss://purplepag.es
 
# 2. Publish updated emoji list with the new set bookmarked
#    Preserve all existing tags from the current list, then add the new 'a' tag
nak event -k 10030 \
  -t 'a=30030:<set_author_hex_pubkey>:<set_d_tag>' \
  --sec <nsec1...> \
  wss://relay.damus.io wss://relay.primal.net wss://purplepag.es

The a tag format is ['a', '30030:<pubkey>:<d-tag>'].

When updating the emoji list, you must include all existing tags (both emoji and a tags) from the current kind 10030 event, plus any new tags. Since kind 10030 is replaceable, publishing without the old tags will remove previously bookmarked sets.

Fetch a user’s custom emoji

# Fetch user's emoji list
nak req -k 10030 -a <hex_pubkey> -l 1 wss://relay.damus.io wss://purplepag.es
 
# Fetch a specific emoji set (from 'a' tags in the emoji list)
nak req -k 30030 -a <set_author_hex_pubkey> -t d=<set_d_tag> wss://relay.damus.io

Individual emoji are stored as ['emoji', '<shortcode>', '<image_url>'] tags, optionally with a fourth element ['emoji', '<shortcode>', '<image_url>', '<30030-set-address>'] per NIP-30. Shortcodes must contain only alphanumerics, hyphens, and underscores.

Use a custom emoji in a message

To use a custom emoji in a chat message or reaction, include the shortcode in the content wrapped in colons, and add a matching emoji tag:

nak event -k 1311 \
  --content "Love this stream :fire:" \
  -t 'emoji=fire;https://example.com/emoji/fire.png' \
  -t a='30311:<stream_author_hex_pubkey>:<d-tag>;wss://relay.damus.io;root' \
  --sec <nsec1...> \
  wss://relay.damus.io wss://relay.primal.net

Shosho renders :shortcode: as the image from the matching emoji tag.

Related

• Chat (kind 1311 / 7)