> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/notification-channels/slack.md).

# Slack

Configure Slack notifications and understand supported capabilities.

Slack is the most popular notification channel for Pharos, providing real-time error awareness directly in your team's primary communication tool. Slack notifications support rich formatting, direct links to Pharos records, and thread-based collaboration for troubleshooting.

## Why Slack for Observability

Slack excels as an observability notification channel because:

**Team Already There:** Most development teams use Slack as their primary communication tool. Notifications appear where teams are already working, not in yet another tool to monitor.

**Rich Formatting:** Slack supports formatted messages with bold text, links, code blocks, and structured data, making error details easy to scan.

**Thread Support:** Teams can discuss issues directly in notification threads, keeping context together without cluttering the main channel.

**Fast Delivery:** Slack notifications appear within seconds of error occurrence, enabling rapid response to critical issues.

**Channel Flexibility:** Organizations can create unlimited channels for free, enabling granular routing by functional area, severity, or environment.

## Integration Setup

Pharos connects to Slack via OAuth.

**Setup Overview:**

1. Create a Slack app in your workspace (or use existing Pharos app)
2. Configure OAuth scopes for channel posting
3. Authenticate via OAuth flow in Pharos Admin
4. Map notification rules to specific Slack channels

{% hint style="info" %}
**Authentication Method**

The Slack integration uses OAuth. The user who authenticates becomes the "sender" of all notifications. Messages appear as if sent by that user, so consider creating a dedicated "Pharos Bot" user or using a shared service account.
{% endhint %}

**Required OAuth Scopes:**

* `chat:write` — Post messages to channels and threads
* `chat:write.public` — Post to channels the app isn't a member of
* `channels:read` — List public channels for channel selection
* `groups:read` — List private channels (if posting to private channels)
* `users:read` — Get user information (for @mentions and display names)
* `im:read` — List direct messages
* `im:write` — Send direct messages

This is the full set the Pharos app requests — there is no reduced set for public-channel-only use. Pharos does not request channel or group message history, and group direct messages (multi-person DMs) aren't supported by the shipped app.

Once authenticated, Pharos can post to any channel the authenticated user has access to. For the configuration walkthrough, see [Configuration Guide: Slack](https://docs.pharos.ai/configuration-guide/integrations/slack.md).

## Notification Capabilities

### Rich Message Formatting

Pharos notifications in Slack support:

**Bold and Italic Text:**

```
*Bold text* for emphasis
_Italic text_ for secondary info
```

**Links:**

```
<https://yourinstance.salesforce.com/record_id|View Issue>
```

**Code Blocks:**

````
`inline code` for field values
```code block``` for stack traces
````

**Lists:**

```
• Bullet points for impact metrics
• User counts
• Record counts
```

### Notification Message Structure

A typical Pharos Slack notification contains:

**Subject Line:** Brief summary of the issue

```
🔴 [Production] New Critical Issue: OpportunityTriggerHandler Exception
```

**Message Body:**

* Direct link to Pharos issue or log record
* Error category and type
* Functional area
* Impact statistics (users, records, occurrences)
* Error details (configurable)

**Example Message:**

```
🔴 New Issue in Production

Summary: Apex Exception in OpportunityTriggerHandler
Category: Apex
Type: NullPointerException
Functional Area: Sales

Impact:
  • 23 users affected
  • 145 Opportunity records involved
  • First occurred: Today at 10:15 AM
  • Occurrences: 8 times in last hour

View Issue: https://yourinstance.salesforce.com/apex/pharos__issueDetail?id=a1b2c3
```

### Customizable Templates

Notification messages use merge fields to dynamically populate content:

**Available Merge Fields:**

* `{!Issue.Summary__c}` - Issue summary
* `{!Issue.Description__c}` - Full error message
* `{!Issue.Category__c}` - Error category (Apex, Flow, Bulk API, etc.)
* `{!Issue.Priority__c}` - Priority (Lowest through Highest)
* `{!Issue.Functional_Area__c}` - Business process name
* `{!Issue.Log_Count__c}` - Total occurrences
* `{!Issue.Impacted_Users_Count__c}` - Number of unique users affected
* `{!Issue.Impacted_Objects_Count__c}` - Number of unique records involved
* `{!Issue_Link}` - Direct link to Pharos issue page

**Template Example:**

```
Subject: New {!Issue.Category__c} in Production

Body:
Issue: {!Issue.Summary__c}
Functional Area: {!Issue.Functional_Area__c}

Users Impacted: {!Issue.Impacted_Users_Count__c}
Occurrences: {!Issue.Log_Count__c}

{!Issue_Link}
```

You can customize templates per notification rule, allowing different message formats for different teams or severity levels.

## Channel Mapping Strategies

Slack's unlimited free channels enable flexible routing strategies.

### Strategy 1: Single Channel (Simplest)

**Use Case:** Small teams (5-10 people), low error volume

```
Setup:
  #production-errors → All production issues
  
Notification Rule:
  Filter: Organization = "Production"
  Action: Post to #production-errors
```

**Pros:**

* Dead simple to set up
* Everyone has complete visibility
* No confusion about where to look

**Cons:**

* Doesn't scale beyond \~20 issues/day
* No functional area separation

### Strategy 2: Severity-Based Channels

**Use Case:** Teams that prioritize by urgency over functional ownership

```
Setup:
  #prod-critical → P0/P1 issues
  #prod-high → P2 issues
  #prod-monitoring → All other issues
  
Notification Rules:
  Rule 1: Priority = "Highest" → #prod-critical
  Rule 2: Priority = "High" → #prod-high  
  Rule 3: (Catch-all) → #prod-monitoring
```

**Pros:**

* Clear escalation path
* Teams know where to focus attention
* Easy to mute #prod-monitoring without missing critical issues

**Cons:**

* Requires accurate priority tagging
* Doesn't align with functional team ownership

### Strategy 3: Functional Area Routing

**Use Case:** Large teams (50+) with specialized functional areas

```
Setup:
  #prod-sales-errors → Sales automation
  #prod-service-errors → Service cloud
  #prod-marketing-errors → Marketing automation
  #prod-integration-errors → Middleware team
  #prod-platform-errors → Infrastructure
  
Notification Rules:
  Rule 1: Functional Area contains "Sales" → #prod-sales-errors
  Rule 2: Functional Area contains "Service" → #prod-service-errors
  [... additional functional areas ...]
  Rule N: (Catch-all) → #prod-platform-errors
```

**Pros:**

* Aligns with team structure
* Reduces noise (teams only see relevant errors)
* Clear ownership

**Cons:**

* Requires functional area tagging
* More channels to manage
* Critical cross-functional issues may need separate channel

### Strategy 4: Hybrid (Recommended for Large Teams)

**Use Case:** Large teams needing both functional separation and cross-functional critical visibility

```
Setup:
  #prod-critical → Cross-functional critical issues
  #prod-sales-errors → Sales team
  #prod-service-errors → Service team
  #prod-integration-errors → Integration team
  #prod-platform-errors → Catch-all
  
Notification Rules (ordered):
  Rule 1: Priority = "Highest" OR Impacted Users Count > 50 → #prod-critical
  Rule 2: Functional Area = "Sales" → #prod-sales-errors
  Rule 3: Functional Area = "Service" → #prod-service-errors
  Rule 4: Functional Area = "Integration" → #prod-integration-errors
  Rule 5: (Catch-all) → #prod-platform-errors
```

**Pros:**

* Combines severity and functional routing
* Critical issues have cross-functional visibility
* Functional teams have dedicated channels for routine monitoring

**Cons:**

* More complex rule configuration
* Critical channel must be actively monitored by all teams

{% hint style="info" %}
**Start Simple, Evolve**

Begin with a single channel (#production-errors) for the first 1-2 weeks. Observe error volume and patterns. Then split into functional or severity-based channels based on actual team structure and workflows.
{% endhint %}

## Channel Best Practices

### Dedicated Channels for Automation

**Do:**

```
✓ Create dedicated channel: #production-errors
✓ Only automated notifications post here
✓ Team discusses issues in threads
```

**Don't:**

```
❌ Post notifications to #general-engineering
❌ Mix automated notifications with team conversations
❌ Use personal DMs for team-wide issues
```

**Why:** Automated messages break up conversations, making channels hard to follow. Dedicated channels keep automation separate from human communication.

### Public vs. Private Channels

**Public Channels (Recommended):**

* Accessible to entire engineering org
* Easy to add stakeholders
* Discoverable (people can find them)
* Supports transparency

**Private Channels:**

* Restricted to specific team members
* Useful for security-sensitive errors
* Requires manual invitation to add people
* Less visible to broader organization

**Recommendation:** Use public channels unless dealing with security incidents or compliance-sensitive errors.

### Channel Naming Conventions

**Consistent Naming Pattern:**

```
#prod-{functional-area}-errors
#uat-{functional-area}-errors

Examples:
  #prod-sales-errors
  #prod-service-errors
  #uat-sales-errors
```

**Why:** Consistent naming makes channels easy to find and understand at a glance.

### Channel Descriptions

Set clear channel descriptions:

```
Channel: #prod-sales-errors
Description: Automated Pharos notifications for sales automation errors in Production. 
             Respond SLA: Triage during daily standup (10 AM).
             Owner: @sales-automation-team
```

This helps new team members understand the channel's purpose and expected response time.

## Notification Timing

Slack notifications from Pharos are sent **synchronously** when the triggering event occurs:

**Issue-Level Notifications:** Sent within 2-5 seconds of issue creation or update

**Log-Level Notifications:** Sent within 1-2 seconds of log creation (extremely fast)

This near-real-time delivery enables rapid response to critical issues.

## Thread-Based Collaboration

One of Slack's key advantages is thread support for issue discussions:

**Workflow:**

1. Pharos posts issue notification to channel
2. Team member starts thread: "I'm investigating"
3. Follow-up in thread: "Root cause identified: null reference in line 47"
4. Final update in thread: "Fix deployed, monitoring for recurrences"

**Benefits:**

* Keeps investigation context together
* Doesn't clutter main channel
* Easy to reference later ("what happened with that payment issue last week?")
* Clear accountability (who's investigating?)

{% hint style="success" %}
**Encourage Thread Usage**

Train teams to always reply in threads on Pharos notifications, not in the main channel. This keeps the channel clean and makes it easy to see which issues have been addressed.
{% endhint %}

## Limitations and Considerations

### Slack API Rate Limits

Slack has rate limits for incoming messages:

* \~1 message per second per channel (sustained)
* Bursts handled gracefully, but sustained high volume may be throttled

**Implication:** If you're generating 100+ errors per minute, use issue-level alerts (not log-level) to avoid rate limits.

### Message Length Limits

Slack messages have a \~3,000 character limit.

**Best Practice:** Keep notification messages concise. Don't include full stack traces in Slack—link to Pharos for full details.

**Template Guidance:**

```
Good:
  Summary, category, functional area, link → ~300 characters

Avoid:
  Full stack trace, all field values, complete history → 3,000+ characters
```

### No Interactive Buttons (Currently)

Unlike some Slack integrations, Pharos notifications don't currently support interactive buttons (e.g., "Acknowledge," "Create Ticket").

**Workaround:** Include direct links to Pharos, where users can take actions like changing priority, creating Jira tickets, or marking as resolved.

### Authentication Scope

Notifications appear to come from the user who authenticated the Slack integration.

**Consideration:** If that user leaves the company or changes permissions, the integration may break. Use a service account or bot user for authentication when possible.

## Real-World Example

**Organization:** 80-person engineering team, 12 functional areas

**Initial Setup:**

```
Single channel: #production-errors
Volume: 40-60 notifications per day
Feedback: "Too noisy, hard to know which issues are ours"
```

**Evolved Setup:**

```
Channels:
  #prod-critical (all team leads)
  #prod-sales-errors (8 people)
  #prod-service-errors (12 people)
  #prod-marketing-errors (5 people)
  #prod-integration-errors (4 people)
  #prod-platform-errors (10 people - catch-all)

Rules (ordered):
  1. Priority = "Highest" → #prod-critical
  2. Functional Area = "Sales" → #prod-sales-errors
  3. Functional Area = "Service" → #prod-service-errors
  4. Functional Area = "Marketing" → #prod-marketing-errors
  5. Functional Area = "Integration" → #prod-integration-errors
  6. (Catch-all) → #prod-platform-errors

Results:
  - Each team sees 5-15 notifications per day (manageable)
  - Critical channel averages 2-3 per day (actionable)
  - Response time improved from "eventual" to <2 hours
  - Team satisfaction high (right notifications to right teams)
```

## Summary

Slack is the recommended notification channel for most Pharos customers due to its:

**Strengths:**

* Real-time delivery (1-5 seconds)
* Rich message formatting
* Thread-based collaboration
* Unlimited free channels for routing flexibility
* Teams already use it daily

**Best Practices:**

* Start with single channel, split as needed
* Use dedicated channels (not mixed with team conversations)
* Encourage thread-based discussions
* Keep messages concise, link to Pharos for details
* Use public channels for transparency

**Avoid:**

* Log-level notifications (too many messages)
* Mixing production and sandbox in same channel
* Overly long messages (use links instead)
* Too many channels (start broad, split only when needed)

For other notification channels, see [Microsoft Teams](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/notification-channels/teams.md), [PagerDuty](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/notification-channels/pagerduty.md), [Email](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/notification-channels/email.md), and [Webhooks](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/notification-channels/webhooks.md).
