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:
| Text | UTF-8 bytes | UTF-16 units (JavaScript .length) | Code points (Python len()) | Graphemes |
|---|---|---|---|---|
a | 1 | 1 | 1 | 1 |
é | 2 | 1 | 1 | 1 |
☕ | 3 | 1 | 1 | 1 |
👋 | 4 | 2 | 1 | 1 |
👨👩👧👦 | 25 | 11 | 7 | 1 |
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#mentionwithdid: the account's DID, never its handle;app.bsky.richtext.facet#linkwithuri: a full address, scheme included;app.bsky.richtext.facet#tagwithtag: 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:
[
{
"$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://orhttps://, or look like a domain on a known top-level domain (bsky.app/profile/xbecomeshttps://bsky.app/profile/x;index.jsstays 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$BTCbecomes the tag$BTC.
Common bugs
- Counting in UTF-16. JavaScript's
indexOfand.lengthgive UTF-16 positions. Encode first:
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:
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.resolveHandlefirst. - 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:
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.