Slack Integration

Overview

Orcha integrates with Slack to provide a conversational interface for data queries, approvals, document uploads, and proactive notifications. Slack acts purely as the UI layer—all processing, classification, and workflow orchestration happens in the Orcha backend.

Architecture

Hybrid Routing Model

The integration uses a hybrid approach combining deterministic routing for structured actions with an LLM-powered agent for conversational queries:

┌─────────────────────────────────────────────────────────────────────┐
│                         SLACK WORKSPACE                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │
│  │ Slash Cmds   │  │ File Uploads │  │ Natural Language Msgs    │  │
│  │ /purchase    │  │ (images,docs)│  │ "@orcha what invoices..."│  │
│  │ /budget      │  │              │  │                          │  │
│  │ /report      │  │              │  │                          │  │
│  └──────┬───────┘  └──────┬───────┘  └────────────┬─────────────┘  │
│         │                 │                        │                 │
│  ┌──────┴─────────────────┴────────────────────────┴─────────────┐  │
│  │                    Slack Bot (Orcha)                          │  │
│  │              Receives events, forwards to backend              │  │
│  └──────────────────────────┬────────────────────────────────────┘  │
│                             │                                        │
└─────────────────────────────┼────────────────────────────────────────┘
                              │ HTTPS / WebSocket
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        ORCHA BACKEND                                 │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌────────────────────────────────────────────────────────────────┐ │
│  │                    Slack Gateway Service                        │ │
│  │  - Authenticates requests (maps Slack user → Orcha user)       │ │
│  │  - Routes by interaction type                                   │ │
│  │  - Enforces role-based permissions                              │ │
│  └───────┬──────────────────┬──────────────────┬──────────────────┘ │
│          │                  │                  │                     │
│          ▼                  ▼                  ▼                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │
│  │ Command      │  │ Document     │  │ Conversational Agent     │  │
│  │ Handlers     │  │ Processor    │  │ (LLM + Constrained Tools)│  │
│  │ (determin.)  │  │ (OCR, class.)│  │                          │  │
│  └──────────────┘  └──────────────┘  └──────────────────────────┘  │
│          │                  │                  │                     │
│          └──────────────────┴──────────────────┘                     │
│                             │                                        │
│                             ▼                                        │
│  ┌────────────────────────────────────────────────────────────────┐ │
│  │                 Slack Response Builder                          │ │
│  │  - Formats Block Kit messages                                   │ │
│  │  - Attaches action buttons (approve/reject)                     │ │
│  │  - Includes source links and citations                          │ │
│  └────────────────────────────────────────────────────────────────┘ │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Why Hybrid?

Multi-Tenancy

• One Slack workspace per Orcha tenant
• Each customer connects their Slack workspace via OAuth
• Slack user IDs are mapped to Orcha user accounts during workspace connection
• All requests are scoped to the tenant's data

Workspace Connection Flow

1. Orcha admin initiates Slack connection from Orcha settings
2. OAuth flow grants Orcha bot access to workspace
3. Users link their Slack accounts to Orcha accounts (SSO or manual)
4. Bot is added to relevant channels or users interact via DM

Role-Based Access Control

The Slack integration mirrors Orcha's existing role system. The Slack Gateway Service enforces permissions before executing any action or query.

Slash Commands (Deterministic Routing)

Slash commands provide structured entry points for common actions. These bypass the LLM entirely for speed and predictability.

/purchase - Create Purchase Request

Opens a modal to create a new purchase request.

/purchase

Modal Fields:

• Supplier (autocomplete from existing suppliers or free text)
• Description
• Amount
• Currency
• Cost center (dropdown based on user's access)
• Urgency (normal, urgent)
• Attachments (optional)

Response: Confirmation with request ID, assigned approver, and status tracker.

/budget - Check Budget Status

Quick view of budget utilization.

/budget [cost-center]

Response (example):

📊 Marketing Budget (Q1 2026)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Budget:    €50,000
Spent:     €32,450 (65%)
Committed: €8,200
Available: €9,350
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░ 65%

[View Details in Orcha]

Permission: Only shown to users with budget visibility for the requested cost center.

/report - Request Report

Generate or retrieve reports on-demand.

/report [report-type]

Available report types:

• spending - Spending summary for user's scope
• approvals - Pending approvals summary
• renewals - Upcoming contract renewals
• invoices - Open invoices summary

/approvals - List Pending Approvals

Quick view of items awaiting user's approval.

/approvals

Response: List of pending items with inline approve/reject buttons.

/help - Command Reference

/help

Shows available commands and example natural language queries.

Natural Language Queries (LLM Agent)

For conversational interactions, users mention the bot or send DMs. The LLM agent processes these with constrained tools.

Triggering the Agent

• Channel: @orcha <query>
• DM: Direct message to Orcha bot
• Thread reply: Continue conversation in thread

Agent Architecture

┌─────────────────────────────────────────────────────────────┐
│                  Conversational Agent                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌────────────────────────────────────────────────────────┐ │
│  │                   System Prompt                         │ │
│  │  - Role: Orcha assistant for financial/procurement     │ │
│  │  - Constraints: Only use provided tools, cite sources  │ │
│  │  - Context: User role, permissions, tenant             │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐ │
│  │                   Tool Definitions                      │ │
│  │                                                         │ │
│  │  search_invoices(query, status?, date_range?)          │ │
│  │  search_contracts(query, status?, renewal_date?)       │ │
│  │  search_suppliers(query)                                │ │
│  │  search_expenses(query, status?, submitter?)           │ │
│  │  search_purchase_requests(query, status?)              │ │
│  │  get_budget_status(cost_center)                        │ │
│  │  get_pending_approvals()                                │ │
│  │  get_contract_details(contract_id)                     │ │
│  │  get_invoice_details(invoice_id)                       │ │
│  │  get_supplier_details(supplier_id)                     │ │
│  │                                                         │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐ │
│  │              Permission Enforcement                     │ │
│  │  Tools are filtered based on user's role               │ │
│  │  Query results are scoped to user's access             │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Example Queries

Hallucination Prevention

1. Tool-only responses: Agent can only answer using tool results; no fabricated data
2. Source citations: Every response includes links to source documents in Orcha
3. Explicit uncertainty: If no results found, agent says so clearly rather than guessing
4. Scoped results: All queries are automatically filtered by user permissions
5. Structured output: Agent returns data in consistent formats, not free-form prose for factual queries

Thread-Based Conversations

• All bot responses are posted in threads to keep channels clean
• Thread context is maintained for multi-turn conversations
• Thread history is included in agent context (last 10 messages max)

File Uploads (Document Processing)

Users can upload documents directly without slash commands—critical for mobile UX.

Supported Upload Types

Upload Flow

┌─────────────┐     ┌─────────────┐     ┌─────────────────────┐
│ User drops  │────▶│ Slack sends │────▶│ Orcha Backend       │
│ photo/PDF   │     │ file event  │     │                     │
└─────────────┘     └─────────────┘     │ 1. Download file    │
                                         │ 2. OCR extraction   │
                                         │ 3. Classification   │
                                         │ 4. Data extraction  │
                                         │ 5. Workflow trigger │
                                         └──────────┬──────────┘
                                                    │
                                                    ▼
                                         ┌─────────────────────┐
                                         │ Response to Slack   │
                                         │ (confirmation or    │
                                         │  approval request)  │
                                         └─────────────────────┘

Expense Upload Example

User action: Drops photo of restaurant receipt in DM with Orcha bot

Backend processing:

1. Downloads image from Slack
2. Runs OCR + extraction (existing Orcha pipeline)
3. Classifies as expense receipt
4. Extracts: merchant, amount, date, category (meal)

Bot response:

🧾 Expense Receipt Detected
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Merchant:  Restaurant Zur Linde
Amount:    €47.80
Date:      January 21, 2026
Category:  Meals & Entertainment

Is this correct?

[✓ Submit Expense]  [✎ Edit Details]  [✗ Cancel]

Clicking "Submit Expense" creates the expense and routes to approver.

Approval Workflows

Approvals happen entirely within Slack—no need to open Orcha.

Approval Notification Format

When an item requires approval, the approver receives a threaded message:

🔔 Approval Required: Purchase Request
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Requester:   @maria.schmidt
Item:        MacBook Pro 14"
Amount:      €2,499.00
Supplier:    Apple Store
Cost Center: Engineering
Justification: Current laptop 4+ years old, performance issues

📎 Attachments: quote.pdf

[✓ Approve]  [✗ Reject]  [💬 Ask Question]  [View in Orcha]

Approval Actions

Multi-Level Approvals

For items requiring multiple approvers:

• Each approver receives their own notification when it's their turn
• Message shows approval chain status: Approved by @finance.lead → Awaiting @cfo
• Final approval triggers completion notification to requester

Proactive Messages

Scheduled Executive Reports

Recipients: Executives, Finance Managers (configurable per tenant)

Frequency: Monthly (first Monday of month, 9:00 AM tenant timezone)

Content:

📊 Monthly Financial Summary - December 2025
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💰 Budget vs. Actual
┌────────────────┬──────────┬──────────┬─────────┐
│ Department     │ Budget   │ Actual   │ Var     │
├────────────────┼──────────┼──────────┼─────────┤
│ Engineering    │ €120,000 │ €115,420 │ -4%  ✓  │
│ Marketing      │ €50,000  │ €62,300  │ +25% ⚠️ │
│ Operations     │ €80,000  │ €78,900  │ -1%  ✓  │
│ Sales          │ €45,000  │ €44,200  │ -2%  ✓  │
└────────────────┴──────────┴──────────┴─────────┘

📄 Invoices
• Processed: 142 (€485,200)
• Pending approval: 8 (€23,400)
• Overdue: 3 (€12,100) ⚠️

📝 Contracts
• Active: 47
• Expiring in 30 days: 2
• New this month: 5

[View Full Report in Orcha]

Approval Reminders

Aggressiveness: Medium

Reminder message:

⏰ Reminder: Pending Approval
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
You have 3 items awaiting your approval:

1. Expense €127.50 from @john.doe (2 days ago)
2. Purchase Request €890 from @anna.lee (1 day ago)  
3. Invoice €2,340 from Supplier XYZ (4 hours ago)

[Review All Approvals]

Context-aware urgency:

• High-value items (>€5,000): More frequent reminders
• Items marked "urgent" by requester: Immediate + 2h + 4h
• Low-value routine items: Standard cadence

Event-Driven Notifications

Technical Implementation

Slack App Configuration

Required Scopes:

• chat:write - Send messages
• commands - Slash commands
• files:read - Access uploaded files
• im:history - Read DM history for context
• im:write - Send DMs
• users:read - Map Slack users to Orcha users
• channels:history - Read channel messages (for @mentions)

Event Subscriptions:

• message.im - DM messages
• app_mention - @orcha mentions in channels
• file_shared - File uploads
• message.channels - Channel messages (for thread replies)

Database Schema Additions

-- Slack workspace connections
CREATE TABLE slack_workspaces (
    id UUID PRIMARY KEY,
    tenant_id UUID REFERENCES tenants(id),
    slack_team_id TEXT UNIQUE NOT NULL,
    slack_team_name TEXT,
    bot_token TEXT ENCRYPTED,
    bot_user_id TEXT,
    connected_at TIMESTAMPTZ DEFAULT NOW(),
    connected_by UUID REFERENCES users(id)
);

-- Slack user mappings
CREATE TABLE slack_user_mappings (
    id UUID PRIMARY KEY,
    workspace_id UUID REFERENCES slack_workspaces(id),
    slack_user_id TEXT NOT NULL,
    orcha_user_id UUID REFERENCES users(id),
    linked_at TIMESTAMPTZ DEFAULT NOW(),
    UNIQUE(workspace_id, slack_user_id)
);

-- Message tracking for threads/context
CREATE TABLE slack_conversations (
    id UUID PRIMARY KEY,
    workspace_id UUID REFERENCES slack_workspaces(id),
    channel_id TEXT NOT NULL,
    thread_ts TEXT,
    orcha_user_id UUID REFERENCES users(id),
    context JSONB, -- Conversation history for agent
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Pending approval messages (for button callbacks)
CREATE TABLE slack_approval_messages (
    id UUID PRIMARY KEY,
    workspace_id UUID REFERENCES slack_workspaces(id),
    channel_id TEXT NOT NULL,
    message_ts TEXT NOT NULL,
    approvable_type TEXT NOT NULL, -- 'expense', 'purchase_request', 'invoice'
    approvable_id UUID NOT NULL,
    approver_user_id UUID REFERENCES users(id),
    status TEXT DEFAULT 'pending',
    created_at TIMESTAMPTZ DEFAULT NOW()
);

API Endpoints

POST /api/slack/events          -- Slack event webhook
POST /api/slack/interactions    -- Button clicks, modal submissions
POST /api/slack/commands        -- Slash command handler
GET  /api/slack/oauth/callback  -- OAuth completion
POST /api/slack/oauth/initiate  -- Start OAuth flow

Backend Services

1. SlackGatewayService - Receives all Slack events, authenticates, routes
2. SlackCommandHandler - Processes slash commands
3. SlackAgentService - Manages LLM agent for natural language queries
4. SlackNotificationService - Sends proactive messages
5. SlackApprovalService - Handles approval button interactions
6. SlackDocumentService - Processes file uploads

Error Handling

Security Considerations

1. Token storage: Bot tokens encrypted at rest
2. Request verification: All Slack requests verified using signing secret
3. Permission enforcement: Every action checks Orcha RBAC before execution
4. Audit logging: All Slack actions logged with user, action, timestamp
5. Data minimization: Conversation context purged after 24h of inactivity
6. No sensitive data in logs: Slack message content not logged, only metadata

Metrics & Monitoring

Future Enhancements (Out of Scope for Initial Release)

• Slack Connect: Support for shared channels with external parties
• Workflow Builder integration: Custom Slack workflows triggering Orcha actions
• Voice messages: Transcribe voice messages for queries
• Scheduled queries: "Remind me every Monday about open invoices"
• Custom slash commands per tenant: Admin-configurable commands