# Slack: how to read it into Maplith

*Communication · also known as Slack workspace, Slack channels · last checked 2026-10-14 · recipe `maplith://systems/slack`*

Slack holds how the company works day to day: which channels carry which work, who hands what to whom, and which systems post their notices there. Maplith reads it to find the recurring processes and write a playbook for each, never to keep the messages.

## Best path

**Recommended: your agent fetches it.** Many assistants already have a Slack connector, and a first map needs a few weeks of a few work channels. For a daily refresh, Maplith's own Slack connector reads the channels a rule selects, once it is switched on for the workspace.

Try the paths in this order (ADR-0031):

1. **Your agent fetches it**, with the access your human already gave you. Connectors a vendor or client page confirms: Slack connector in Claude; Slack connector in ChatGPT. The agent reads the recent history of the public work channels its human names, a few weeks each, and leaves out channels about people (social, HR, personal). It only reads; it should not post.
2. **Maplith reads an MCP server your human already has.** Official: **Slack MCP server**. Endpoint to connect to: `https://mcp.slack.com/mcp`. Documentation (a page to read, not an address to connect to): https://docs.slack.dev/ai/mcp-server. Access: There is no read-only token: an app published in Slack's directory, or one internal to the workspace, connects with OAuth, and each person consents with their own Slack user token. The server then sees what that person may see, direct messages included, which is why Maplith's connector below uses a bot token instead. It offers tools, not resources: search, read channels and threads, and also send messages, create channels and edit canvases. Use it as path 1, for your own agent. Maplith cannot read this server: it offers tools or a personal sign-in to an agent, not resources Maplith reads. Maplith reads only a server that serves MCP resources and takes a token a person types under Data sources › Systems in the Maplith app, such as the customer-run template for a database (ADR-0028). Your human can connect this server to you instead, as path 1.
3. **Export files**, the fallback that always works: see *Export steps* below.
4. **Maplith's own integration** (built, and switched on per workspace: ask Maplith (suggest_feature) to switch it on for yours): see *Maplith's integration* below.

## Datasets that make a good map

| Dataset | One row is | Key columns | Joins to |
|---|---|---|---|
| Channel messages | One message in a public channel: who wrote it (a user id), when, its text, and the thread it belongs to. | channel, ts, user id, thread_ts | Systems and objects the messages name (an order number, an issue, an invoice); the processes the map finds in other systems by the same reference. |
| Channels | One public channel: its name and topic, which say what kind of work it carries. | channel id, name, topic | Messages by channel; the systems that post notices into it. |
| Notices from other systems | One message a bot or integration posted (a deploy, a payment, a new lead). | bot id, channel, ts | The system that posted it, which often is a system not yet shared with Maplith. |

Columns are named, never their values. Maplith tries to mask personal data such as email addresses, but that is best effort: your human decides what goes in.

## Read-only access

**Who usually has the rights:** A Slack workspace owner or admin, or anyone allowed to install apps in the workspace.

**For the key your own agent's client uses, choose only these read permissions:** `channels:read`, `channels:history`, `channels:join`

**Where to click:**

1. Go to api.slack.com/apps and click Create New App, then From scratch
2. Name it (for example Maplith) and pick your workspace
3. Open OAuth & Permissions and, under Bot Token Scopes, add channels:read, channels:history and channels:join, and nothing else
4. Click Install to Workspace and allow it
5. Copy the Bot User OAuth Token; it is used in the next step and is never pasted into a chat

A key or token made here stays in the tool that reads the system for your human, never in a chat. Maplith asks for one only under Data sources › Systems in the app: for an MCP server it can read, or for its own integration below.

## Export steps

**Format:** JSON, delivered as a ZIP file · **Date range:** The last 3 months

1. A workspace owner or admin clicks Admin in the sidebar, then Workspace settings, then Security
2. Click Import & export data, then open the Export tab
3. Choose a date range of the last 3 months and start the export (public channels only)
4. When Slack sends the mail, open the workspace's export page and download the ZIP file
5. Unpack it and remove the folders of channels that are about people (social, HR, personal) before uploading

## Volume hint

**About 1,000–20,000 messages a month** (an estimate). Estimate for a small company, not a measured figure: a handful of work channels, with notice channels from other systems adding most of the volume.

Every row an agent reads passes through its context, about one token per four characters. Above a few thousand rows a dataset, or for a daily refresh, prefer an MCP server or an export over fetching through the chat.

## Maplith's integration

**Status:** built, and switched on per workspace: ask Maplith (suggest_feature) to switch it on for yours.

**How to connect:**

1. Create the Slack app with the three bot scopes, as under Read-only access above
2. In Maplith, open Data sources › Systems and click Connect Slack
3. Paste the Bot User OAuth Token there: Maplith checks it with Slack before it stores it, seals it, and never shows it again
4. Click Test connection to see which channels it will read and which it leaves out

**The permissions it needs, and why:**

- `channels:read`: lists the public channels, so the channel rule can choose among them
- `channels:history`: reads the messages of the public channels the rule selects
- `channels:join`: joins the selected channels by itself, so nobody has to invite the app channel by channel

**What it reads:**

- Messages in the selected public channels within the scan window, as a Slack export the build reads and deletes with the run
- Who wrote each message as a Slack user id, never a name
- What reaches the map: the channels as a source, the processes the messages show and the systems they name; playbooks describe the process, never quote a message

**What it never reads or does:**

- Private channels, direct messages or group messages: the scopes for them are never asked for
- A user token (it reads what a person reads): only a bot token is accepted
- Posting, reacting or changing anything in Slack
- Names or profiles of people (users:read is not asked for)

**Choosing what is read:** Maplith reads every public channel except the ones its rule leaves out: channels whose names say they are about people rather than work (social, random, HR, personal and similar), and any channel a person names. A person changes the rule under Data sources › Systems, Change channels; that choice is theirs from then on.

## What Maplith sets up once it is connected

Maplith builds these itself; a person corrects them, and never has to approve them first (ADR-0038). If the system is disconnected, Maplith takes the playbooks it set up and nobody changed out of use, and puts them back when the system is connected again; a playbook a person changed stays as they left it.

**Signals:**

| Kind | Delivery | When |
|---|---|---|
| `link_dead` | poll | the daily probe finds the token refused, a scope missing, or every selected channel out of reach |
| `structure_changed` | poll | the connection offers at least a quarter more or fewer resources than at the last check |
| `process_silent` | poll | a recurring process the map found in Slack has not happened within its usual interval |
| `finding_added` | poll | the messages name a system the map does not have, or a hand-off that happens out of sight of every shared system |

**Checks:**

- **Connection probe** (every 12 hours): checks the token and the channel list, never a message
- **Channel rule** (every scan): states which channels are read and which are left out, and why, on every scan

**Suggested playbooks:**

- **Reconnect Slack.** Starts when the Slack connection's link_dead signal is raised. Steps: Open Data sources › Systems and run Test connection to read the reason; If the token was refused, create a new bot token in the Slack app and connect again; If a scope is missing, add it to the Slack app, reinstall it, and connect with the new token; Run Test connection again and record what was done.
- **Share the system Slack names.** Starts when a finding says Slack names a system the map does not have. Steps: Read the finding: which system, and in which channel it shows up; Ask the system's owner whether it may be shared with Maplith; Connect it, or upload an export, as that system's guide describes; Resolve the finding with what was decided.

**Schedules:**

- **Read Slack** (with the workspace's scan schedule (daily or weekly)): the playbooks and the processes stay current with how the work is actually done

**What setup integrity expects:**

- The Slack connection exists and its last probe succeeded
- The slack source has an owner and a refresh cadence (Maplith states them from the workspace owner and the scan schedule; a person corrects them)
- Each suggested playbook exists, or a person removed it, and is anchored on a signal kind the connection raises

## Always

- Read-only, and never a credential sent to Maplith through the chat.
- The same recent period, a few months, from every system.
- Your human decides what goes in.

## Sources

Written from the vendor's public documentation, last checked 2026-10-14:

- https://docs.slack.dev/ai/mcp-server
- https://docs.slack.dev/reference/methods/conversations.history
- https://docs.slack.dev/reference/methods/conversations.join
- https://docs.slack.dev/reference/scopes/channels.history
- https://slack.com/help/articles/201658943-Export-your-workspace-data