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

# Microsoft Teams

This guide walks you through connecting Microsoft Teams to TruU TOTAL for persona generation and threat detection.

***

## Overview

TOTAL collects collaboration and communication events from Microsoft Teams via Microsoft Graph API change notifications (webhooks). Events are streamed in real time — when a message is sent, a meeting occurs, or a membership changes, TOTAL receives the notification within seconds. We collect **metadata only** — message content is never accessed or stored.

**Connector Type:** Streaming (Webhooks via Microsoft Graph Change Notifications)

***

## Prerequisites

* **Microsoft Entra ID** (Azure AD) access with **Application Administrator** or **Global Administrator** role
* **Microsoft Teams** enabled and actively used in your organization
* **Microsoft 365 E3/E5** or equivalent license (for Graph API access)
* Approximately **20 minutes** to complete setup

***

## Step 1: Register an Application in Entra ID

1. Sign in to the [Azure Portal](https://portal.azure.com)
2. Navigate to **Microsoft Entra ID** → **App registrations**
3. Click **New registration**
4. Enter:
   * **Name**: `TruU TOTAL - Teams Integration`
   * **Supported account types**: *Accounts in this organizational directory only*
   * **Redirect URI**: Leave blank
5. Click **Register**
6. On the app's **Overview** page, copy:
   * **Application (client) ID**
   * **Directory (tenant) ID**
7. Paste the Client ID and Tenant ID into the TruU Portal

***

## Step 2: Create a Client Secret

1. In your App Registration, go to **Certificates & secrets**
2. Click **New client secret**
3. Enter:
   * **Description**: `TOTAL Teams integration`
   * **Expires**: Choose your organization's preferred expiry
4. Click **Add**
5. Immediately copy the secret **Value** — it will only be shown once
6. Paste the Client Secret value into the TruU Portal

***

## Step 3: Grant API Permissions

1. In the App Registration, click **API permissions**
2. Click **Add a permission** → **Microsoft Graph** → **Application permissions**
3. Add the following permissions:
   * `ChannelMessage.Read.All` — Read Teams channel messages (metadata)
   * `Chat.Read.All` — Read chat metadata
   * `Team.ReadBasic.All` — Read team properties
   * `TeamMember.Read.All` — Read team membership
   * `OnlineMeetings.Read.All` — Read meeting metadata
   * `CallRecords.Read.All` — Read call/meeting records
   * `User.Read.All` — Read user profiles for identity resolution
4. Click **Add permissions**
5. Click **Grant admin consent for \[Your Organization]**
6. Click **Yes** to confirm

> All permissions are **read-only**. TOTAL cannot send messages, create teams, schedule meetings, or modify any Teams resources.

***

## Step 4: Verify Connectivity

Once credentials are entered in the TruU Portal:

1. Click **Test Connection** — TOTAL will validate the credentials and confirm Graph API access
2. TOTAL will automatically create webhook subscriptions for your Teams resources
3. Real-time event streaming will begin within minutes

> Webhook subscriptions are automatically renewed by TOTAL before they expire. No manual maintenance is required.

***

## Security & Privacy

### What We Access

* **Read-only access** to Teams event metadata via Microsoft Graph webhooks
* Channel message metadata (sender, timestamp, channel — **not message content**)
* Team membership changes
* Meeting metadata (participants, duration, join/leave times)
* Call records (participants, duration, modality)

### What We Don't Have Access To

* Message content (body text, subject lines)
* Private chat content
* File contents shared in Teams
* Screen sharing or recording content
* User passwords or authentication tokens

***

## Updating or Rotating Credentials

### Rotate Client Secret (Recommended: Before expiry)

1. In Azure Portal, go to **Entra ID** → **App registrations** → `TruU TOTAL - Teams Integration`
2. Go to **Certificates & secrets**
3. Click **New client secret** (create the new one before deleting the old one)
4. Copy the new secret value
5. Paste the new secret in the Teams section in the TruU Portal
6. After TOTAL confirms the new secret is active, delete the old secret

### Revoke Access

To immediately remove TOTAL's access:

1. **Option A** — Disable in the TruU Portal
2. **Option B** — Remove the App Registration's API permissions in Entra ID
3. **Option C** — Delete the App Registration entirely

***

## Rate Limiting & Scalability

### Microsoft Graph Rate Limits (Teams)

| Parameter                     | Limit                                       |
| ----------------------------- | ------------------------------------------- |
| **Global Graph API limit**    | 130,000 requests per 10 seconds per app     |
| **Teams subscription limit**  | 10,000 total subscriptions per organization |
| **Subscription max lifetime** | 60 minutes (auto-renewed)                   |
| **Throttle response**         | HTTP 429 with `Retry-After` header          |

### Ingestion Capacity

Teams uses a **streaming/webhook model** — Microsoft pushes change notifications to TOTAL in near real-time, so throughput is not constrained by polling rate limits. TOTAL uses tenant-wide subscription resources (e.g., `/teams/getAllMessages`) to minimize subscription count well below the 10,000 limit. A large enterprise with 100K+ users typically generates 3M–15M Teams events/day. Webhook delivery capacity is effectively unlimited.

### Event Freshness

Microsoft delivers change notifications within seconds of the event. TOTAL acknowledges and processes them immediately. End-to-end latency from event occurrence to TOTAL processing is typically **under 10 seconds**.

### Resilience

TOTAL acknowledges webhook notifications immediately and processes them in the background. If the webhook endpoint is temporarily unavailable, Microsoft retries delivery with exponential backoff for up to 4 hours. Subscriptions are auto-renewed before their 60-minute expiry. If a subscription lapses, TOTAL creates a new one and performs a catch-up poll via the Graph API delta query to fill any gap. For outages exceeding 4 hours (beyond Microsoft's retry window), the same delta query mechanism ensures no events are permanently lost.

### Connector Design

TOTAL's webhook endpoint acknowledges notifications immediately and processes them asynchronously. Events are batched and published in per-user order to preserve sequence integrity for persona building. The webhook service scales horizontally behind a load balancer. All subscription scopes and batching parameters are tunable from the TruU Portal.

***

# Part 2: Event Types & Data Schema

## Signal Classification

| Signal Class   | TOTAL Category          |
| -------------- | ----------------------- |
| Communications | Activity, Collaboration |

## Event Types We Ingest

TOTAL subscribes to the following Microsoft Graph change notification resources for Teams. Every event is tied to a human identity — the user who sent the message, joined the meeting, or modified the team. Bot and application-generated events are excluded.

### Channel Message Events

| Graph Resource                       | Change Types              | Description                                 | TOTAL Classification |
| ------------------------------------ | ------------------------- | ------------------------------------------- | -------------------- |
| `/teams/{id}/channels/{id}/messages` | created                   | New message posted in a channel             | Activity             |
| `/teams/{id}/channels/{id}/messages` | updated                   | Message edited in a channel                 | Activity             |
| `/teams/{id}/channels/{id}/messages` | deleted                   | Message deleted from a channel              | Activity             |
| `/teams/getAllMessages`              | created, updated, deleted | All messages across all teams (tenant-wide) | Activity             |

### Chat Events

| Graph Resource          | Change Types              | Description                                 | TOTAL Classification |
| ----------------------- | ------------------------- | ------------------------------------------- | -------------------- |
| `/chats/getAllMessages` | created, updated, deleted | Chat message events across all chats        | Activity             |
| `/chats`                | created, updated          | New chat created or chat properties updated | Activity             |
| `/chats/{id}/members`   | created, deleted          | Members added/removed from a chat           | Activity             |

### Team & Channel Membership Events

| Graph Resource         | Change Types              | Description                                            | TOTAL Classification |
| ---------------------- | ------------------------- | ------------------------------------------------------ | -------------------- |
| `/teams`               | created, updated, deleted | User created, updated, or deleted a team               | Admin                |
| `/teams/{id}/channels` | created, updated, deleted | User created, updated, or deleted a channel            | Admin                |
| `/teams/{id}/members`  | created, updated, deleted | User added/removed a member or changed a member's role | Admin                |

### Meeting & Call Events

| Graph Resource                              | Change Types     | Description                                   | TOTAL Classification |
| ------------------------------------------- | ---------------- | --------------------------------------------- | -------------------- |
| `/communications/callRecords`               | created          | User participated in a call or meeting        | Activity             |
| `/communications/onlineMeetings`            | created, updated | User created or updated an online meeting     | Activity             |
| `/communications/callRecords/{id}/sessions` | —                | Individual user session details within a call | Activity             |

### Presence Events

| Graph Resource                   | Change Types | Description                  | TOTAL Classification |
| -------------------------------- | ------------ | ---------------------------- | -------------------- |
| `/communications/presences/{id}` | updated      | User presence status changed | Activity             |

***

## Sample Source Event (Microsoft Graph Change Notification — Channel Message)

```json theme={null}
{
  "value": [
    {
      "subscriptionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "changeType": "created",
      "clientState": "total-verification-token",
      "resource": "teams('team-id-001')/channels('channel-id-001')/messages('msg-id-001')",
      "subscriptionExpirationDateTime": "2026-03-16T14:00:00.000Z",
      "resourceData": {
        "@odata.type": "#Microsoft.Graph.chatMessage",
        "@odata.id": "teams('team-id-001')/channels('channel-id-001')/messages('msg-id-001')",
        "id": "msg-id-001",
        "from": {
          "user": {
            "id": "user-aad-id-001",
            "displayName": "Jane Doe",
            "userIdentityType": "aadUser"
          }
        },
        "createdDateTime": "2026-03-15T14:45:30.000Z",
        "lastModifiedDateTime": "2026-03-15T14:45:30.000Z",
        "chatId": null,
        "channelIdentity": {
          "teamId": "team-id-001",
          "channelId": "channel-id-001"
        },
        "messageType": "message",
        "importance": "normal",
        "locale": "en-us",
        "webUrl": "https://teams.microsoft.com/l/message/...",
        "mentions": [
          {
            "id": 0,
            "mentionText": "John Smith",
            "mentioned": {
              "user": {
                "id": "user-aad-id-002",
                "displayName": "John Smith"
              }
            }
          }
        ],
        "attachments": [
          {
            "id": "attachment-001",
            "contentType": "reference",
            "name": "Q1-Report.xlsx"
          }
        ],
        "reactions": []
      },
      "tenantId": "tenant-id-001"
    }
  ]
}
```

## TOTAL Normalized Event

```json theme={null}
{
  "event_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "event_type": "CHAT",
  "source": "TEAMS",
  "signal_type": "COMMUNICATIONS",
  "domain_id": "customer-domain-001",
  "tuid": "tuid-jane-doe-001",
  "timestamp": "2026-03-15T14:45:30.000Z",
  "payload": {
    "event_id": "msg-id-001",
    "user": "jane.doe@acme.com",
    "action": "message_created",
    "channel": "channel-id-001",
    "team": "team-id-001",
    "message_type": "message",
    "importance": "normal",
    "has_mentions": true,
    "mention_count": 1,
    "has_attachments": true,
    "attachment_count": 1
  },
  "raw_metadata": {
    "platform_event_id": "msg-id-001",
    "change_type": "created",
    "from_user_id": "user-aad-id-001",
    "from_display_name": "Jane Doe",
    "from_identity_type": "aadUser",
    "team_id": "team-id-001",
    "channel_id": "channel-id-001",
    "message_type": "message",
    "importance": "normal",
    "locale": "en-us",
    "mentions": ["user-aad-id-002"],
    "attachment_names": ["Q1-Report.xlsx"],
    "attachment_types": ["reference"],
    "created_at": "2026-03-15T14:45:30.000Z",
    "source_platform": "microsoft_teams"
  },
  "platform_event_id": "msg-id-001",
  "platform_event_source": "MICROSOFT_GRAPH_TEAMS_API"
}
```

***

## How This Feeds TOTAL

### Persona Building

Teams events define a user's **communication graph and collaboration pattern** — who they message, which channels they're active in, what meetings they attend, and when they're online. This forms a behavioral fingerprint of each identity's normal collaboration routine, including peer networks, working hours, and communication cadence.

### Anomaly Detection

TOTAL's behavioral engine uses Teams events to detect:

* **Communication graph anomalies** — sudden messaging with users outside normal peer networks, indicating potential collusion or account takeover
* **Insider threat indicators** — unusual file sharing patterns, bulk data sharing in channels, or communication with external contacts that deviates from baseline
* **Low-and-slow activity** — gradual shifts in communication patterns that represent behavioral precursors to exploitation
* **Working hours drift** — activity outside established patterns that may indicate compromised credentials being used from a different time zone
* **Collaboration pattern breaks** — sudden absence from regular channels/meetings combined with activity in unusual contexts

### Breach Lifecycle Coverage

Teams events provide primary coverage across **Intent Exposed** and **Scope / Lateral Movement** stages. Communication metadata is one of the strongest signals for surfacing insider intent and social engineering activity before it manifests as a technical exploit.