Docs: System guides
Read Slack into Maplith
On this page
Best path
Recommended: your agent fetches it. Many agents 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:
- Your agent fetches it, with the access you already gave it. 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 you name, a few weeks each, and leaves out channels about people (social, HR, personal). It only reads; it should not post.
- Maplith reads an MCP server you already run. Slack runs Slack MCP server. Its address is
https://mcp.slack.com/mcp. Documentation: docs.slack.dev. 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. Maplith cannot read this server itself, because it offers tools or a personal sign-in to an agent. Connect it to your agent instead, as the first path. - Export files, the fallback that always works. See the export steps below.
- Maplith’s own integration. Built, and switched on per workspace. Ask Maplith at [email protected] 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: you decide what goes in.
The access to give
Who usually has the rights: A Slack workspace owner or admin, or anyone allowed to install apps in the workspace.
Choose the narrowest access that covers the data:
channels:readchannels:historychannels:join
Where to click:
- Go to api.slack.com/apps and click Create New App, then From scratch
- Name it (for example Maplith) and pick your workspace
- Open OAuth & Permissions and, under Bot Token Scopes, add channels:read, channels:history and channels:join, and nothing else
- Click Install to Workspace and allow it
- 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, never in a chat. Maplith asks for one only under Data sources › Systems in the app.
Export steps
Format: JSON, delivered as a ZIP file Date range: The last 3 months
- A workspace owner or admin clicks Admin in the sidebar, then Workspace settings, then Security
- Click Import & export data, then open the Export tab
- Choose a date range of the last 3 months and start the export (public channels only)
- When Slack sends the mail, open the workspace's export page and download the ZIP file
- Unpack it and remove the folders of channels that are about people (social, HR, personal) before uploading
How much data
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.
An agent that reads rows through a chat reads every one of them, about one token per four characters. Above a few thousand rows a dataset, or for a daily refresh, an MCP server or an export is the better path.
Maplith’s integration
Status: Built, and switched on per workspace. Ask Maplith at [email protected] to switch it on for yours.
How to connect
- Create the Slack app with the three bot scopes, as under “The access to give” above
- In Maplith, open Data sources › Systems and click Connect Slack
- Paste the Bot User OAuth Token there: Maplith checks it with Slack before it stores it, seals it, and never shows it again
- Click Test connection to see which channels it will read and which it leaves out
The permissions it asks for
| Permission | 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 read during the scan and deleted when it ends
- 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 sets these up itself. You correct them; you never have to approve them first. If the system is disconnected, the playbooks Maplith set up and nobody changed are taken out of use, and put back when it is connected again.
Signals it raises:
- Something Maplith relies on stopped working (checked on a schedule): the daily check finds the token refused, a scope missing, or every selected channel out of reach
- A connected system grew or shrank (checked on a schedule): the connection offers at least a quarter more or fewer resources than at the last check
- A process is no longer found (checked on a schedule): a recurring process the map found in Slack has not happened within its usual interval
- New finding (checked on a schedule): 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 check (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 “Something Maplith relies on stopped working” signal is raised.
- Share the system Slack names. Starts when a finding says Slack names a system the map does not have.
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
Always
- Read-only, and never a credential sent to Maplith through a chat.
- The same recent period, a few months, from every system.
- You decide what goes in.
Sources
Written from public documentation, last checked 2026-10-14: