For websites
Bafflebot and link previews
How baff.gg previews links to your site, how to customise the card with bafflux tags, and how to control Bafflebot with robots.txt.
When someone posts a link in baff.gg, Bafflebot fetches the page and shows a preview card under the message: the site name, a title, a description, an image and a colored bar. This page is for website owners who want those cards to look right, or different from other platforms.
Bafflebot
Bafflebot is baff.gg's link preview crawler. It sends this User-Agent:
Mozilla/5.0 (compatible; Bafflebot/1.0; +https://docs.baff.gg/bafflebot)- When it visits. Only when someone sends or edits a message with your link (up to 3 links per message). It doesn't crawl, follow links or index anything. A result is reused for about 30 minutes, so a busy link isn't fetched again for every message.
- What it reads. The first 512 KB of the page's HTML (only the
<head>tags matter), within 6 seconds, following up to 4 redirects. Images it reads only far enough to know their size. - Where it connects from. baff.gg's server, never from the people chatting. It won't fetch private or local network addresses.
- What it skips. Links wrapped in angle brackets (
<https://example.com>), links inside code or||spoilers||, and links to baff.gg itself.
To show baff.gg something different from browsers or other platforms, match Bafflebot in the User-Agent on your server. Most sites don't need to: the bafflux tags below change the card without changing the page.
robots.txt
Bafflebot respects your robots.txt (Discord's crawler doesn't). It reads https://your-site/robots.txt once in a while and follows the group for Bafflebot, or the * group when there isn't one. A page it may not fetch simply gets no preview.
# No previews of anything under /private on baff.gg
User-agent: Bafflebot
Disallow: /private
# No baff.gg previews at all
User-agent: Bafflebot
Disallow: /Rules follow the usual reading: the longest matching path wins, Allow wins a tie, * matches anything and a final $ anchors the end. If there's no robots.txt, or it can't be reached, previews are allowed.
What the card shows
Without any baff.gg-specific tags, the card uses the tags most sites already have:
| Part of the card | Read from |
|---|---|
| Site name | og:site_name, application-name |
| Title | og:title, twitter:title, <title> |
| Description (up to 350 characters) | og:description, twitter:description, <meta name="description"> |
| Image | og:image, twitter:image (a thumbnail on the right; a large image when twitter:card is summary_large_image) |
| Bar color | <meta name="theme-color"> |
A direct link to an image shows just the image, and YouTube links get a playable video card.
bafflux tags
Add bafflux: tags to your page's <head> to set the card for baff.gg only. Each one wins over its Open Graph and Twitter equivalent, so you can keep those for other platforms. Use name="..." or property="...", whichever you prefer.
| Tag | What it does |
|---|---|
bafflux:title | The title |
bafflux:description | The description |
bafflux:site | The site name above the title |
bafflux:image | The image (absolute or relative URL) |
bafflux:card | summary: small image on the right. large: big image under the text |
bafflux:color | The bar color, like #2ec4b6 (instead of theme-color) |
bafflux:author | An author line above the title |
bafflux:author:icon | A small round icon next to the author |
bafflux:author:url | Makes the author a link |
bafflux:footer | Small text at the bottom of the card (up to 200 characters) |
bafflux:footer:icon | A small icon next to the footer |
bafflux:button:1:label + bafflux:button:1:url | A link button under the card. Up to 3: button:1, button:2, button:3. Labels up to 80 characters |
bafflux:spoiler | true covers the image until it's clicked |
<head>
<!-- What every platform sees -->
<meta property="og:title" content="Harbor: a new map" />
<meta property="og:description" content="Night fights, fog and a lighthouse." />
<meta property="og:image" content="https://example.com/harbor.png" />
<!-- baff.gg only -->
<meta name="bafflux:card" content="large" />
<meta name="bafflux:color" content="#f2766b" />
<meta name="bafflux:author" content="Patch notes" />
<meta name="bafflux:author:icon" content="https://example.com/icon.png" />
<meta name="bafflux:footer" content="Version 1.4" />
<meta name="bafflux:button:1:label" content="Play now" />
<meta name="bafflux:button:1:url" content="https://example.com/play" />
<meta name="bafflux:button:2:label" content="Full patch notes" />
<meta name="bafflux:button:2:url" content="https://example.com/notes/1-4" />
</head>A few rules keep cards trustworthy:
- Buttons are always plain links. A site can't make a button that does something inside baff.gg. People who click a link that leaves baff.gg see where it goes first ("Leaving baff.gg"), unless they trusted that site before.
- Only http and https URLs are used, for images, icons, links and buttons. Anything else is ignored.
- A button needs both its label and its url, or it's left out.
- Text is shortened to fit (title 256, description 350, author 256, footer 200 characters).
Testing your tags
Post your link in any baff.gg channel. If you just changed your tags, add something to the URL (like ?v=2) so Bafflebot doesn't reuse the card it made in the last 30 minutes. If nothing shows up, check that:
- The page is reachable from the internet without logging in.
- The tags are in the HTML your server sends, not only added later by JavaScript (Bafflebot doesn't run scripts).
- robots.txt doesn't block Bafflebot for that path.
- The page answers within 6 seconds.
For bots, link previews show up in the message's embeds with type: "link"; see Embeds.