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 2 above
   • Azure Client ID: The Application (client) ID from Step 2 above
   • Azure Client Secret: The client secret value from Step 2 above
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 Bot Framework Messaging Endpoint URL
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 Teams 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

Step 3: Update an Existing Installation

If the bot is already installed, download the app package again whenever Airia changes the manifest - for example, to pick up the /new and /resume entries in the bot's command menu:

1. Download the package again from your Teams Bot deployment in Airia
2. In Teams, open Apps > Manage your apps and use the Update option next to the app if one is offered; otherwise upload the new package the same way you installed it. For an organization-wide install, upload it in Teams apps > Manage apps in the Teams Admin Center
3. Teams treats the upload as an update, and the bot's command menu now lists the new commands

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

When a user sends a message to the bot:

1. Airia retrieves the user's email from Microsoft Graph using the app credentials, preferring the mailbox address and falling back to the user principal name
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, until someone starts a new conversation with /new

Conversation Commands

A Teams chat is attached to one Airia conversation at a time, and that conversation's context keeps growing as the chat goes on. Teams has no per-topic threads in 1:1 and group chats, so Airia provides two commands for changing topic and for going back:

After /new, the bot replies:

🆕 Started a new conversation. Earlier messages in this chat won't be used as context from here on. Type /resume to go back to an earlier one.

/resume on its own replies with the chat's list - up to 10 conversations, with the one the chat is attached to right now marked (current):

Earlier conversations in this chat:

1. Q3 budget questions (current)
2. Onboarding checklist for new hires
3. Teams Conversation

Reply with /resume and a number (for example /resume 2) to switch back.

Picking a number switches the chat and confirms it:

↩️ Switched to "Onboarding checklist for new hires". Earlier messages from that conversation are context again.

The other replies you may see are:

• There are no earlier conversations in this chat yet. - the chat has no conversations to list yet
• That number isn't in the list. Type /resume to see the current one. - the number is outside the list
• You're already in "<title>". - you picked the conversation the chat is already attached to
• Couldn't switch conversations just now. Please try again. - the switch didn't go through

What Happens to the Previous Conversation

/new deletes nothing. The conversation the chat was attached to keeps its full message history, stays visible in Airia alongside your other Teams bot conversations, and can be reopened from the chat with /resume. All /new does is stop that conversation from receiving new Teams messages.

/resume only ever offers conversations this chat was previously attached to and that you can still see, so it can't be used to reach a conversation from another chat. Conversations deleted in Airia drop out of the list.

Command Chips in 1:1 Chats

In a 1:1 chat, the agent's replies carry two chips under the last message of the answer:

• 🆕 New conversation - tapping it sends /new
• ↩️ Resume - tapping it sends /resume

The chips are shortcuts for typing the commands, so they do exactly the same thing and produce the same replies. They ride on the final message of a reply, so a long answer split across several messages keeps them at the end.

Conversation Titles

Conversations started from Teams are named from their first message rather than all being called "Teams Conversation". Airia saves a title derived from the first message straight away, then replaces it in the background with a generated name from the same naming agent that titles chats in the platform.

Response Formatting

Your agent's replies are sent as ordinary Teams chat messages, with the text converted to Teams-flavored Markdown first. What Teams then renders is Microsoft's call and varies by client - notably, headings are not rendered in a plain chat message at all, and lists render on desktop but not on iOS or Android. See Microsoft's message formatting reference for the current per-platform support matrix, and prefer bold text over headings if your users are mostly on mobile.

Airia's own conversion changes three things, so avoid relying on them in your agent's output:

• Markdown images are flattened to alt text (url) and don't render as images
• Horizontal rules are removed
• Two or more consecutive blank lines are collapsed to one

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
• Fresh Topics: Tell users about /new and /resume so they can change topic without a stale context window following them
• 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
• Response Formatting: Replies are sent as Teams chat messages with Markdown. Keep formatting to what Teams renders, and don't rely on Markdown images - they are flattened to text.

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