Presets, buckets and caps
Presets, buckets and caps
A preset supplies a nav's banner, dividers, edge emoji and colour variants. Three are currently configured. Separate caps limit how many links a nav can carry and how much custom emoji it can spend.
What a preset controls
Preset fields
| Field | Controls |
|---|---|
| banner | The emoji run on row 1, alone on its own line. |
| topDivider | The divider directly under the banner. Left empty — the current default for two of the three presets — the body divider is reused there too. |
| divider | The body divider: the row between every link, and the closing row after the last one. |
| footer | Stored and editable, never sent (chapter 4.7). |
| emojis | One edge emoji per platform, plus an optional default that covers every platform without its own slot. A platform with neither renders with no edge emoji and no padding — see below. |
| labels | Per-preset overrides of a link's displayed text, up to 64 characters each. None of the three current presets defines any. |
| label | The name shown in the Preset dropdown. |
| colors | Per-colour overrides — a full banner/divider/emoji/label set for each colour choice offered in the Color dropdown. |
A preset can also be switched off: enabled: false removes it from the pool entirely; any other value — true, or leaving the field unset — keeps it available.
A bucket can optionally name a preset to switch to automatically when it's picked.
A platform with no edge emoji renders bare (test-verified)
| Input | Output |
|---|---|
A website link on a preset whose emojis covers only one other platform | the label alone, centred with spaces across the full line — no edge emoji, no padding asymmetry from one |
191px free ÷ 3px spaces = 63.7 → 63 spaces, 31 left / 32 right, from the builder's own test suite.
The three presets
Configured presets
| Key | Dropdown label | Default emoji slot | Colour variants |
|---|---|---|---|
| white | ios theme | None — unlisted platforms render bare | 17 |
| white-theme | Glossy | None — unlisted platforms render bare | 17 |
| diamonds | diamonds | Yes — every unlisted platform still gets an edge emoji | 14 (materials) |
"Unlisted platform" means any link whose platform has no emoji of its own in that preset — most site: links to a project's own domain, among others. white (20 platform emoji slots) and white-theme (15 slots) define no default slot at all, so any unlisted platform's link renders as the label alone, no edge emoji, centred across the full line. diamonds (16 slots, including default) always shows an edge emoji, falling back to it for anything not individually listed.
diamonds draws its colour variants from a separate 14-entry materials palette (Silver, Diamond, Bronze, Ruby, Emerald, and 9 others); white and white-theme draw from a 17-colour standard palette. Every Color dropdown also offers Main first — the preset's own top-level appearance, outside of any named colour.
The link cap
Six links, currently. The active configuration itself allows up to 8, but a compiled cap of 6 takes precedence wherever the two disagree — the builder always uses the smaller of the two, so raising the configuration value alone has no effect on what can actually be selected.
Where the six-link cap shows up
| Setting | Value |
|---|---|
| Reaching it while checking links | the next checkbox is simply disabled |
| Pressing + at the cap | "Select up to 6 links. Uncheck one to add another." |
| Confirming with more than 6 checked | "Pick at most 6 links ({n} checked)" |
| Saving with more than 6 links | refused server-side: "Select between 1 and 6 links" |
The cap applies only to the links that end up in the message. A scanned site's discovery data is stored independently, up to 1,000 platform groups with up to 100 candidates each, whether or not all of them were ever selected — this is what lets an edit reopen every original candidate, not only the six that were chosen (below).
The custom-emoji ceiling
The active configuration currently caps a nav at 100 custom emoji; any configuration can set the minimum as low as 1, and no maximum is enforced.
When a message's total custom-emoji count is over that cap, the builder removes divider rows to bring it back under — starting from the last row and working upward, removing any row that is byte-for-byte the configured body divider or top divider, one row at a time, until the count fits or every divider row is gone.
Links never drop
Link rows, and the space padding around them, are never removed by this process, and neither is the banner row. Only rows that exactly match a configured divider are candidates for removal — a nav keeps every one of its links no matter how far over the cap it ends up.
Dropping dividers to fit the cap (test-verified)
| Input | Output |
|---|---|
| 8 links, cap set to 120 | banner (8) + 9 divider rows × 12 (108) + 8 link rows × 2 edge emoji (16) = 132 total → one divider row removed (−12) = 120, fits. All 8 links survive; the message ends with the banner, 8 divider rows and 8 link rows — 17 lines, down from 18. |
| Same 8 links, cap set to 20 | even with every divider row gone, the banner (8) plus 8 links × 2 edges (16) alone total 24 — still over the cap. All 8 links still survive; nothing beyond divider rows is ever removed. |
The drop shows up directly in the live preview, as fewer divider rows, rather than through any message displayed in the builder.
Saving and sending
A finished nav is saved through the same request every text command uses; there is no nav-specific save path. Submitting Step 5 sends the trigger, the exact HTML the live preview rendered, and the hyperlinkNav settings together.
The server validates hyperlinkNav before accepting it, and refuses to save one with no response HTML at all: "A hyperlink navigation response is required."
Once saved, the command is written into the bot's textCommands and reaches the running bot the same way any other command change does. Sending it afterward is ordinary text-command dispatch: a reply to the triggering message, HTML parse mode, link previews disabled (chapter 4.7).
Editing an existing nav
Opening a saved nav
- Open the bot's Commands tab.
- Find the nav's row and click its response cell — it reads "Click to edit hyperlink navigation" instead of the usual "Click to edit."
- The builder opens directly on Step 4 (Preset), pre-loaded with the saved preset, colour, logo choice and trigger. Steps 1 through 3 are skipped.
- Change the preset, colour, links (via "Edit links"), or the trigger, then confirm through to Save Changes.
If the preset pool hasn't finished its own request yet when the builder opens this way, the card briefly shows "Loading presets…"; if that request fails, it shows the pool's own error text with only a Cancel button.
Editing never re-scans the site — no new network request is made. The saved discovery data is replayed exactly as stored: the saved links appear first, checked, followed by every other candidate from the original scan, unchecked. This is the only reason discovery is kept at all.
The trigger can be changed while editing — a new one is only sent if it differs from the saved trigger. Deleting a nav uses the same delete control and confirmation as any other command.
What editing cannot do
| Attempt | Result |
|---|---|
| Clone a nav command | No Clone button is shown on a nav's row — the control is absent, not disabled. |
| Edit a nav's response as plain text, bypassing the builder | Refused: "Edit this command through Hyperlink Nav." |
| Convert a nav into a button command | Refused: "Hyperlink navigations cannot be converted to regular commands." |
Building a nav from links
The builder runs as one five-step flow: website URL, buckets, link selection, preset, and command. The same builder also handles editing (chapter 4.9).
The complete command table
48 user-facing slash commands — 16 public, 2 group-admin, 30 owner-or-staff — plus the bare-uppercase `STOP` and `UNDO` keywords and an unbounded set of…