> 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/teams.md).

# Teams

Configure Microsoft Teams notifications and understand supported capabilities.

Microsoft Teams is the preferred notification channel for organizations deeply integrated with the Microsoft ecosystem. Teams notifications provide real-time error awareness within Microsoft 365, supporting rich formatting, adaptive cards, and integration with Azure DevOps workflows.

## Why Teams for Observability

Microsoft Teams excels as an observability channel for organizations that:

**Microsoft-First Culture:** Teams is the primary communication tool, replacing email and other messaging platforms across the organization.

**Compliance Requirements:** Microsoft enterprise compliance and security policies are already in place for Teams, making it easier to get security approval than third-party tools like Slack.

**Azure DevOps Integration:** Seamless connection to Azure DevOps for automated ticket creation directly from notifications.

**Enterprise Scale:** Teams is provisioned company-wide, with consistent authentication via Azure AD.

**Mobile-First Organizations:** Strong mobile app presence with push notifications keeps remote teams connected.

## Integration Setup

Pharos connects to Microsoft Teams through OAuth against Microsoft Entra ID. **No app registration is required** — Pharos publishes a pre-configured Entra ID application, verified as Pharos AI, Inc., and you consent to it during the connection flow.

What varies between tenants is *who* can grant that consent. A global administrator approves it directly; in tenants that allow user-level consent, a non-admin can consent for themselves or on behalf of the organization; and in locked-down tenants an admin consent request has to be raised and approved before the connection completes. This is the step most likely to need coordination outside your team, so it's worth checking your tenant's consent policy before starting.

The permissions Pharos requests cover listing teams and channels, posting channel messages, sending and reading user chat messages for threading and direct messages, and maintaining refresh access. They're displayed in full on the consent screen.

{% hint style="info" %}
**The Authenticating User Is the Sender**

Messages appear as if sent by whoever authenticated the connection. Consider connecting as a dedicated service or "Pharos Bot" account rather than a personal one, so notifications aren't tied to an individual who may change roles or leave.
{% endhint %}

For the connection walkthrough, the consent scenarios, and the full permission list, see [Teams](https://docs.pharos.ai/configuration-guide/integrations/teams.md).

## Notification Capabilities

### Adaptive Card Formatting

Teams supports Adaptive Cards—rich, interactive message formats with structured layouts.

**Adaptive Card Features:**

* Structured sections (header, body, footer)
* Bold, italic, and colored text
* Action buttons (though Pharos primarily uses links)
* Collapsible sections for long content
* Consistent rendering across desktop and mobile

### Message Auto-Collapse

One of Teams' advantages over Slack is **automatic message collapse** for long content:

**Behavior:**

* Messages exceeding \~200 characters show a "See more" link
* Users click to expand full content
* Collapsed by default keeps channel clean

**Implication for Templates:** You can include more details in Teams notifications (like full error details) without cluttering the channel, since Teams will auto-collapse the message.

From training transcript: *"I believe teams does this differently, where even if the message is really long, like this one here, for example, there's going to be that little 'see more' link here, which is really nice. This is a lengthy message... it does kind of shorten them up for you, which is nice."*

### Notification Message Structure

A typical Pharos Teams notification contains:

**Subject Line (Bold Header):**

```
🔴 New Issue in Production
```

**Message Body:**

* Issue summary
* Category and type
* Functional area
* Impact metrics (users, records, occurrences)
* Direct link to Pharos
* Error details (can be lengthy due to auto-collapse)

**Example Message:**

```
🔴 New Log in Production

Summary: Flow failed to access lookup field

Category: Flow
Type: FlowException
Functional Area: Case Management

Link: https://yourinstance.salesforce.com/apex/pharos__logDetail?id=a1b2c3

Details:
Flow failed to access the value for the field because the field is not 
available to the running user. Verify that the flow is running as the 
correct user and has access to all required fields.
```

### Template Customization

Teams notification templates use merge fields similar to Slack:

**Available Merge Fields (Logs):**

* `{!Log.Summary__c}` - Log summary
* `{!Log.Category__c}` - Error category
* `{!Log.Type__c}` - Error type
* `{!Log.Details__c}` - Full error message/stack trace
* `{!Log_Link}` - Direct link to log record

**Available Merge Fields (Issues):**

* `{!Issue.Summary__c}` - Issue summary
* `{!Issue.Category__c}` - Error category
* `{!Issue.Functional_Area__c}` - Business process
* `{!Issue.Log_Count__c}` - Total occurrences
* `{!Issue.Impacted_Users__c}` - Users affected
* `{!Issue_Link}` - Direct link to issue record

**Template Best Practice for Teams:**

Because Teams auto-collapses long messages, you can safely include the full `{!Log.Details__c}` field:

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

Body:
{!Log.Summary__c}

Category: {!Log.Category__c}
Type: {!Log.Type__c}

{!Log_Link}

Details:
{!Log.Details__c}
```

For Slack, including Details would create a wall of text. For Teams, it's collapsed by default, so users can expand if needed.

## Team and Channel Mapping

Microsoft Teams has a two-level structure: **Teams** (workspaces) and **Channels** (within teams).

### Understanding Teams vs. Channels

**Team (Workspace):**

* Top-level organization (e.g., "Engineering," "IT Operations")
* Contains multiple channels
* Membership controlled at team level

**Channel (Conversation Space):**

* Sub-division within a team (e.g., "General," "Production Errors," "UAT Issues")
* Can be public (all team members) or private (selected members)
* Pharos posts notifications to specific channels

**Pharos Notification Rule Configuration:**

```
Team: Engineering
Channel: production-errors

Result: Notification posts to #production-errors within Engineering team
```

### Channel Mapping Strategies

#### Strategy 1: Single Team, Multiple Channels

**Use Case:** All technical staff in one "Engineering" team

```
Team: Engineering
Channels:
  - production-critical
  - production-errors  
  - uat-errors
  - platform-monitoring
```

**Pros:**

* Centralized team membership
* Easy to add new channels
* Consistent permissions

**Cons:**

* Everyone must be in Engineering team to see notifications
* Can't have different permissions per functional area

#### Strategy 2: Multiple Teams, Specialized Channels

**Use Case:** Large organizations with separate teams for functional areas

```
Team: Sales Engineering
  Channel: production-errors
  
Team: Service Engineering
  Channel: production-errors
  
Team: Platform Engineering
  Channel: production-errors
```

**Pros:**

* Clear organizational boundaries
* Each team controls their own membership
* Separate permissions per team

**Cons:**

* More complex setup
* Cross-functional issues require posting to multiple teams
* Harder to get broad visibility

#### Strategy 3: Hybrid (Recommended)

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

```
Team: Engineering (cross-functional)
  Channel: production-critical
  
Team: Sales Engineering
  Channel: production-errors
  
Team: Service Engineering
  Channel: production-errors
  
Team: Platform Engineering
  Channel: production-errors
```

**Notification Rules:**

```
Rule 1: Priority = "Highest" → Engineering / production-critical
Rule 2: Functional Area = "Sales" → Sales Engineering / production-errors
Rule 3: Functional Area = "Service" → Service Engineering / production-errors
Rule 4: (Catch-all) → Platform Engineering / production-errors
```

### Decision Point: Channel Granularity

During implementation, organizations often debate how many channels to create.

**Real-World Example from Training:**

A customer with 18 functional areas initially wanted 18 separate channels (one per area). After discussion, the team realized this was too many:

From training transcript: *"We have our 4 prefixes in Jira. Is there a way to create the channels based off of those prefixes, and then have the notifications go there based on that prefix? Or do we have to create those 18 separate channels?"*

Response: *"We could... have everything go to one channel and then have the message specify functional area. It's more of a question for you to decide on approach."*

**Recommendation:** Start with broader groups (4-8 channels), then split only if specific teams request dedicated channels.

## Creating Channels in Teams

One consideration for Teams is **who can create channels**:

**Team Owner:** Can create unlimited channels within their team

**Team Member:** Permissions vary based on organizational settings

**IT Ticket Required:** Some organizations require IT approval for new team creation (but not channel creation)

From training transcript: *"If we needed to create a new team, we'd have to submit a ticket, and that would just get created. But the channels within the teams, there's a limit of 250."*

**Implication:** Channel creation is typically easy (no IT ticket), but team creation may require approval. Design your notification structure around existing teams when possible.

{% hint style="info" %}
**Channel Limit**

Microsoft Teams supports up to 250 channels per team, which is more than sufficient for most notification routing strategies. If you're approaching this limit, you likely have too many channels and should consolidate.
{% endhint %}

## Channel Best Practices

### Dedicated Channels for Notifications

**Do:**

```
✓ Create dedicated channel: production-errors
✓ Only automated notifications post here
✓ Pin channel description explaining purpose
```

**Don't:**

```
❌ Post notifications to General channel (mixed conversations)
❌ Use existing team chat channels for automation
❌ Mix production and sandbox notifications in same channel
```

From training transcript: *"I think that's a sound plan. Because what we found is some customers would plug in their day-to-day channel for notifications, and then it's just really hard to have a conversation when all of a sudden you get an automated message, and it breaks up the thread."*

### Channel Naming Conventions

**Recommended Pattern:**

```
{environment}-{functional-area}-{severity}

Examples:
  production-errors
  production-critical
  uat-errors
  sandbox-monitoring
```

### Channel Descriptions

Set clear descriptions to help team members understand channel purpose:

```
Channel: production-errors
Description: Automated error notifications from Pharos for production environment.
             Review SLA: Daily standup (9 AM)
             Owner: @platform-team
             Integration: Pharos observability platform
```

### Public vs. Private Channels

**Public Channels (Recommended):**

* Any team member can see messages
* Easy to add stakeholders
* Supports transparency

**Private Channels:**

* Restricted to invited members only
* Useful for security-sensitive notifications
* Requires manual invitation for new members

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

## Environment Separation

For organizations with multiple Salesforce environments (Production, UAT, Sandbox), channel strategy matters.

### Separate Channels per Environment

**Recommended Setup:**

```
Team: Engineering
Channels:
  - production-critical
  - production-errors
  - uat-errors
```

**Notification Rules:**

```
Rule 1: Organization = "Production" AND Priority = "Highest"
        → Engineering / production-critical

Rule 2: Organization = "Production"
        → Engineering / production-errors

Rule 3: Organization = "UAT"
        → Engineering / uat-errors

Rule 4: (catch-all — any other org)
        → (No notification, or daily email digest)
```

### Combined Channels with Environment Prefix

**Alternative Setup:**

```
Team: Engineering
Channels:
  - salesforce-errors (all environments)
```

**Notification Message Template:**

```
Subject: [Production] New Issue
         [UAT] New Issue (environment in subject)
```

**Pros:** Fewer channels to manage **Cons:** Production urgency diluted by sandbox noise

**Recommendation:** Separate channels for production and non-production.

## Notification Timing

Teams notifications from Pharos are sent **synchronously**:

**Issue-Level Notifications:** Delivered within 2-5 seconds of issue creation

**Log-Level Notifications:** Delivered within 1-2 seconds of log creation

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

## Limitations and Considerations

### Mobile Notifications

Teams mobile app provides push notifications for channel messages. Ensure team members:

* Have Teams mobile app installed
* Have notifications enabled for relevant channels
* Have Do Not Disturb settings configured appropriately (critical channels allowed)

### Message Length

Teams messages have a practical limit of \~28,000 characters (much higher than Slack's \~3,000).

**Implication:** You can safely include full error details in notifications without hitting limits. However, use the auto-collapse feature to keep channels readable.

### Rate Limits

Microsoft Graph API (used for Teams notifications) has rate limits:

* \~30 messages per second per application (very high)
* Throttling is rare unless posting hundreds of messages per minute

**Best Practice:** Use issue-level alerts (not log-level) to avoid rate limiting.

### Authentication Scope

Notifications appear to come from the user who authenticated the Azure AD integration.

**Consideration:** If that user leaves or loses permissions, integration may break. Use a service account or service principal when possible.

## Real-World Example

**Organization:** 120-person technology team, Microsoft 365 enterprise, strong governance requirements

**Initial Setup:**

```
Single Team: IT Operations
Single Channel: salesforce-errors
Volume: 50-80 notifications per day
Feedback: "Too noisy, not sure which team owns which errors"
```

**Evolved Setup:**

```
Teams and Channels:
  Engineering (cross-functional)
    - production-critical
    
  Sales Technology
    - production-errors
    
  Service Technology  
    - production-errors
    
  Platform Engineering
    - production-errors
    - integration-errors

Notification Rules (ordered):
  1. Priority = "Highest" → Engineering / production-critical
  2. Functional Area = "Sales" → Sales Technology / production-errors
  3. Functional Area = "Service" → Service Technology / production-errors
  4. Functional Area = "Integration" → Platform Engineering / integration-errors
  5. (Catch-all) → Platform Engineering / production-errors

Results:
  - Each team sees 8-20 notifications per day (manageable)
  - Critical channel averages 1-3 per day (truly urgent)
  - Response time improved from days to hours
  - Compliance team approved (Microsoft-only stack)
```

## Teams vs. Slack

**Choose Teams if:**

* Organization is Microsoft 365-centric
* Security/compliance favors Microsoft stack
* Integration with Azure DevOps is important
* Teams is already primary communication tool

**Choose Slack if:**

* Development team prefers Slack experience
* Organization has existing Slack investment
* Need interactive buttons (Slack has richer bot capabilities)
* Teams is not widely adopted

**Use Both if:**

* Some teams use Teams, others use Slack
* Want redundancy (critical issues → both channels)
* Different environments → different tools (prod → Teams, dev → Slack)

{% hint style="success" %}
**Real-World Adoption Insight**

During customer training, the facilitator asked: "My question is not so much around your preference or your thoughts around Teams in particular, but how ingrained is Teams into your company day-to-day?"

Response: "Really the sole communication tool."

This confirmation that Teams was THE communication tool (not just A communication tool) validated that Teams was the right notification channel for this organization.
{% endhint %}

## Summary

Microsoft Teams is the ideal notification channel for Microsoft-centric organizations:

**Strengths:**

* Native Microsoft 365 integration
* Auto-collapse for long messages
* Enterprise compliance and security
* Strong mobile app with push notifications
* Azure AD authentication

**Best Practices:**

* Start with single team, multiple channels approach
* Use dedicated notification channels (not mixed conversations)
* Include full error details (Teams auto-collapses)
* Separate production from non-production environments
* Use public channels for transparency

**Avoid:**

* Log-level notifications (too many messages)
* Mixing environments in same channel
* Too many channels (start broad, split when needed)
* Posting to General or active conversation channels

For other notification channels, see [Slack](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/notification-channels/slack.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).
