# Runbook: move a Slack workspace to Bundle

> For AI agents acting for a Bundle owner or admin. Human version: https://bundle.direct/blog/migrate-from-slack
> Last checked against Bundle on 2026-10-25.

## Goal

Copy a Slack workspace's channels, DMs, threads, files and canvases into a Bundle workspace, then let each person bring their own private conversations. Slack is only read; nothing changes there.

## How you act

- Imports run in the Bundle web app at https://app.bundle.direct, signed in as an **owner or admin** (Settings → Import). Guests, deactivated members and agent or bot tokens (`bxb-…`) are refused by the import API.
- Drive the user's own signed-in browser session. Don't create Bundle or Slack accounts.
- **Never ask the user to paste a token, password or secret into the chat.** When a secret has to go into a field, either let the human paste it into the field themselves, or use a password-manager or secret-handoff tool that fills the field without revealing the value to you. Don't echo secrets in logs or messages.

## Prerequisites

- [ ] A Bundle workspace, and the user is an owner or admin in it.
- [ ] The user is a Slack workspace owner or admin (needed to export, or to install a Slack app).
- [ ] Decide the source:
  - **Token (recommended):** reads public channels plus the token owner's private channels, DMs and group DMs; turns canvases into pages.
  - **Export zip:** ≤ 1 GB; Slack Free/Pro exports have public channels only; Business+/Enterprise exports may include `groups.json`, `mpims.json`, `dms.json`.
- [ ] No other workspace import is running (only one at a time; a second one gets HTTP 409).

## Steps

### A. Token source

1. Open `https://app.bundle.direct/<workspace>/settings/import`. Choose **Slack**, then **Connect with a token**.
2. Click **Create the Slack app**. It opens `https://api.slack.com/apps?new_app=1&manifest_json=…` with the "Bundle import" manifest (user scopes, all read-only: `channels:history channels:read groups:history groups:read im:history im:read mpim:history mpim:read users:read users:read.email files:read team:read`).
3. **Human step:** in Slack, the user creates the app from the manifest and installs it to the workspace (Slack shows an OAuth consent screen; a Slack admin may need to approve the app).
4. **Human step (secret):** the user copies the **User OAuth Token** (`xoxp-…`) from the app's OAuth & Permissions page and puts it in Bundle's **Slack user token** field. Then click **Connect**.
5. Wait for the scan. The page shows the review.

### B. Export source

1. **Human step:** in Slack, **Workspace settings → Import/Export data → Export**, date range **Entire history**. Slack emails a download link to the owner.
2. In Bundle **Settings → Import → Slack → Export file**, upload the `.zip` (must end in `.zip`, ≤ 1 GB, contain `users.json` or `org_users.json` and `channels.json`).

### C. Review (both sources)

Confirm these with the user before clicking **Import**; they decide who gets invited and emailed:

1. **Copy attached files into Bundle**: on (default) unless the user wants links to Slack.
2. **People**: for each person the dropdown is a matched member, **Invite to Bundle**, **Invite as external guest (Org)**, **Keep as deactivated profile** or **Keep as name only**. Bots can only be name only; invites need an email. **Invite everyone missing** fills the rest.
3. **People from other companies only get the channels they were in**: keep on.
4. **Email the invites now**: ask the user. Off means accounts and pending invites are still created; invites can be sent later from Settings → Invitations (Resend).
5. **Channels**: all ticked by default (archived too). A name already used by a non-empty Bundle channel is imported as `<name>-slack`; two picked channels with the same final name block the start.
6. **Direct messages**: off by default. A DM only comes over if everyone in it maps to someone in Bundle.
7. **Conversations with apps**: off by default.
8. Click **Import**. A review left untouched expires after 7 days.

### D. Personal imports (each person's private conversations)

1. Admin, once: **Settings → Import → Slack → Connect with a token → Let people import their own Slack messages**. Use that section's create-app button (the manifest includes Bundle's redirect URL `https://app.bundle.direct/v1/imports/slack/callback`), install the app.
2. **Human step (secret):** the admin copies **Client ID** and **Client Secret** from the Slack app's **Basic Information** into Bundle and clicks **Connect the app**. Bundle shows "Connected (Client ID …)".
3. Each person, in their own session: **Settings → Data → Import my Slack conversations → Connect with Slack**. **Human step:** Slack OAuth consent (the link expires in 10 minutes). Then they pick conversations and import. You can't do this on someone else's behalf.

### E. Clean-up of files still linked to Slack (optional, later)

Settings → Import → Slack → Connect with a token, turn on **Only bring over files still linked to Slack**, provide a token (human step), Connect. Nothing new is imported; messages already in Bundle get their files, canvases become pages, and the timeline explains failures (`fileNotFound`, `fileNoAccess`, `fileTooBig` over 1 GB, `canvasUnreadable`).

## What comes over / what doesn't

- Comes over: public and private channels (topic, purpose, members, archived), DMs and group DMs (when everyone maps), threads (incl. replies sent to channel), original timestamps (as read, no notifications), latest text of edited messages, reactions from mapped people (≤ 50 emoji per message), mentions, files (copied when downloadable; over 1 GB stay links), canvases/posts as pages (token imports and the clean-up job only), bot/workflow messages under the bot's name, avatars.
- Doesn't: pins, bookmarks, custom emoji images, user groups, workflows/apps configuration, edit history, reactions from unmapped people, huddles, Lists, scheduled messages, sidebar sections, saved items, join/leave and topic-change notices, link unfurls.
- Google Drive and other external files are never downloaded; messages keep a link (the clean-up points it at the original Drive URL). Bundle has no Google Drive access.

## Under the hood (signed-in session only)

The web app calls these with the user's session; bot tokens can't. Prefer the UI.

- `GET /v1/w/:ws/imports` (list), `POST /v1/w/:ws/imports` (create → scanning), `GET /v1/w/:ws/imports/:id` (status and preview), `POST /v1/w/:ws/imports/:id/start`, `POST /v1/w/:ws/imports/:id/cancel`, `POST /v1/w/:ws/imports/:id/rescan`
- `GET|PUT /v1/w/:ws/imports-slack-app` (personal-import app settings), `POST /v1/w/:ws/imports-slack-connect` (Slack OAuth URL), `GET /v1/w/:ws/my-imports`

## Verify

1. Settings → Import: the job shows **Imported** (statuses: Reading → Waiting for review → Importing → Imported, or Failed / Cancelled); read its timeline for skipped items and warnings.
2. Open the three busiest channels; spot-check thread replies, file attachments and dates.
3. Check Settings → Members / Invitations / Guests match the review choices; external people carry the External badge and only their channels.
4. If the workspace has a Bundle app with `channels:read` and `channels:history`, `POST https://app.bundle.direct/api/conversations.list` and `/api/conversations.history` (Bearer `bxb-…`) can confirm channel counts and recent messages.

## Rollback

- Slack is unchanged. To stop: **Stop import** in Settings → Import (`POST …/cancel`); what's already imported stays.
- Remove what you don't want in Bundle: archive or delete imported channels, revoke pending invites in Settings → Invitations, deactivate guests.
- The Slack token is deleted when the job ends. Afterwards the user can delete the "Bundle import" app in Slack (api.slack.com/apps → the app → Delete App).
