Skip to content

slack_connector

diapason.connectors.slack_connector

Slack connector — bulk channel message sync via the Slack Web API.

Uses a Slack user OAuth token (xoxp-...) stored locally so the sync sees everything the user can see — including their 1:1 DMs and multi-person DMs with other humans. A bot token (xoxb-) cannot see user-to-user DMs (Slack platform constraint), so this connector explicitly rejects bot tokens with a clear error at connect time.

All network calls are isolated in module-level functions (_slack_api_*) to make them trivially mockable in tests.

SlackConnector

Bases: BaseConnector

Connector that syncs channel message history from Slack via the Web API.

Authentication is handled through Slack OAuth 2.0. Tokens are stored locally in a JSON credentials file.

Parameters

credentials_path: Path to the JSON file where OAuth tokens are stored. Defaults to ~/.diapason/connectors/slack.json.

auth_url()

Return a Slack OAuth consent URL requesting user-token scopes.

Uses user_scope (not scope) so the install grants a User OAuth Token (xoxp-) — bot tokens (xoxb-) can't see human- to-human DMs and are rejected by :func:handle_callback.

Without a stored client_id, this returns the Slack app dashboard rather than a consent URL — the same rule the Google connectors follow. A consent URL with an empty client_id is not degraded, it is broken: Slack answers invalid_client_id, and the user goes looking for the fault on their own side.

Note that unlike Google, Slack has no entry in OAUTH_PROVIDERS: there is no server-side /oauth/start path for it, so this URL is the only one on offer.

disconnect()

Delete the stored credentials file.

handle_callback(code)

Validate and persist a supplied User OAuth Token.

The connector /connect endpoint funnels manually-pasted tokens through this method (the parameter is named code for OAuth-flow compatibility). The token is checked two ways before it is allowed to touch disk, so an invalid credential never overwrites a working one:

  1. Shape — must start with xoxp- (xoxb- bot tokens and any other prefix are rejected via :func:_validate_user_token).
  2. Liveness — a live auth.test call must return ok so an expired or revoked token is caught at connect time.

is_connected()

Return True if a credentials file with a valid token exists.

mcp_tools()

Expose three MCP tool specs for real-time Slack queries.

sync(*, since=None, cursor=None)

Yield :class:Document objects for every accessible Slack message.

With a user OAuth token (xoxp-) the listing returned by conversations.list already reflects what the user can see — no conversations.join step, no membership filtering. We enumerate every conversation first (so the per-type count can be logged up front), then stream history for each one.

Parameters

since: Not yet used (reserved for incremental sync). cursor: Not yet used (reserved for pagination resumption).

sync_status()

Return sync progress from the most recent :meth:sync call.

SlackTokenError

Bases: ValueError

Raised when the stored Slack token isn't a usable user token.

Surfaced via :class:SyncStatus.error so the UI can render the actual reason (e.g. xoxb- bot token rejected) instead of an empty sync.