Share diagrams in Slack: unfurl mechanics, the cache, and cache-busting

Paste a URL and Slack fetches it to build an unfurl. A URL that responds with an image Content-Type renders inline as the image itself; an HTML page renders as a link card built from its Open Graph tags, og:image included. A direct image URL is therefore the strongest form for a diagram: the picture lands in the thread full-size, no card chrome around it.

The Datadef image URL responds as a PNG by default, so it unfurls as the diagram. The interactive page URL unfurls as a card instead; it earns its place when you want readers clicking through to pan and zoom, and the two can travel together in one message.

Unfurls as the image itself:
https://datadef.io/api/embed/my-platform-a1b2c3d4

Unfurls as a link card; click through for pan and zoom:
https://datadef.io/embed/my-platform-a1b2c3d4

Slack caches unfurl results per URL, roughly half an hour globally, and proxies the images themselves through its own image proxy with its own cache. There is no API to purge either one. The consequences are specific: repost the same URL right after regenerating the diagram and Slack may serve the cached unfurl; and messages posted earlier keep the preview they were born with, because Slack does not retroactively re-render unfurls in old messages.

For a diagram this is a real correctness issue. The thread from three weeks ago shows the architecture of three weeks ago, with nothing marking it as outdated. Treat Slack previews as timestamped by their message, and when a thread resurfaces after an architecture change, post the URL again rather than pointing at the old message.

The reliable workaround is making the URL unique when you need a fresh render: append a throwaway query parameter and Slack treats it as a URL it has never seen, fetching and unfurling from scratch. Editing the message containing the link also makes Slack re-process that message's unfurl.

This composes well with regeneration. When an agent updates the diagram after a merge, have it post the announcement with a version parameter, the merge SHA is the natural choice. Every such message then unfurls the diagram as of that merge, and the channel history becomes a visual changelog of the architecture.

Force a fresh unfurl by making the URL unique:
https://datadef.io/api/embed/my-platform-a1b2c3d4?v=a1f39c2

The extra parameter is ignored by the renderer; it exists so
Slack's cache sees a brand-new URL.

One layer deeper: a Slack app can register unfurl domains and subscribe to link_shared events, letting it attach custom unfurls when links from those domains are posted. That is how internal tools decorate their links with rich context. It is not required for anything in this guide, image URLs and OG cards unfurl without any app, but teams already running a Slack bot can use it to enrich diagram links with, say, the last-updated time.

A diagram unfurled in a thread answers today's question and then scrolls away, becoming exactly the kind of buried knowledge that tribal knowledge in engineering teams describes. The pattern that works: docs pages carry the live embed as the permanent home, Slack carries the URL when the question comes up, and the URL always resolves to the current diagram.

The source diagram stays current the same way everywhere the URL travels: a person edits it, or an agent does. Datadef exposes diagram tools through its MCP server, registry name io.datadef/mcp, so the redraw can ride the same merge that changed the architecture, and the next unfurl of the URL shows it. Detection is not part of the offer, Datadef never watches a repository; the agent call is the trigger, gated by an API key that arrives with a paid plan. The URLs exist only for projects shared public, so confidential architectures should travel through Slack as uploaded files instead, staleness accepted.

• Embed diagrams in Markdown
• Embed diagrams in Dropbox Paper
• Tribal knowledge in engineering teams
• How to detect stale diagrams