Slack and Teams Link Previews

Slack and Teams Link Previews

A Folio link pasted into Slack or Microsoft Teams unfurls into a card with the page's title, place, opening text and headings, built with the Folio access of the person who shared it. Added in Folio 0.4. A page that person cannot open shows a card with no title at all.

What the card shows

Icon and title, Space / Parent / Page, the first lines of text, section headings, tags, the last update and who made it. A data table shows its rows and columns, a form its number of fields. An Open in Folio button goes to the page. Cards are in English.

How people connect

The first time someone shares a Folio link, Slack shows them (only them) a Connect Folio message; Teams shows a Connect Folio sign-in in the compose box. They sign in with Slack or in the Teams window, then to Folio, and approve read access on Folio's consent screen. After that their links unfurl by themselves. Share links and pages of a public site unfurl for everyone without connecting. People disconnect in API tokens, Chat apps; admins see every connection in Administration, Chat integrations.

Set it up (administrator)

Requirements: PUBLIC_URL is an https:// address reachable from the internet, and FOLIO_SECRET is set (it is with the bundled compose file).

Slack (one workspace per instance):

1. Administration, Chat integrations, Download Slack app manifest (filled with your addresses).
2. At api.slack.com/apps: Create New App, From a manifest, paste it.
3. Copy the Signing Secret, Client ID and Client Secret into FOLIO_SLACK_SIGNING_SECRET, FOLIO_SLACK_CLIENT_ID, FOLIO_SLACK_CLIENT_SECRET.
4. Install to Workspace, copy the Bot User OAuth Token into FOLIO_SLACK_BOT_TOKEN (optional: FOLIO_SLACK_TEAM_ID).
5. Restart Folio, verify the Request URL under Event Subscriptions, paste a link in a channel.

Teams (one Microsoft Entra tenant per instance): create an Azure Bot (single tenant), set its messaging endpoint to <PUBLIC_URL>/api/integrations/teams/messages, add the Teams channel, set FOLIO_TEAMS_APP_ID and FOLIO_TEAMS_TENANT_ID, restart, download the Teams app package from Chat integrations, and have a Microsoft 365 administrator upload it.

The complete steps, the manifest and the variable tables are in CHAT-PREVIEWS.md.

Privacy

A preview is seen by everyone in the conversation, whatever their own Folio rights. So a page not open to its whole space (restricted, or an .agent page) shows its title only; the breadcrumb never names a parent the sharer cannot read; page text goes out as plain text. Folio stores the chat user id and name, the workspace or tenant id and the OAuth tokens (encrypted); message text is never stored.

Limits

• One card for the whole conversation, built for the sharer; Teams cards are not refreshed per viewer.
• A preview is a snapshot of the page when the link was shared.
• One Slack workspace (no Enterprise Grid org-wide install) and one Teams tenant per instance. Slack accepts five link domains.
• Teams mobile unfurls only links that need no sign-in; connecting needs the desktop or web client.
• Connections unused for 30 days lapse and the person connects again.

See also

Sharing and Permissions · Publish a Public Website · Install guides · Blog: Folio 0.4