Slack

1. Sign in at api.slack.com/apps and click Create New App → From scratch. Give it a name (e.g. Ingest) and pick the workspace you want to sync.
2. In the left sidebar, open OAuth & Permissions.
3. Under Scopes → Bot Token Scopes, add the following scopes. Skip any you don't need — each one unlocks a specific group of endpoints (see "Pick endpoints" below):
   • channels:read, channels:history, channels:join — public channels and their messages.
   • groups:read, groups:history — private channels.
   • im:read, im:history — direct messages.
   • mpim:read, mpim:history — group direct messages.
   • users:read, users:read.email, users.profile:read — workspace members and their profile fields.
   • usergroups:read — user groups (Standard plan and above).
   • files:read — uploaded files and file metadata.
   • emoji:read — custom emoji.
   • pins:read — pinned items in channels.
   • reactions:read — reaction activity.
   • team:read — workspace identity and profile field definitions.
   • dnd:read — Do Not Disturb status.
   • chat:write — scheduled-message lookups (also needed if you ever want the connector to post on behalf of the app).
4. If you plan to enable search_messages or search_files, scroll to User Token Scopes and add search:read. Search is only available with a user token — Slack does not offer it to bot tokens.
5. Scroll up to the top of OAuth & Permissions and click Install to Workspace. Approve the permissions prompt.
6. Once installed, the page shows:
   • Bot User OAuth Token — starts with xoxb-. Copy this.
   • User OAuth Token — starts with xoxp-. Copy this only if you added user-token scopes in step 4 or plan to use the admin endpoints.

If you'll be syncing private channels, direct messages, or group DMs, the bot also needs to be invited to each conversation — Slack only returns history for channels the bot is a member of. From any Slack channel, type /invite @YourAppName to add it.

In the Ingest UI under Connectors → Slack, paste the bot token. If you're using search or the admin-only endpoints, also paste the user token in the optional field. Ingest stores both in AWS Secrets Manager — the bot token under the key bot_token and the user token under user_token — and sends each as an Authorization: Bearer <token> header on the calls that need it.

Slack rate-limits each method independently, per workspace, per app. The Web API documents four standard tiers — Tier 1 at 1+ request/min, Tier 2 at 20+/min, Tier 3 at 50+/min, and Tier 4 at 100+/min — and the Ingest runtime dispatches each endpoint at its documented tier with AIMD backoff on 429s.

There is one important exception. As of 2025-05-29, Slack clamps conversations.history and conversations.replies to 1 request per minute with limit=15 for newly created, commercially distributed apps that have not been approved for the Slack Marketplace. The Ingest connector is not Marketplace-distributed, so it encodes this clamp directly: long historical backfills of channel history are slow by design, and you should keep your lookback window short (the default is 30 days). If you need higher throughput, listing the app on the Slack Marketplace lifts the clamp back to Tier 3.

Errors with status 400 (malformed request), 401 (invalid or expired token), 403 (missing scope, paid feature on a free workspace, or bot not a member of the channel), and 404 (resource not found) are treated as fatal — the request stops without retry. Status 429 triggers an exponential-backoff retry, and transient 500/502/503/504 errors retry as well.

The Slack catalog spans 27 endpoints. Most workspaces start with the workspace dimensions and channel-message endpoints and add the rest as their analytical needs grow:

• Workspace dimensions (almost always required): team, users, conversations, emoji.
• Messaging: conversation_history, conversation_replies (both subject to the Marketplace clamp), conversation_members, pins, reactions.
• Files: files, file_info.
• User detail enrichment: user_info, user_profile, user_presence, user_conversations.
• Org graph: usergroups, usergroup_users, dnd, dnd_team_info. User groups require Slack's Standard plan or above.
• Scheduled messages: chat_scheduled_messages.
• Advanced (user token required): search_messages, search_files. Both require the search:read scope on a user token — Slack does not offer search to bot tokens.
• Enterprise Grid only: team_access_logs, team_integration_logs, team_billable_info. Each requires the admin scope on a user token belonging to a workspace admin on a paid plan. Untested in the standard Ingest install.