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

# Teams Bot Deployment

> Deploy your Airia agents as Microsoft Teams bots to enable conversational AI within your workspace.

Deploy your Airia agents as Microsoft Teams bots to bring AI-powered assistance directly into your organization's Teams workspace. Users can interact with your agents through direct messages or chat conversations, creating seamless workflows within their existing communication tools.

## Overview

The Teams Bot interface allows you to deploy agents that users can interact with directly in Microsoft Teams. Once configured, your agent appears as a bot in your Teams workspace, ready to respond to messages, participate in conversations, and assist with tasks without leaving the Teams environment.

<Note>
  Teams Bot deployment requires administrator access to both your Airia account and your Microsoft Azure/Entra ID tenant.
</Note>

## Prerequisites

Before deploying an agent to Teams, you'll need:

* Administrator or Platform Admin access in Airia
* Microsoft Azure administrator privileges with access to Azure Portal and Entra ID
* A deployed agent ready to connect to Teams
* A Microsoft 365 tenant with Teams enabled

## Creating a Microsoft Teams Bot

The first step is to register a bot with the Microsoft Bot Framework. When you create an Azure Bot, it automatically creates an App Registration for you, simplifying the setup process.

### Step 1: Register Your Bot in Azure Bot Services

1. Navigate to the [Azure Portal](https://portal.azure.com)
2. Search for **Azure Bot** in the search bar
3. Click **Create** to start creating a new Azure Bot
4. Configure the bot settings:
   * **Bot handle**: Enter a unique name for your bot (e.g., `airia-assistant-bot`)
   * **Subscription**: Select your Azure subscription
   * **Resource group**: Create new or select existing
   * **Pricing tier**: Choose appropriate tier (F0 for free tier is fine for testing)
   * **Type of App**: Select **Single Tenant**
   * **Creation type**: Select **Create new Microsoft App ID**
5. Click **Review + Create**, then **Create**
6. Wait for the deployment to complete

<Tip>
  The bot handle will be the identifier users see when interacting with your bot in Teams, so choose a descriptive name.
</Tip>

<Note>
  When you create an Azure Bot with "Create new Microsoft App ID", Azure automatically creates an App Registration for you. You don't need to create a separate App Registration manually.
</Note>

### Step 2: Access the App Registration and Generate Client Secret

After the Azure Bot is created, navigate to its automatically created App Registration:

1. In your Azure Bot resource, navigate to **Configuration** in the left sidebar
2. Click on **Manage Password** link next to the Microsoft App ID field - this opens the App Registration
3. Alternatively, go to **Microsoft Entra ID** > **App registrations** and find the app with your bot's name
4. Copy and save the **Application (client) ID** - you'll need this later
5. Copy and save the **Directory (tenant) ID** - you'll need this later
6. In the left sidebar, navigate to **Certificates & secrets**
7. Under **Client secrets**, click **New client secret**
8. Add a description (e.g., "Airia Integration")
9. Select an expiration period (recommendation: 24 months or less for security)
10. Click **Add**
11. **Immediately copy the secret Value** - you won't be able to see it again
12. Store this securely - you'll need it in Airia

<Warning>
  The client secret value is only shown once. If you lose it, you'll need to generate a new secret. Never share your client secret publicly or commit it to version control.
</Warning>

### Step 3: Configure API Permissions

Your bot needs permissions to access Microsoft Graph API for user information:

1. In your App Registration, navigate to **API permissions** in the left sidebar
2. Click **Add a permission**
3. Select **Microsoft Graph**
4. Select **Application permissions** (not Delegated)
5. Add the following permissions:
   * `User.Read.All` - Read all users' basic profiles
6. Click **Add permissions**
7. Click **Grant admin consent for \[your organization]** (requires admin privileges)
8. Confirm by clicking **Yes**

<Note>
  Admin consent is required for application permissions. The `User.Read.All` permission allows the bot to retrieve user email addresses for user mapping.
</Note>

### Step 4: Add Teams Channel

Enable the Microsoft Teams channel for your bot:

1. In your Azure Bot resource, navigate to **Channels** in the left sidebar
2. Click on the **Microsoft Teams** icon
3. Review and accept the Terms of Service
4. Select **Microsoft Teams Commercial (default)** as the deployment channel
5. Click **Apply**
6. The Teams channel will now appear in your channels list with a status of "Running"

<Tip>
  After enabling the Teams channel, you can install your bot directly to Teams or publish it to your organization's app catalog for broader distribution.
</Tip>

## Configuring Your Teams Bot Deployment in Airia

Now you'll create the Teams Bot deployment in Airia and connect it to your agent:

### Step 1: Create a Teams Bot Interface

1. Navigate to your agent in the Airia platform
2. Click on the **Interfaces** section in Agent Settings
3. Click **Add Interface** or **New Deployment**
4. Select **Teams Bot** as the interface type

### Step 2: Add Your Microsoft Graph Access Token Credential

1. In the credential dropdown, select **Create new credential** or choose an existing Microsoft Graph Access Token credential
2. If adding a new credential, provide:
   * **Azure Tenant ID**: The Directory (tenant) ID from Step 3
   * **Azure Client ID**: The Application (client) ID from Step 3
   * **Azure Client Secret**: The client secret value from Step 3
3. This connects your deployment to your Azure tenant and enables user mapping via Microsoft Graph

<Note>
  Microsoft Graph Access Token credentials can be reused across multiple Teams bot deployments in your organization.
</Note>

### Step 3: Configure Execution Settings

Choose how the agent should execute when triggered from Teams:

**Anonymous**

* Execute without user context
* No user mapping required
* All messages are processed with the same permissions
* Best for: Public bots where user identity isn't important

**Agent Creator**

* Execute as the user who created this agent
* Uses agent creator's permissions for all executions
* No additional configuration needed
* Best for: Bots with consistent permission requirements

**Airia User** (Recommended)

* Map Teams users to existing Airia users
* Each user's execution uses their own Airia permissions
* Supports automatic user provisioning
* Best for: Enterprise deployments with role-based access control

When selecting "Airia User", you can optionally enable **"Automatically create Airia users"**:

* When enabled, new Airia accounts are automatically created for Teams users who don't have an Airia account
* Users are created with the "End User" role by default
* Matching is based on email address from Microsoft Graph

<Tip>
  Select "Airia User" with automatic user creation for enterprise deployments where you want seamless user access without manual account provisioning.
</Tip>

### Step 4: Copy the Webhook URL

After configuring the execution settings:

1. Click **Create Deployment**
2. Airia generates a **Webhook Events API URL** (also called Messaging Endpoint)
3. Click the **Copy** button to copy this URL
4. Keep this URL handy - you'll need it to configure the Messaging Endpoint in Azure Bot
5. The deployment is now created and ready for configuration

<Note>
  The webhook URL is unique to this deployment and allows the Bot Framework to send messages to your Airia agent.
</Note>

## Configuring the Messaging Endpoint in Azure

Return to your Azure Bot configuration to set up the messaging endpoint:

### Step 1: Set the Messaging Endpoint

1. Go back to the [Azure Portal](https://portal.azure.com)
2. Navigate to your **Azure Bot** resource
3. In the left sidebar, click **Configuration**
4. In the **Messaging endpoint** field, paste the webhook URL you copied from Airia
5. Click **Apply** to save the configuration

<Warning>
  Make sure your Airia deployment is created before configuring the messaging endpoint, otherwise message delivery will fail.
</Warning>

### Step 2: Verify Configuration

1. The Bot Framework will automatically validate the endpoint
2. If successful, your bot is now ready to receive and send messages
3. Any errors will be displayed in the Azure Portal

## Installing Your Bot in Teams

Your Teams bot is now configured and ready to be installed. Airia provides a convenient way to download a ready-to-use Teams app package.

### Step 1: Download the Teams App Package from Airia

1. In your Airia agent's **Interfaces** section, click on your Teams Bot deployment
2. Find the **Teams App Manifest** section
3. Click the **Download Manifest** button
4. A zip file will be downloaded containing:
   * `manifest.json` - The Teams app configuration
   * `color.png` - The app's color icon (192x192)
   * `outline.png` - The app's outline icon (32x32)

<Note>
  The downloaded manifest is pre-configured with your bot's App ID and Airia branding. You can customize the icons by replacing them in the zip file before uploading.
</Note>

### Step 2: Upload to Microsoft Teams

#### For Personal Use or Testing

1. Open Microsoft Teams
2. Click on **Apps** in the left sidebar
3. Click **Manage your apps** at the bottom
4. Click **Upload an app**
5. Select **Upload a custom app**
6. Choose the zip file you downloaded from Airia
7. Click **Add** to install the bot
8. The bot will appear in your Teams chat list

#### For Organization-Wide Deployment

For broader deployment across your organization:

1. Go to the [Teams Admin Center](https://admin.teams.microsoft.com)
2. Navigate to **Teams apps** > **Manage apps**
3. Click **Upload new app**
4. Upload the zip file downloaded from Airia
5. The app will appear in the list - click on it to review
6. Click **Publish** to make it available to your organization
7. Users can then find and install the bot from Teams' built-in app store

<Tip>
  Work with your Teams administrator to configure app permission policies if you want to pre-install the bot for specific users or groups.
</Tip>

## Testing Your Teams Bot

Your Teams bot is now fully configured and ready to use:

1. Open Microsoft Teams (desktop or web app)
2. Find the bot in your **Chat** list or search for it
3. Send a direct message to the bot
4. The message should be received by your Airia agent
5. You should receive a response from the agent through the bot

<Tip>
  Start by testing your bot with a simple direct message. Monitor the Conversation Feed in Airia to troubleshoot any issues.
</Tip>

## User Mapping (For "Airia User" Mode)

If you selected "Airia User" as your execution configuration, Airia automatically maps Teams users to Airia users based on email addresses retrieved from Microsoft Graph API.

### How Automatic Mapping Works

Airia automatically matches Teams users to Airia users when:

* The Microsoft Graph Access Token credential has the `User.Read.All` permission (required)
* Both the Teams account and Airia account use the same email address (UPN)

When a user sends a message to the bot:

1. Airia retrieves the user's email (User Principal Name) from Microsoft Graph using the app credentials
2. Searches for an Airia user with a matching email address
3. If found, executes the agent with that Airia user's permissions and context
4. If not found and auto-provisioning is enabled, creates a new Airia user with "End User" role

<Warning>
  If a Teams user cannot be matched to an Airia user and auto-provisioning is disabled, they will receive a message indicating they don't have access. Enable "Automatically create Airia users" to allow seamless access.
</Warning>

## Using Your Teams Bot

Once deployed, users can interact with your agent through Microsoft Teams:

### Direct Messages (1:1 Chat)

Users can send direct messages to the bot for one-on-one interactions:

1. Find the bot in Teams by searching for its name
2. Click to open a direct message conversation
3. Type a message and send
4. The bot will respond directly in the conversation
5. The conversation maintains context across multiple messages

### Adaptive Cards and Rich Responses

Teams bots support rich responses using Adaptive Cards:

* Formatted text with headings and lists
* Interactive buttons and actions
* Images and media
* Data visualization
* Form inputs

<Note>
  Your Airia agent's responses are automatically formatted as Adaptive Cards for optimal display in Teams, providing a richer user experience than plain text.
</Note>

<Note>
  Microsoft Teams messages are limited to approximately 20,000 characters. If your agent's response exceeds this limit, it will automatically be split into multiple messages.
</Note>

## Best Practices

### Security

* **Credential Protection**: Keep your Azure Client Secret secure and rotate it regularly (before expiration)
* **Webhook URL Protection**: Keep your webhook URL secure and don't share it publicly
* **Scope Minimization**: Only request the Microsoft Graph API permissions your bot actually needs
* **Access Control**: Configure your agent's policies to control what data the bot can access
* **Audit Logs**: Regularly review bot activity in Airia's monitoring feeds
* **Execution Context**: Choose the appropriate execution configuration based on your security requirements

### User Experience

* **Clear Bot Identity**: Use a descriptive bot name and profile picture in Azure Bot configuration
* **Response Time**: Ensure your agent is optimized for quick responses in chat conversations
* **Error Handling**: Configure graceful error messages when the bot can't fulfill requests
* **Context Awareness**: Enable chat history in your agent's configuration to maintain conversation context
* **User Guidance**: Communicate to users how to find and interact with the bot

### Agent Configuration

* **Clear Instructions**: Provide clear system prompts that define the bot's role and capabilities
* **Tool Access**: Ensure your agent has access to necessary tools and data sources
* **Rate Limiting**: Configure appropriate usage limits to prevent abuse
* **Monitoring**: Set up alerts for errors or unusual activity
* **Adaptive Card Compatibility**: Airia automatically formats responses as Adaptive Cards. Ensure your agent's responses work well in this format by avoiding overly complex nested structures.

## Use Cases

### IT Support Bot

Deploy an agent that helps employees with common IT issues:

* Password resets and account unlocks
* Software troubleshooting guides
* Access requests and approvals
* Ticket status lookups
* IT knowledge base queries

### HR Assistant

Create a bot that assists with HR-related questions:

* Benefits information and enrollment
* PTO policies and balance inquiries
* Onboarding guidance for new hires
* Company policy lookups
* Personal HR inquiries with privacy

### Personal Productivity Assistant

Build an agent that helps individuals manage their work:

* Task reminders and follow-ups
* Meeting preparation and summaries
* Document summarization
* Quick research queries
* Personal knowledge management

### Sales Assistant

Deploy a bot that supports sales team members:

* CRM data lookups (Dynamics, Salesforce)
* Lead qualification assistance
* Account information retrieval
* Quick competitive intelligence
* Sales playbook access

## Troubleshooting

<AccordionGroup>
  <Accordion title="Bot is not responding to messages">
    Check the following:

    * Verify the Microsoft Graph Access Token credential in Airia has the correct Tenant ID, Client ID, and Client Secret
    * Ensure the messaging endpoint URL is correctly configured in your Azure Bot's Configuration
    * Confirm the Azure App Registration has the required API permissions (`User.Read.All`)
    * Verify admin consent was granted for the API permissions
    * Check that the agent deployment is active in Airia
    * Review error logs in Airia's monitoring feeds (Conversation Feed)
    * Ensure the bot is properly installed in Teams
    * Verify the Teams channel is enabled and running in your Azure Bot
  </Accordion>

  <Accordion title="Azure Bot endpoint verification failed">
    This indicates the messaging endpoint couldn't be reached:

    * Ensure your Airia deployment is created and active
    * Copy the webhook URL again from Airia (don't manually type it)
    * Check that there are no extra spaces or characters when pasting
    * Wait a moment after creating the deployment before configuring in Azure
    * If the issue persists, delete and recreate the deployment in Airia
    * Check if there are any firewall or network restrictions blocking the connection
  </Accordion>

  <Accordion title="Bot can't access user information or email addresses">
    This typically indicates missing or misconfigured Microsoft Graph API permissions:

    * Return to your Azure App Registration's **API permissions** page
    * Verify `User.Read.All` permission is present under Application permissions (not Delegated)
    * Ensure admin consent has been granted (look for the green checkmark)
    * If you just added the permission, wait a few minutes for propagation
    * Verify the credentials in Airia match the Azure App Registration (Client ID, Tenant ID, Secret)
  </Accordion>

  <Accordion title="Bot doesn't appear in Teams or can't be installed">
    Possible causes:

    * The Teams channel may not be enabled in your Azure Bot - check the Channels section
    * Your organization may have policies restricting custom app uploads
    * The manifest zip file may be corrupted - download it again from Airia
    * The App ID in the manifest doesn't match your Azure Bot's App ID
    * Contact your Teams administrator to verify custom app upload policies
    * For organization-wide deployment, the app must be approved in the Teams Admin Center
  </Accordion>

  <Accordion title="Bot responds to some users but not others">
    This may be a permissions or user mapping issue:

    * If using "Airia User" execution mode, verify affected users have an Airia account with the same email (UPN) as their Microsoft 365 account
    * If auto-provisioning is disabled, users must have pre-existing Airia accounts
    * Confirm the `User.Read.All` permission is granted to your Azure App Registration
    * Verify the user is properly licensed in Microsoft 365
    * Review your agent's policies in Airia for user-level restrictions
    * Check if affected users are in your Azure AD tenant
  </Accordion>

  <Accordion title="Bot responses are slow or timing out">
    Performance optimization steps:

    * Review your agent's configuration for inefficient steps
    * Check if external tool integrations are responding slowly
    * Monitor token consumption and rate limits
    * Consider simplifying complex agent workflows
    * Check Airia platform status for any service issues
    * Verify your Azure Bot's pricing tier isn't hitting limits
  </Accordion>

  <Accordion title="How do I update my bot's name or profile picture?">
    Bot appearance is managed in Azure:

    * Go to the [Azure Portal](https://portal.azure.com)
    * Navigate to your Azure Bot resource
    * Go to **Configuration**
    * Update the **Display name** and **Icon URL** fields
    * Click **Apply** to save
    * Changes may take a few minutes to propagate to Teams
  </Accordion>

  <Accordion title="Can I deploy the same agent to multiple Teams tenants?">
    Yes, but each tenant requires its own Azure Bot and credential:

    * Create a separate Azure Bot and App Registration for each tenant
    * Obtain unique credentials (Tenant ID, Client ID, Client Secret) for each
    * Add each credential set to Airia separately
    * Create separate Teams Bot deployments for each tenant
    * Each deployment operates independently with its own webhook URL
  </Accordion>

  <Accordion title="The bot can't maintain conversation context">
    Enable chat history in your agent:

    * Edit your agent in Airia's Agent Studio
    * Navigate to AI steps in your agent flow
    * Enable **"Include the chat history"** option for all LLM steps
    * This allows the agent to reference previous messages in the conversation
    * Save your agent configuration
  </Accordion>

  <Accordion title="Client secret expired or about to expire">
    Client secrets have expiration dates and need to be rotated:

    * Go to your Azure App Registration
    * Navigate to **Certificates & secrets**
    * Create a new client secret before the old one expires
    * Copy the new secret value immediately
    * In Airia, go to **Settings** > **Credentials**
    * Update your Microsoft Graph Access Token credential with the new secret
    * Your deployments will automatically use the updated credential
    * Delete the old secret after confirming the new one works
  </Accordion>

  <Accordion title="Users receive 'unauthorized' or 'access denied' messages">
    This typically occurs when user mapping fails:

    * Verify the user's email in Teams matches their Airia account email exactly
    * If using auto-provisioning, ensure it's enabled in the deployment configuration
    * Check that the Microsoft Graph API permission `User.Read.All` is granted and consented
    * Verify the Azure credentials in Airia are correct and haven't expired
    * Review any agent-level access policies that might restrict users
    * Check the Conversation Feed in Airia for specific error details
  </Accordion>
</AccordionGroup>

## Managing Your Teams Bot

### Monitoring Activity

Track your bot's usage and performance:

1. Navigate to **Feeds** in Airia
2. Select **Conversation Feed** to view bot interactions
3. Review **Token Consumption** for usage patterns
4. Check **Agent Executions** for performance metrics
5. Monitor user adoption and engagement trends

### Updating Configuration

To modify your bot's behavior:

1. Edit the agent in Airia's Agent Studio
2. Make your changes to prompts, tools, or flow logic
3. Save the agent
4. Changes take effect immediately for new conversations

To modify deployment settings:

1. Navigate to the **Interfaces** section in Agent Settings
2. Click on your Teams Bot deployment to edit
3. Update execution configuration or credential
4. Click **Save Changes**
5. The deployment will use the new settings immediately

### Rotating Azure Credentials

Azure client secrets expire and should be rotated regularly:

1. Go to your Azure App Registration in the Azure Portal
2. Navigate to **Certificates & secrets**
3. Create a new client secret before the old one expires
4. Copy the new secret value
5. In Airia, update your Microsoft Graph Access Token credential with the new secret
6. Test the bot to ensure it's working with the new credentials
7. Delete the old secret once confirmed working

### Regenerating Webhook URL

If your webhook URL is compromised or you need a new one:

1. Navigate to your Teams Bot deployment in Airia
2. Click **Delete** to remove the existing deployment
3. Create a new Teams Bot deployment (you can reuse the same credential)
4. Copy the new webhook URL
5. Update the Messaging Endpoint in your Azure Bot's Configuration
6. Click **Apply** in Azure to save

### Removing the Bot

To deactivate a Teams bot deployment:

1. In Airia, navigate to your agent's Interfaces section
2. Click on the Teams Bot deployment
3. Click **Delete** at the bottom of the configuration screen
4. Confirm the deletion
5. Optionally, remove the bot from Azure:
   * Delete the Azure Bot resource in the Azure Portal
   * Delete the App Registration in Azure AD if no longer needed
   * Users will no longer be able to interact with the bot in Teams

## Security Considerations

### Data Privacy

* **Message Content**: All messages sent to your bot are processed by your Airia agent
* **Data Retention**: Configure data retention settings in Airia's admin settings
* **Compliance**: Ensure your deployment meets your organization's compliance requirements (GDPR, HIPAA, etc.)
* **User Consent**: Communicate to users how their messages will be processed
* **Microsoft Graph Access**: Your bot can access user profile information via the granted API permissions

### Access Control

* **Tenant Isolation**: Bots are isolated to your Azure AD tenant
* **User Authentication**: Microsoft handles user authentication through Teams
* **Policy Enforcement**: Use Airia's policy features to filter sensitive content
* **Role-Based Access**: Configure agent-level permissions for different user groups
* **Credential Management**: Regularly rotate Azure client secrets

### Incident Response

Prepare for security incidents:

* **Quick Deactivation**: Know how to quickly delete the deployment in Airia to stop the bot
* **Webhook Security**: If webhook URL is exposed, regenerate it immediately by recreating the deployment
* **Credential Rotation**: If credentials are compromised, generate new client secret in Azure and update in Airia
* **Audit Logging**: Monitor bot activity in Airia's Conversation Feed and Agent Executions
* **Incident Procedures**: Document steps to disable the bot quickly if needed
* **User Reporting**: Provide a way for users to report issues with the bot

## Support

For additional help with Teams Bot deployment:

* Review [Microsoft Bot Framework documentation](https://docs.microsoft.com/en-us/azure/bot-service/)
* Check [Microsoft Graph API documentation](https://docs.microsoft.com/en-us/graph/)
* Review [Teams bot development documentation](https://docs.microsoft.com/en-us/microsoftteams/platform/bots/what-are-bots)
* Check Airia's monitoring feeds for error details
* Contact your Airia account administrator
* Reach out to Airia support for platform-specific issues