Teams Bot Deployment

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.

​

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
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

​

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

​

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

​

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”

​

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

​

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

​

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

​

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
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

​

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)

​

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
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

​

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

​

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

​

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

​

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

​

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
• Check Microsoft Graph API documentation
• Review Teams bot development documentation
• Check Airia’s monitoring feeds for error details
• Contact your Airia account administrator
• Reach out to Airia support for platform-specific issues