# Slack Collaboration API

## Available Tools

| Tool | Description |
|------|-------------|
| `slack_search_messages` | Search Slack messages by query |
| `slack_list_channels` | List/search Slack channels |
| `slack_ask` | Natural language Slack queries with smart routing |
| `slack_get_latest_messages` | Get recent messages from a channel |
| `slack_get_file` | Download a Slack file by ID |
| `slack_check_scopes` | Check OAuth token scopes |
| `slack_list_users` | **NEW** — List workspace users with account status |
| `slack_get_user` | **NEW** — Exact user lookup by ID, email, or username |

---

## slack_list_users

Workspace user list with full account-status flags. Exposes the **actual deleted/deactivated** flag from Slack — does not infer status from message activity or channel membership.

**No pagination — every matching user is returned in a single response.** The tool internally scans the ENTIRE workspace, applies all filters, and returns the full `rows[]` array with an accurate `total_matched` count. `is_complete` is always `true`. Keep `include_details` off (default) for bulk queries to keep the payload small.

### Request

```bash
curl -X POST {{base_url}}/internal/v1/tools/slack_list_users \
  -H "Authorization: Bearer {{s2s_token}}" \
  -H "X-Lucos-Org-Id: {{org_id}}" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "staging",
    "args": {
      "include_deactivated": true
    }
  }'
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `status` | string | `all` | `active` \| `deactivated` \| `all` — `deactivated` returns ONLY deactivated users |
| `user_type` | string | `all` | `bot` \| `guest` \| `external` \| `admin` \| `human` |
| `name_prefix` | string | — | Case-insensitive prefix match against username/real name/display name (e.g. "names starting with S") |
| `include_deactivated` | boolean | true | Include deleted/deactivated users (ignored if `status` is set) |
| `include_details` | boolean | false | Include `tz`/`tz_label`/`avatar_url` (larger payload — omit for bulk lists) |
| `updated_after` / `updated_before` | ISO date | — | Filters on Slack's profile last-updated time. **Not a deactivation date** — Slack has no such field |

### Response Fields (per user)

| Field | Type | Description |
|-------|------|-------------|
| `user_id` | string | Slack user ID (e.g., `U1234567890`) |
| `username` | string | Slack username |
| `email` | string | Primary email address |
| `real_name` | string | Full name |
| `display_name` | string | Display name in Slack |
| `title` | string | Profile title |
| **`deleted`** | boolean | **Account deleted/deactivated flag** |
| **`deactivated`** | boolean | **Same as deleted — explicit alias** |
| `is_bot` | boolean | Bot user flag |
| `is_app_user` | boolean | App user flag |
| `is_guest` | boolean | Guest user (restricted or ultra-restricted) |
| `is_multi_channel_guest` | boolean | Multi-channel guest |
| `is_single_channel_guest` | boolean | Single-channel guest |
| `is_external` | boolean | External/Connect user |
| `is_owner` | boolean | Workspace owner |
| `is_admin` | boolean | Workspace admin |
| `is_primary_owner` | boolean | Primary workspace owner |
| `is_restricted` | boolean | Restricted user flag |
| `is_ultra_restricted` | boolean | Ultra-restricted user flag |
| `updated_at` | string | Last profile-change time (not a deactivation date) |
| `tz` / `tz_label` / `avatar_url` | | Only present when `include_details: true` |

### Response Metadata

| Field | Description |
|-------|-------------|
| `as_of` | ISO timestamp of the API call |
| `result_count` / `total_matched` | Count of users in `rows[]` — always the full filtered count (same value, no partial pages) |
| `is_complete` | Always `true` |
| `guidance` | Human/LLM-readable confirmation that this is the full list |

### Example Response

```json
{
  "ok": true,
  "tool": "slack_list_users",
  "source": "collaboration",
  "environment": "staging",
  "result_count": 2,
  "total_matched": 2,
  "is_complete": true,
  "guidance": "COMPLETE RESULT: all 2 matching users are included in rows[]. No pagination — this is the full list.",
  "as_of": "2026-09-01T12:00:00.000Z",
  "include_deactivated": true,
  "status": "all",
  "user_type": "all",
  "name_prefix": null,
  "rows": [
    {
      "user_id": "U0123456789",
      "username": "danny",
      "email": "danny@admedia.com",
      "real_name": "Danny Patel",
      "display_name": "Danny",
      "title": "Engineering Lead",
      "deleted": false,
      "deactivated": false,
      "is_bot": false,
      "is_app_user": false,
      "is_guest": false,
      "is_multi_channel_guest": false,
      "is_single_channel_guest": false,
      "is_external": false,
      "is_owner": false,
      "is_admin": true,
      "is_primary_owner": false,
      "is_restricted": false,
      "is_ultra_restricted": false,
      "tz": "America/Los_Angeles",
      "tz_label": "Pacific Daylight Time",
      "avatar_url": "https://avatars.slack-edge.com/..."
    },
    {
      "user_id": "U9876543210",
      "username": "john.doe",
      "email": "john@admedia.com",
      "real_name": "John Doe",
      "display_name": "",
      "title": "",
      "deleted": true,
      "deactivated": true,
      "is_bot": false,
      "is_app_user": false,
      "is_guest": false,
      "is_multi_channel_guest": false,
      "is_single_channel_guest": false,
      "is_external": false,
      "is_owner": false,
      "is_admin": false,
      "is_primary_owner": false,
      "is_restricted": false,
      "is_ultra_restricted": false,
      "tz": null,
      "tz_label": null,
      "avatar_url": null
    }
  ]
}
```

---

## slack_get_user

Exact user lookup by ID, email, or username. Returns full account-status details for a single user.

### Request (by user ID)

```bash
curl -X POST {{base_url}}/internal/v1/tools/slack_get_user \
  -H "Authorization: Bearer {{s2s_token}}" \
  -H "X-Lucos-Org-Id: {{org_id}}" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "staging",
    "args": {
      "user_id": "U0123456789"
    }
  }'
```

### Request (by email)

```bash
curl -X POST {{base_url}}/internal/v1/tools/slack_get_user \
  -H "Authorization: Bearer {{s2s_token}}" \
  -H "X-Lucos-Org-Id: {{org_id}}" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "staging",
    "args": {
      "email": "danny@admedia.com"
    }
  }'
```

### Request (by username)

```bash
curl -X POST {{base_url}}/internal/v1/tools/slack_get_user \
  -H "Authorization: Bearer {{s2s_token}}" \
  -H "X-Lucos-Org-Id: {{org_id}}" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "staging",
    "args": {
      "username": "danny"
    }
  }'
```

### Parameters (one required)

| Parameter | Type | Description |
|-----------|------|-------------|
| `user_id` | string | Slack user ID (e.g., `U1234567890`) |
| `email` | string | User's primary email |
| `username` | string | Slack username (with or without `@`) |

### Example Response

```json
{
  "ok": true,
  "tool": "slack_get_user",
  "source": "collaboration",
  "environment": "staging",
  "as_of": "2026-09-01T12:00:00.000Z",
  "user": {
    "user_id": "U0123456789",
    "username": "danny",
    "email": "danny@admedia.com",
    "real_name": "Danny Patel",
    "display_name": "Danny",
    "title": "Engineering Lead",
    "deleted": false,
    "deactivated": false,
    "is_bot": false,
    "is_app_user": false,
    "is_guest": false,
    "is_multi_channel_guest": false,
    "is_single_channel_guest": false,
    "is_external": false,
    "is_owner": false,
    "is_admin": true,
    "is_primary_owner": false,
    "is_restricted": false,
    "is_ultra_restricted": false,
    "tz": "America/Los_Angeles",
    "tz_label": "Pacific Daylight Time",
    "avatar_url": "https://avatars.slack-edge.com/..."
  }
}
```

### User Not Found Response

```json
{
  "ok": false,
  "tool": "slack_get_user",
  "source": "collaboration",
  "environment": "staging",
  "error": "user_not_found",
  "message": "No user found matching the provided criteria",
  "as_of": "2026-09-01T12:00:00.000Z"
}
```

---

## MCP Tool Schemas

For MCP servers that need tool definitions:

### slack_list_users

```json
{
  "name": "slack_list_users",
  "description": "List Slack workspace users with full account-status flags. Returns the actual deleted/deactivated flag from Slack (not inferred from activity). Scans the ENTIRE workspace and returns ALL matching users in a single response (no pagination) — total_matched/result_count are always the full filtered count.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "environment": {
        "type": "string",
        "description": "Environment (staging, prod)"
      },
      "args": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "'active' | 'deactivated' | 'all' (default). 'deactivated' returns ONLY deactivated users."
          },
          "user_type": {
            "type": "string",
            "description": "'bot' | 'guest' | 'external' | 'admin' | 'human'"
          },
          "name_prefix": {
            "type": "string",
            "description": "Case-insensitive prefix match against username/real name/display name"
          },
          "include_deactivated": {
            "type": "boolean",
            "description": "Include deleted/deactivated users (default true, ignored if status is set)"
          },
          "include_details": {
            "type": "boolean",
            "description": "Include tz/tz_label/avatar_url (default false to keep bulk payloads small)"
          },
          "updated_after": {
            "type": "string",
            "description": "ISO date filter on Slack's profile last-updated time (not a deactivation date)"
          },
          "updated_before": {
            "type": "string",
            "description": "ISO date filter on Slack's profile last-updated time (not a deactivation date)"
          }
        }
      }
    },
    "required": ["environment"]
  }
}
```

### slack_get_user

```json
{
  "name": "slack_get_user",
  "description": "Exact Slack user lookup by ID, email, or username. Returns user_id, username, email, real/display name, title, and the actual deleted/deactivated flag. Also returns bot/app, guest, external, admin, owner, and restricted-user flags.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "environment": {
        "type": "string",
        "description": "Environment (staging, prod)"
      },
      "args": {
        "type": "object",
        "properties": {
          "user_id": {
            "type": "string",
            "description": "Slack user ID (e.g., U1234567890)"
          },
          "email": {
            "type": "string",
            "description": "User's primary email address"
          },
          "username": {
            "type": "string",
            "description": "Slack username (with or without @)"
          }
        }
      }
    },
    "required": ["environment"]
  }
}
```

---

## Required Scopes

Both tools require the `users:read` and `users:read.email` OAuth scopes on the Slack token.