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

# Microsoft Teams

> Deploy your thinnestAI agent to Microsoft Teams as a bot for workplace conversations.

# Microsoft Teams

Add your agent to Microsoft Teams as a bot. Users can chat with it in channels or direct messages within their Teams workspace.

## Prerequisites

* An Azure account with access to [Azure Bot Service](https://portal.azure.com)
* A Microsoft 365 organization with Teams
* Admin permissions to install apps in Teams
* Your agent created and tested in thinnestAI

## Setup

### Step 1: Create an Azure Bot

1. Go to [Azure Portal](https://portal.azure.com)
2. Click **Create a resource** > search for **Azure Bot**
3. Click **Create**
4. Fill in:
   * **Bot handle**: A unique name (e.g., `acme-ai-assistant`)
   * **Subscription**: Your Azure subscription
   * **Resource group**: Create new or use existing
   * **Pricing tier**: F0 (Free) for testing
   * **Microsoft App ID**: Create new
5. Click **Review + Create** > **Create**

### Step 2: Get App Credentials

1. After creation, go to your bot resource
2. Navigate to **Configuration**
3. Copy the **Microsoft App ID**
4. Click **Manage Password** > **New client secret**
5. Copy the **Client Secret** (save it — you can't see it again)

### Step 3: Configure Your Agent

1. Open your agent in thinnestAI
2. Go to the **Deploy** tab
3. Select **Teams**
4. Enter:
   * **App ID** — The Microsoft App ID from Azure
   * **App Password** — The client secret
5. Click **Save & Enable**

### Step 4: Set the Messaging Endpoint

1. In Azure Portal, go to your bot's **Configuration**
2. Set the **Messaging endpoint** to:

```
https://api.thinnest.ai/webhooks/teams/YOUR_AGENT_ID
```

3. Click **Apply**

### Step 5: Add Teams Channel

1. In your Azure Bot, go to **Channels**
2. Click **Microsoft Teams**
3. Accept the Terms of Service
4. Click **Apply**

### Step 6: Install in Teams

1. In Azure Bot > **Channels** > **Microsoft Teams**, click **Open in Teams**
2. Or search for your bot by name in the Teams app store
3. Click **Add** to install the bot

### Step 7: Test It

Send a message to your bot in Teams. It should respond within seconds.

## How It Works

```
User sends message in Teams
        ↓
Teams sends activity to /webhooks/teams/{agent_id}
        ↓
thinnestAI verifies Azure JWT token
        ↓
Extracts user info → auto-captures lead
        ↓
Routes message to agent (GraphExecutor)
        ↓
Agent responds → sent back via Teams Bot API
```

### Session Persistence

Each Teams conversation gets its own session. The agent remembers the full conversation history within a conversation thread.

Session ID format: `teams_{conversation_id}`

### Automatic Lead Capture

Every Teams user is automatically captured as a lead with:

* **Name**: Display name from Teams profile
* **User ID**: Teams/Azure AD user identifier
* **Conversation ID**: Stored in custom fields
* **Platform**: `teams`
* **Deduplication**: One lead per Teams user per agent

### Bot Mentions

In channels, users must @mention the bot to trigger a response. The mention text is automatically stripped from the message before it's sent to your agent.

## Security

* **Azure JWT verification**: Every incoming webhook is verified using Azure Bot Service JWT tokens
* **App credentials required**: Both App ID and App Password must be configured — requests are rejected without them
* **Credential encryption**: App Password is encrypted at rest

## Supported Activities

| Activity Type        | Supported | Description                 |
| -------------------- | --------- | --------------------------- |
| `message`            | Yes       | Text messages from users    |
| `conversationUpdate` | Partial   | Member added/removed events |
| `messageReaction`    | Not yet   | Reactions to messages       |
| `invoke`             | Not yet   | Card actions                |

## Troubleshooting

| Issue                  | Solution                                                          |
| ---------------------- | ----------------------------------------------------------------- |
| No response            | Verify messaging endpoint URL is correct                          |
| "missing credentials"  | Add App ID and App Password in agent config                       |
| "unauthorized"         | Verify App ID/Password match Azure portal                         |
| "teams not enabled"    | Enable Teams in agent Deploy settings                             |
| Bot not found in Teams | Check the Teams channel is added in Azure                         |
| Slow responses         | Complex agents may take time — consider simplifying instructions  |
| Empty messages ignored | The bot strips @mentions; if nothing remains, it returns silently |