Docs

Slack Updates

Post session updates and weekly summaries from FlyDocs to a Slack channel: what each message contains, the six scopes the app requests and why, and how to connect, reconnect and disconnect.

When an engineer wraps a session, FlyDocs can post the update to a Slack channel your team already reads. Once a week it can post a summary of the whole workspace to the same channel or a different one. You connect Slack once for the organization, and each workspace picks its own channels.

In the portal this feature is called Updates. The Slack connection lives on Settings > Connections, and the per-workspace choices live in the Activity page settings.

What FlyDocs posts

Two kinds of message, both built the same way: a short parent message that keeps the channel scannable, and a thread reply underneath it with the detail. Someone skimming the channel reads the parent; someone who cares opens the thread.

Session updates

One message per wrapped session, posted as the session wraps.

  • The parent has one line saying who wrapped, in which repository, and the health they gave it (on track, at risk, off track). Below that sits the session title in bold and the summary the engineer wrote, in full. Nothing is cut short, so the parent alone tells you what happened.
  • The thread breaks the wrap into lists: Accomplished, Next up, Blockers and Progress. A section with nothing in it is left out rather than shown empty.

A session update never carries cost, token counts, or any per-person figure. The message template has no field that could hold one, so this isn't a setting someone can switch on by accident.

Weekly summary

A separate message, once a week, that mirrors the week panel on the Activity page.

  • The parent names the week, then gives four figures, each with its change from the week before: Sessions (and how many people filed them), Issues moved, PRs shipped and Open blockers. A TL;DR paragraph reads those numbers for you, and a link opens the full week in FlyDocs.
  • The thread lists what Landed (the issues that moved and where they ended up), what Shipped (the pull requests, linked), and what is still Blocked.

A week with no recorded sessions gets one line saying so, not four zeros that look like an outage. If a week had more sessions than the summary could read, the message says that too.

Connect Slack

Connecting is an organization admin's job, because it decides which Slack workspace every FlyDocs workspace in the organization can post to. One organization connects to one Slack workspace.

  1. In the portal, open Settings > Connections.
  2. Find the Updates row and click Connect Slack.
  3. Slack asks you to pick a Slack workspace and approve the app's permissions. If the grant Slack returns is missing any of the six scopes below, or carries one beyond them, FlyDocs refuses the install and shows an error rather than running with a different set.
  4. You land back on Connections, where the row shows Connected and the name of your Slack workspace.

Org-wide installs across an Enterprise Grid aren't supported yet. Install into one Slack workspace inside the grid instead.

Choose where updates go

Each FlyDocs workspace chooses its own channels. An admin does this from the workspace's Activity page; every member can see the settings.

  1. Open the workspace's Activity page and click the gear to open Activity settings.
  2. Under Session wrap updates, turn on Post session wraps to Slack.
  3. Pick a channel from the list that appears.
  4. Click Send test. FlyDocs posts a sample message through the same path a real update takes, so if the test arrives, real updates will too.

The weekly summary is set up in the same dialog. Under Weekly summary, turn on Send a weekly summary, then turn on Post the weekly summary to Slack and pick its channel. It can be the channel your session updates use or a different one. Turning the weekly summary off keeps the channel you chose, so switching it back on doesn't mean picking again.

Public channels only

The channel picker lists public channels only. That follows from the scopes below: FlyDocs can read the list of public channels and nothing else, so a private channel can never appear in the picker. In a very large Slack workspace the picker shows the first 1,000 public channels and says so.

You don't need to invite the bot. The chat:write.public scope lets FlyDocs post to any public channel you pick without being a member of it first, so there's no /invite step per channel.

Scopes, and why each one

The FlyDocs Slack app requests six bot scopes and no user scopes. A user token would be a second credential tied to one employee's account, and nothing here needs one.

Scope What FlyDocs does with it
channels:read Lists public channels for the channel picker. It returns the channel directory (name, ID, whether it's archived, member count) and no messages.
chat:write Posts session updates and weekly summaries.
chat:write.public Posts to a public channel the bot hasn't been invited to, so nobody has to invite it channel by channel.
im:write Opens a direct message for a personal digest. Not in use yet.
links:read Reads link previews of FlyDocs's own messages, for unfurling. Not in use yet.
links:write Unfurls issue references and FlyDocs links into a summary card. Not in use yet.

There are no scopes that read messages, and that is a commitment, not an omission. FlyDocs doesn't request channels:history, groups:read, users:read or files:read, or anything else that would let it read what people say, who they are, or what they share. The picker being limited to public channels is the visible cost of that choice.

The set is enforced exactly. An install that grants fewer than these six, or any scope beyond them, is refused, so the permissions your Slack admin approved are the permissions FlyDocs holds.

What crosses into Slack

Data boundary

FlyDocs only writes to Slack. It holds no scope that reads message content or user profiles, and the only thing it reads is the list of public channels. The bot can't join a private channel on its own, and the picker never offers one.

What it writes is the session wrap your team already wrote and the weekly figures built from those wraps. Source code, diffs and the prompts behind a session are never posted.

Session updates carry no cost or token figures, and neither message reports anything per person.

The bot token is encrypted before FlyDocs stores it and is decrypted only on the server, at the moment a message is sent or the channel list is loaded.

Disconnect and reconnect

An organization admin can disconnect at any time.

  1. Open Settings > Connections.
  2. On the Updates row, click Disconnect.

Disconnecting revokes the bot token with Slack, so it stops working at Slack's end, and permanently revokes the encrypted copy FlyDocs stored: it can never be decrypted or used again. Every channel that was receiving updates stops at once. If Slack can't be reached at that moment, FlyDocs still revokes its own copy; you can also remove the app from your Slack workspace's app management page to be certain.

Messages FlyDocs already posted stay in Slack. We don't delete them, and after disconnecting we couldn't.

Reconnecting works exactly like connecting: the Updates row shows Reconnect, and you approve the app again. Each workspace's channel choices survive a disconnect, so after reconnecting, updates go back to the channels they were going to before.

Next