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

# Teams

Configure the Microsoft Teams integration in Pharos Admin.

The Microsoft Teams integration enables Pharos to send real-time notifications directly to Teams channels when issues are created or updated. Teams is the preferred channel for organizations deeply integrated with the Microsoft ecosystem.

{% hint style="info" %}
For an overview of Teams capabilities, channel strategies, and best practices, see [Microsoft Teams Notifications](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/notification-channels/teams.md).
{% endhint %}

***

## Accessing Teams Settings

1. Open the **Pharos** app
2. Navigate to **Pharos Admin**
3. Select **Integrations** from the left-hand menu
4. Click **Teams**

![Pharos Admin — Integrations sidebar with Teams selected, showing Teams Settings page](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-5e878dff53d5f41dbea66b96adf12b303931fea4%2Fteams-settings-nav.png?alt=media)

***

## Prerequisites

Before configuring Teams, ensure you have:

| Requirement                 | Details                                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Microsoft 365**           | Access to Teams and Microsoft Entra ID                                                                 |
| **Team and channel access** | Ability to create or access the channels where notifications will post                                 |
| **Consent permissions**     | Either admin rights to consent directly, or the ability to request admin consent (see scenarios below) |

***

## Authentication

Pharos connects to Microsoft Teams via OAuth. The flow varies depending on your Microsoft Entra ID role and your tenant's consent policies.

### Step 1: Enable and Initiate

1. Toggle **Enable Teams Integration** to on
2. Click **Login to Teams**

![Teams Settings — integration disabled, toggle in off position](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-852c53c7d08b94e63b5a42c063d7b7c26266084f%2Fteams-settings-disabled.png?alt=media)

After toggling on, the OAuth Token field and Login button appear:

![Teams Settings — integration enabled, showing OAuth Token field and Login to Teams button](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-c208f66d275e3e00b6d08e1a6b86438ad72928b5%2Fteams-settings-enabled.png?alt=media)

### Step 2: Complete the OAuth Consent

After clicking **Login to Teams**, Microsoft redirects you to a consent page. What you see depends on your role and tenant configuration.

#### Scenario A: Admin Consent (Direct)

If you are a **Global Administrator** or have admin consent privileges, you see the **Permissions requested** screen and can approve immediately:

![Microsoft Permissions requested — admin can review scopes and click Accept to grant access](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-eadedfe916a61426e9bdb9532545886ca4883ab3%2Fteams-oauth-admin-consent.png?alt=media)

Click **Accept** to complete the connection. You'll be redirected back to Pharos.

#### Scenario B: User Consent with Organization Checkbox

If your tenant allows user-level consent, you may see a **Permissions requested** screen with a **Consent on behalf of your organization** checkbox:

![Microsoft Permissions requested — user consent with "Consent on behalf of your organization" checkbox](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-a0d7bd81b62b14a5e16885147d05b6f0fbf08170%2Fteams-oauth-user-consent.png?alt=media)

* Check the box if you want to grant consent for all users in the tenant (requires appropriate permissions)
* Click **Accept** to complete the connection

#### Scenario C: Non-Admin — Approval Required

If your Microsoft Entra ID tenant requires admin approval for third-party apps and you are **not** an admin, you'll see the **Approval required** screen:

![Microsoft Approval required — non-admin user must enter justification and request admin approval](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-fd77d746049b1b9ccbf4d77c4a35a4cb7cda9ba5%2Fteams-oauth-approval-required.png?alt=media)

1. Enter a justification explaining why you need the Pharos integration (e.g., "Pharos is a Salesforce error monitoring application that needs to send notifications via MS Teams")
2. Click **Request approval**
3. You'll see a confirmation that the request was sent to your admin:

![Microsoft Request sent — admin has been notified and will review the consent request](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-aafd174b372b5081395b8f04bb9b201f8495f30f%2Fteams-oauth-request-sent.png?alt=media)

**What happens next:** Your Microsoft Entra ID admin receives the request and must approve it before the integration can be used.

#### Admin: Reviewing Consent Requests in Microsoft Entra

If a non-admin user requested approval, the tenant admin completes the consent from the **Microsoft Entra admin center**:

1. Go to **Microsoft Entra admin center** → **Applications** → **Enterprise applications**
2. In the left sidebar under **Activity**, click **Admin consent requests**
3. Find the **Pharos.ai** application in the pending requests list

![Microsoft Entra admin center — Enterprise applications → Admin consent requests showing Pharos.ai pending](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-c3a31327f6ba5d8eabcea5ff0e0aff72747f26ad%2Fteams-entra-admin-consent.png?alt=media)

4. Click on the Pharos.ai request to open its details
5. Click **Review permissions and consent**

![Pharos.ai app details — Review permissions and consent button to approve the integration](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-b5e897cfa61392abceeb3e93da1a0f556fbcd1dc%2Fteams-entra-app-details.png?alt=media)

6. Review the requested permissions and click **Accept**

After admin approval, the non-admin user can return to Pharos and click **Login to Teams** again to complete the OAuth flow.

### Step 3: Verify the Connection

* After completing the OAuth flow, the **OAuth Token** field should display a masked token value
* The toggle remains in the **on** position

{% hint style="info" %}
**Notification Sender:** The user who authenticates becomes the sender of all Teams notifications. Consider using a dedicated service account or "Pharos Bot" so notifications aren't tied to a personal account.
{% endhint %}

### Required API Permissions

The Pharos app requests these Microsoft Graph API permissions:

| Permission                                                 | Description                                |
| ---------------------------------------------------------- | ------------------------------------------ |
| **Read all groups**                                        | List teams available for channel selection |
| **Read group memberships**                                 | Determine team membership                  |
| **Read the names and descriptions of channels**            | List channels within teams                 |
| **Read the names, descriptions, and settings of channels** | Access channel configuration               |
| **Send channel messages**                                  | Post notifications to team channels        |
| **Read and write user chat messages**                      | Threading support                          |
| **Send user chat messages**                                | Direct message support                     |
| **Maintain access to data you have given it access to**    | Refresh token / persistent access          |
| **View users' basic profile**                              | Display names in notifications             |

These permissions are shown during the OAuth consent step. No manual app registration is required — Pharos provides a pre-configured Microsoft Entra ID app (verified as **Pharos AI, Inc.**).

***

## Team and Channel Mapping

Teams has a two-level structure: **Teams** (workspaces) and **Channels** (within teams). When creating notification rules, you specify which Team to post to in the notification action:

![Teams notification action — Subject, Team dropdown, and Body fields with merge fields](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-fcf9bcb0b29b1d8f78a2a75d45b14092499b2836%2Fteams-notification-action.png?alt=media)

The **Team** field is a dropdown populated from teams the authenticated user has access to. The **Subject** and **Body** fields support merge fields to pull data from the Pharos issue.

**Create dedicated channels** for Pharos notifications:

* `production-errors` — Production issue notifications
* `production-critical` — Critical production issues only
* `uat-errors` — UAT/sandbox notifications

Channels are typically easier to create than new Teams — you can add channels to existing Teams without IT approval in most organizations.

### What Notifications Look Like in Teams

Notifications appear as channel messages with the subject as a bold header, followed by the body content with links back to Salesforce:

![Teams notification — Flow error with Salesforce link, functional area, and error details with "see more" for long messages](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-c10372c6a56446e841008dcaed7bd1f334d7fbcc%2Fteams-message-example.png?alt=media)

{% hint style="info" %}
Teams collapses long messages behind a **see more** link. Keep your notification body focused on the most important context — the Pharos link, functional area, and error summary. Full stack traces are best viewed in Pharos itself.
{% endhint %}

***

## Sandbox and Post-Refresh Considerations

When you refresh a sandbox from production:

1. Run the [Quick Start](https://docs.pharos.ai/configuration-guide/quick-start.md) wizard with the **Sandbox Refresh** option
2. Re-authenticate the Teams integration in the sandbox
3. Update your notification rules to use sandbox-appropriate channels

***

## Re-authenticating

If the OAuth token becomes invalid or the connection stops working:

1. Return to Integrations → Teams
2. Click **Login to Teams** to re-authenticate
3. Complete the OAuth flow again
4. Verify a new token appears in the OAuth Token field

Re-authentication may be needed if the authenticating user is deactivated or if the Entra ID app consent is revoked.

***

## Teams vs. Slack

Teams tends to win where the organization is Microsoft 365-centric, where compliance approval is easier for the Microsoft stack, or where Azure DevOps integration matters; Slack tends to win where the development team already lives there. You can also run both — routing by environment or severity — which is common when different teams have different habits.

→ [Teams Notifications](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting/notification-channels/teams.md#teams-vs-slack) weighs the choice in full, including when running both is worth the overhead.

***

## Troubleshooting

| Issue                        | Cause                                          | Resolution                                                                   |
| ---------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------- |
| Notifications not appearing  | Integration disconnected or rule misconfigured | Verify connection status; check notification rule filters, team, and channel |
| "Channel not found"          | Bot lacks access or channel doesn't exist      | Add the app to the team; verify team and channel names                       |
| Permission errors            | Consent not yet granted                        | Check if admin approval is still pending in Microsoft Entra admin center     |
| "Approval required" on login | Tenant requires admin consent                  | Follow Scenario C above — request approval and have an admin grant consent   |
| Messages from wrong user     | Personal account used for auth                 | Re-authenticate with a dedicated service account                             |

{% hint style="success" %}
**Next Step:** Configure [Notification Rules](https://docs.pharos.ai/configuration-guide/notifications.md) to route issues to your Teams channels.
{% endhint %}
