# Microsoft Teams Interaction Channels

Enable AI-powered assistance directly in Microsoft Teams workspaces

> **Info:** Teams Interaction Channels are currently in beta, please reach out to your Customer Success Manager or Account Executive for support and guidance on this capability.

## Overview

Microsoft Teams Interaction Channels bring your Tray AI Agents directly into Teams workspaces where your users collaborate. Users can communicate with agents through natural conversation, ask questions, and leverage AI capabilities without leaving their Teams environment.

Please note that Teams does not support automated app creation; Teams integration requires manual configuration through the Teams Developer Portal and Tray platform. This setup process gives you full control over bot permissions and deployment options.

## Current Capabilities

**Direct Messaging**\
Users can install the agent and communicate with it through one-on-one conversations in Teams. The agent maintains conversation context and provides personalized responses based on user information.

**Team Channel Access**\
Install the agent in team channels to make it accessible to all channel members. The agent will respond to @mentions in any channel where it's installed.

> **Note:** Channel-specific deployment restrictions are not yet available in the beta. The agent will respond to @mentions across all channels where it has access. Granular channel control will be added in a future release.

**Thread-Aware Conversations**\
The agent maintains conversation history within Teams threads, understanding follow-up questions and referencing previous exchanges. In channels and group chats, users must @mention the agent in thread replies for it to respond.

**Rich Message Formatting**\
Responses use Teams Adaptive Cards for rich visual presentation.

## How It Works

### Workflow Architecture

Tray provides a set of pre-built workflows that handle the complete Teams integration. To view these workflows, click the three-dot menu next to your Teams interaction channel and select **Interaction Channel Assets**.

These workflows handle:

* Bot message filtering to prevent response loops
* Thread context tracking for multi-turn conversations
* Mention detection
* Conversation type identification
* Welcome messages when the bot is added to new conversations
* Rich response formatting with Adaptive Cards
* Error handling and graceful failures

### Authentication & Security

**Bot Framework Integration**\
Teams integration uses the Microsoft Bot Framework, requiring OAuth2 authentication with `botframework.com` as the tenant. The bot requires specific scopes (`https://api.botframework.com/.default`) to send and receive messages.

**Required Permissions**\
Your Teams App needs bot scopes to:

* Read messages in channels, groups, and personal chats
* Send messages with rich formatting (Adaptive Cards)
* Access user profile information for context
* Receive conversation update events

All permissions are configured in the Teams app manifest during setup.

**Authentication Requirements**\
Each Tray AI Agent deployed to Teams requires its own dedicated bot and authentication. While this means separate setup for each agent, it provides clear separation and independent permission management for each bot.

## Limitations (Beta)

The following features are not yet available but are planned for future releases:

* **Channel configuration UI** - Teams requires User scopes to retrieve channel names.
* **Reusable Authentication** - Create a single Teams bot authentication in Tray and reuse it across multiple agents. Simplifies credential management and ensures consistency across deployments.

## Prerequisites

To create a Microsoft Teams Interaction Channel, you need:

* Microsoft Teams admin permissions to publish apps to your organization
* Bot creation permissions in the Teams Developer Portal
* Access to the Agent Builder in your Tray workspace

***

## Setup Guide

### Step 1: Create Teams App and Bot

1. Open the [Teams Developer Portal](https://dev.teams.microsoft.com/apps)
2. Select **Import app** and click **Import zip package**
3. Import the Tray Teams App package ([download Teams manifest](https://tray.ai/documentation/files/teams/Tray_Teams_App_v1.01.zip))
4. Navigate to **App Features**
5. Select **Bot**
6. Click **Create a new bot** and name it (e.g., `Tray AI Agent`)
7. In the **Endpoint URL** field, enter a placeholder URL (e.g., `https://placeholder.example.com/webhook`) - you'll update this later
8. Navigate to **Client Secrets**
9. Click **Add a client secret**
10. Copy and securely store the client secret value - you'll need this for Tray authentication
11. Navigate to the **Bots** section in the left menu to find your bot ID
12. Copy and securely store the bot ID - you'll need this for Tray authentication
13. Return to **Apps** and select your Teams app
14. Go to **App Features** > **Bot** and verify the correct bot is associated
15. Click **Save**

> **Important:** Do not publish the app yet. You'll update the endpoint URL and publish after configuring Tray workflows.

### Step 2: Import and Configure the Teams Interaction Channel

1. Navigate to the **Interaction Channels** tab in your Agent builder
2. Click **Add interaction channel**
3. Select Teams
4. When prompted, select **Create a new authentication**.
5. Enter the following authentication details:
   * **Client ID**: Your bot ID from Step 1.12
   * **Client Secret**: The secret value from Step 1.10
   * **Tenant ID**: `botframework.com`
   * **Extra permission scopes**: `https://api.botframework.com/.default`
6. Configure the following settings:
   * **Allow Direct Messages** (`allow_dms`): Set to `true` to enable personal chats (default: `true`)
   * **Allow Mentions** (`allow_mentions`): Set to `true` to respond to @mentions in channels (default: `true`)
7. When complete, click the three-dot menu on the created Teams Interaction Channel and select **Interaction Channel Assets**
8. Find the **Microsoft Teams App Trigger** in \[Core] Teams Message Events
9. Copy the public webhook URL - you'll need this for the Teams bot endpoint

> **Note:** Channel-specific restrictions (`teams_channels` parameter) are not configurable in the current beta version. The agent will respond to @mentions in all channels where it's installed. This feature requires additional Microsoft Graph API permissions and will be available in a future release.

### Step 3: Update Teams Bot Endpoint

1. Return to the [Teams Developer Portal](https://dev.teams.microsoft.com/apps)
2. Navigate to your app and go to **App Features** > **Bot**
3. Update the **Endpoint URL** with the webhook URL from Step 2.8
4. Click **Save**
5. In the top right, click **Publish** and select **Publish to your organization**
6. Click **Submit for approval**

### Step 4: Distribute the App

You must have Teams admin permissions to complete this step:

1. Navigate to the [Teams Admin Center](https://admin.teams.microsoft.com/policies/manage-apps)
2. Search for your app by name
3. Click into the app details
4. Click **Publish** to make it available to your organization
5. Configure any additional app policies as needed for your organization

### Step 5: Test the Integration

1. Open Microsoft Teams
2. In the left navigation bar, select **Apps**
3. Search for your app name (e.g., "Tray AI Agent")
4. Click **Add** to install the app
5. Choose where to install:
   * **Add for you** - Personal chat with the agent
   * **Add to a team** - Make available in a team channel
6. Start a conversation to test the agent
7. If added to a channel, @mention the agent to trigger a response

***