> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toktra.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack

> Install the Toktra Slack app to surface usage data, alerts, and reimbursement workflows directly in Slack.

The Toktra Slack app brings LLM usage monitoring into your team's daily workflow. Security alerts appear in channels as they fire, and managers can approve or reject reimbursement requests without leaving Slack.

***

## Installing the Toktra Slack app

<Steps>
  <Step title="Start the OAuth flow">
    In your Toktra dashboard, go to **Integrations → Slack** (`/integrations/slack`). Click **Install to Slack**.

    Toktra redirects you to Slack's OAuth authorization page at `https://slack.com/oauth/v2/authorize`.
  </Step>

  <Step title="Authorize the app">
    Review the requested permissions and click **Allow**. The Toktra app requests the following scopes:

    | Scope                             | Purpose                         |
    | --------------------------------- | ------------------------------- |
    | `app_mentions:read`               | Respond to `@Toktra` mentions   |
    | `chat:write`                      | Post messages and alerts        |
    | `commands`                        | Register slash commands         |
    | `channels:read`                   | List channels for alert routing |
    | `im:read` + `im:write`            | Send direct messages            |
    | `users:read` + `users:read.email` | Map Slack users to Toktra users |
  </Step>

  <Step title="Confirm installation">
    Slack redirects back to Toktra at `/integrations/slack/oauth/callback`. Toktra stores the workspace access token and shows a confirmation.
  </Step>

  <Step title="Configure notification channels">
    In **Integrations → Slack**, select the channels where you want alert notifications sent. See [Setting up alert channels](#setting-up-alert-channels).
  </Step>
</Steps>

<Note>
  Only Toktra admins can install the Slack app. The app is installed per Slack workspace. If your organization uses multiple workspaces, repeat the installation for each one.
</Note>

***

## Slash commands

After installation, the following slash commands are available to all workspace members.

### `/toktra-usage`

Shows the calling user's token usage for the current billing period, formatted as a Slack Block Kit card.

```
/toktra-usage
/toktra-usage alice@company.com
```

Pass an email address to look up another user's usage (admin only). The response is ephemeral — only you can see it.

**Example output:**

```
Usage Summary — Alice Smith
Period: January 2025
─────────────────────────────
Provider       Tokens      Cost
OpenAI         1,240,500   $24.81
Anthropic        380,200    $3.80
─────────────────────────────
Total          1,620,700   $28.61
```

***

### `/toktra-budget`

Shows the organization's current budget status and remaining allocation.

```
/toktra-budget
```

The response includes a visual progress bar that changes color based on spend percentage:

* Green — below 75%
* Orange — 75–90%
* Red — above 90%

**Example output:**

```
Budget Status
────────────────────────────────────
Monthly limit:     $10,000
Spent:             $7,520 (75.2%)
Remaining:         $2,480
Alert threshold:   80%

🟠 ███████████████░░░░░ 75.2%
```

***

### `/toktra-alerts`

Lists recent policy violation alerts for your organization.

```
/toktra-alerts
/toktra-alerts severity:high
/toktra-alerts severity:critical limit:5
```

**Arguments:**

| Argument           | Description                                       |
| ------------------ | ------------------------------------------------- |
| `severity:<level>` | Filter by `low`, `medium`, `high`, or `critical`  |
| `limit:<n>`        | Number of alerts to return (default: 10, max: 50) |

Each alert is rendered as a Block Kit card with **Acknowledge** and **Create ticket** action buttons.

***

## Interactive actions

### Acknowledge alerts

Click **Acknowledge** on any alert card from `/toktra-alerts` or a channel notification. Toktra marks the alert as acknowledged and updates the card to show who acknowledged it.

### Approve or reject reimbursements

When an employee submits a personal usage reimbursement request, the assigned approver receives a Slack DM with the request details and two action buttons:

* **Approve** — marks the request as approved and queues it for payroll export
* **Reject** — marks the request as rejected and notifies the employee

<Tip>
  Managers can also approve and reject requests from the Toktra dashboard at **Reimbursements → Approvals**.
</Tip>

### Create ITSM tickets from Slack

Click **Create ticket** on any alert card to open an ITSM ticket directly. Toktra creates the ticket in your configured ITSM connector (ServiceNow or Jira) and replies with the ticket URL.

<Note>
  The **Create ticket** button is available on alert cards when at least one active ITSM connector is configured. See [ITSM integration](/integrations/itsm).
</Note>

***

## Setting up alert notification channels

After installing the Toktra app, configure which Slack channels receive alert notifications:

<Steps>
  <Step title="Open channel settings">
    Go to **Integrations → Slack → Alert channels** and click **Add channel**.
  </Step>

  <Step title="Select a channel">
    Choose a public channel from the dropdown, or type a channel name. Toktra must be invited to private channels before they appear.
  </Step>

  <Step title="Set severity filter">
    Choose which severity levels trigger notifications in this channel. For example, route `critical` alerts to `#security-incidents` and `high` alerts to `#it-alerts`.
  </Step>

  <Step title="Save">
    Click **Save**. Toktra immediately starts routing alerts matching your filter to the channel.
  </Step>
</Steps>

You can configure multiple channels with different severity filters. Alerts that match multiple filters are delivered to all matching channels.

***

## Environment variables

The Toktra Slack app requires the following environment variables in the `integrations/slack` service:

```bash title="Slack environment variables" theme={null}
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_SIGNING_SECRET=your-signing-secret
SLACK_CLIENT_ID=your-client-id
SLACK_CLIENT_SECRET=your-client-secret
SLACK_APP_TOKEN=xapp-your-app-token   # Required for Socket Mode
```

<Warning>
  Toktra verifies the `X-Slack-Signature` header on every incoming event, action, and command. Never disable signature verification in production.
</Warning>