Tool documentation

Bluesky rich text facets: bytes, mentions, links and tags

How Bluesky facets work: UTF-8 byte offsets versus characters and graphemes, the facet lexicon, worked examples and the common bugs in JavaScript and Python.

Bytes, characters and graphemes

The text of a post is one string. Mentions, links and hashtags are not marked up inside it: they are facets, a list next to the text, each one saying "these bytes of the text are a mention of this DID, a link to this address or this tag". The positions count bytes of the UTF-8 encoding, not characters.

Three ways to count the same text disagree as soon as it leaves ASCII:

TextUTF-8 bytesUTF-16 units (JavaScript .length)Code points (Python len())Graphemes
a1111
é2111
☕3111
👋4211
👨‍👩‍👧‍👦251171

Facets use the first column. The length limit of a post uses the last one (300 graphemes) and the first (3,000 bytes): see How Bluesky counts the length of a post.

The facet lexicon

A facet is an app.bsky.richtext.facet object: an index with byteStart (inclusive) and byteEnd (exclusive), and features, usually one:

  • app.bsky.richtext.facet#mention with did: the account's DID, never its handle;
  • app.bsky.richtext.facet#link with uri: a full address, scheme included;
  • app.bsky.richtext.facet#tag with tag: the tag without #, at most 64 graphemes and 640 bytes.

The ranges must stay inside the text, start and end on character boundaries, and should not overlap. Sorting them by byteStart is not required, but readers expect it.

A worked example

The text Café ☕ with @bsky.app: https://atproto.com #atproto is 51 UTF-16 units long, but 54 bytes: é takes 2 bytes and ☕ 3. So @bsky.app starts at byte 15, not at index 12:

json
[
  {
    "$type": "app.bsky.richtext.facet",
    "index": { "byteStart": 15, "byteEnd": 24 },
    "features": [
      {
        "$type": "app.bsky.richtext.facet#mention",
        "did": "did:plc:z72i7hdynmk6r22z27h6tvur"
      }
    ]
  },
  {
    "$type": "app.bsky.richtext.facet",
    "index": { "byteStart": 26, "byteEnd": 45 },
    "features": [
      { "$type": "app.bsky.richtext.facet#link", "uri": "https://atproto.com" }
    ]
  },
  {
    "$type": "app.bsky.richtext.facet",
    "index": { "byteStart": 46, "byteEnd": 54 },
    "features": [{ "$type": "app.bsky.richtext.facet#tag", "tag": "atproto" }]
  }
]

How Bluesky detects facets

The builder follows the rules of @atproto/api (packages/api/src/rich-text/detection.ts in bluesky-social/atproto), and a test compares the two on tricky texts:

  • Links start with http:// or https://, or look like a domain on a known top-level domain (bsky.app/profile/x becomes https://bsky.app/profile/x; index.js stays text). A final ., ,, ;, :, ! or ? is left out, and so is a final ) without an opening one.
  • Mentions are @ followed by a handle on a known top-level domain, after a space, a ( or the start of the text. They need their DID.
  • Hashtags start with # or the full-width #, are not made of digits only, lose their final punctuation, and stop at 64 graphemes. A cashtag such as $BTC becomes the tag $BTC.

Common bugs

  • Counting in UTF-16. JavaScript's indexOf and .length give UTF-16 positions. Encode first:
ts
const encoder = new TextEncoder();
const byteStart = encoder.encode(text.slice(0, start)).length;
const byteEnd = byteStart + encoder.encode(text.slice(start, end)).length;
  • Counting code points. Python's len() and string indexes count code points. Count the encoded bytes:
python
byte_start = len(text[:start].encode("utf-8"))
byte_end = byte_start + len(text[start:end].encode("utf-8"))
  • A handle in a mention. The feature takes a DID: resolve the handle with com.atproto.identity.resolveHandle first.
  • No facets at all. A post created through the API gets no automatic detection: without facets, links and hashtags are plain text. With @atproto/api, RichText.detectFacets(agent) builds them for you; see Make a bot in TypeScript and Make a bot in Python.

Use it from code

The builder is also a free API route and an MCP tool, build_post_facets:

bash
curl -G "https://bluesky.bot/api/v1/tools/facet-builder" \
  --data-urlencode "text=Hello @bsky.app! #atproto"

A call costs 1 against the limits, plus 1 per 3 mentions not resolved in the last minute. A GET address holds about 8 KB once encoded, and a non-ASCII character takes up to 12 bytes there: send long or non-Latin text through MCP, whose request is a POST body. See Tools API and MCP server.

Rich text facet builder

Mentions, links and hashtags with their byte offsets.