Continuously ingest Slack messages into CortexDB as experiences.

Slack Connector

The Slack connector tails messages from configured channels and writes them to CortexDB as conversation experiences. Threads, file shares, and reactions are preserved as metadata.

Info

Two ways to run this connector:

  • Run it yourself (Free + paid) — pip install 'cortexdb-connectors[slack]' then cortexdb-sync sync slack. The connector reads your token from ~/.cortexdb/state.json (written by cortexdb init) or from env vars.
  • Managed sync (Starter and up) — CortexDB runs the connector as a worker on its infrastructure. Configure it once from your dashboard; CortexDB handles webhook registration, retries, backfill, and idempotency.

1. Prepare credentials in Slack

  1. api.slack.com/apps → create a new app from scratch.
  2. Add Bot Token Scopes:
    • channels:history — read public channels
    • channels:read — view channel info
    • groups:history — read private channels (optional)
    • users:read — resolve author names
  3. Install the app to your workspace.
  4. Copy the Bot User OAuth Token (xoxb-...).

2. Configure in your CortexDB dashboard

  1. Sign in at cortexdb.ai/login.
  2. Settings → Connectors → Add Connector → Slack.
  3. Paste the Bot OAuth token from step 1.
  4. Choose the channels to sync (default: all public). Comma-separated, e.g. #engineering, #product, #incidents.
  5. Set the scope template. Default: org:<your-org>/source:slack/channel:{channel}. Placeholders available: {channel}, {author}, {workspace}, {thread_ts}.
  6. Pick sync mode: Real-time (Slack Events API webhook) or Polling (default 10 s).
  7. Optionally enable Include bots and adjust the Backfill window (default 30 days).
  8. Click Start sync.

The dashboard provisions a worker, runs the historical backfill (preserving original message timestamps as observed_at for bi-temporal correctness), and shows live throughput on the connector detail page.

What gets written

Each Slack message becomes a POST /v1/experience call against the resolved scope:

{
  "scope":    "org:acme/source:slack/channel:engineering",
  "modality": "conversation",
  "observed_actor": "user:[email protected]",
  "content": {
    "kind": "message",
    "role": "user",
    "text": "We should migrate the payments service to CockroachDB."
  },
  "context": {
    "observed_at": "2026-03-15T10:30:00.123Z",
    "labels":      ["channel:engineering", "workspace:acme-corp"],
    "intent":      "discussion"
  },
  "idempotency_key": "slack:T01:C123:1710502200.000100"
}
Slack eventMaps to
Channel messageexperience with content.kind=message
Thread replySame, plus context.preceded_by=[<parent event_id>] once the parent has been captured
File shareexperience with content.kind=blob_ref (file uploaded via POST /v1/blobs first)
ReactionsAggregated and emitted as experience with modality=feedback
Bot messagesSkipped by default; toggle "Include bots" in the dashboard to enable

idempotency_key shape: slack:<team>:<channel>:<ts> — retries and backfills write once.

Permissions

CortexDB mints a service actor for the connector with scope.write on your target scope. The actor is managed for you — no token handling, no secrets in your environment.

Run it yourself

If you'd rather host the connector yourself instead of using CortexDB's managed worker, every connector ships in the cortexdb-connectors PyPI package:

pip install 'cortexdb-connectors[slack]'

# Step 1: get a CortexDB token + actor (one-time, free tier)
pip install cortexdb-cli
cortexdb init

# Step 2: supply the connector's third-party credentials
export SLACK_BOT_TOKEN=...                # required

# Step 3: one-shot sync, or `watch` for a poll loop
cortexdb-sync sync slack
cortexdb-sync watch slack --interval 60

cortexdb-sync reads your CortexDB token + actor from ~/.cortexdb/state.json automatically. Cursor state is persisted in ~/.cortexdb/connectors-state.json, so re-running picks up where the last cycle left off.

See also