Catalio logo
Sign in
Banner image for Microsoft Teams Integration Administration
Integrations • 9 min read

Microsoft Teams Integration Administration

Administrator guide for installing, configuring, and managing the Catalio Microsoft Teams bot integration.

Updated

Microsoft Teams Integration Administration

This guide covers installation, configuration, and management of the Catalio Microsoft Teams bot integration for administrators.

Overview

The Catalio Microsoft Teams bot brings conversational AI requirements management directly into your Teams workspace. Your team can create, update, search, and manage requirements without leaving Microsoft Teams.

Key Features:

  • Conversational AI: Natural language interaction with requirements
  • Bot Framework Integration: Native Microsoft Teams bot experience
  • OAuth2 Authentication: Secure workspace connection via Azure AD
  • Multi-Tenant Support: Organization-scoped data isolation
  • Real-time Responses: Instant requirement access in Teams channels and DMs

Prerequisites

Administrative Access

  • Catalio Account with Admin Role: Only organization administrators can connect Teams workspaces.
  • Microsoft Teams Admin Access: You need permission to install custom apps in your Teams workspace.
  • Azure AD Configuration: Your organization’s Azure AD tenant must be configured with the Catalio Bot registration.

Not an Admin? Contact your organization administrator to connect Microsoft Teams, or ask them to grant you admin privileges in Catalio.

Installation Steps

Step 1: Access Teams Integration Settings

  1. Sign into Catalio at catalio.ai
  2. Navigate to Settings (gear icon in top-right)
  3. Select Integrations → Microsoft Teams

You’ll see the Microsoft Teams integration settings page where you can manage workspace connections.

Step 2: Register Catalio Bot in Microsoft Teams

The Catalio bot must be registered in your Microsoft Teams tenant before it can interact with your workspace.

Option A: Install via App Catalog (Recommended)

If your Teams administrator has added Catalio to your organization’s app catalog:

  1. In Microsoft Teams, click Apps in the left sidebar
  2. Search for “Catalio”
  3. Click Add to install the bot to your Teams workspace
  4. Click Add to a team to select which channels the bot can access

Option B: Install via Azure Portal (Custom Registration)

If the bot isn’t in your app catalog, your Azure AD administrator must register it:

  1. Sign into Azure Portal

  2. Navigate to Azure Active Directory → App Registrations

  3. Create new registration for “Catalio Bot”

  4. Configure bot settings:

    • Messaging Endpoint: https://your-catalio-instance.com/api/teams/messages
    • App ID: Provided by Catalio support
    • Bot Framework Token: Auto-generated during registration

  5. Grant permissions:

    • Chat.ReadWrite: Allow bot to send and receive messages
    • User.Read: Access user profile information
    • Team.ReadBasic.All: Access team names and members

  6. Add bot to Teams via manifest upload:

    • Download Catalio Teams bot manifest from Catalio Settings
    • In Teams Admin Center, upload custom app manifest
    • Approve app for organization use

Need Help? Contact Catalio support for detailed Azure AD registration assistance.

Step 3: Connect Workspace in Catalio

Once the bot is registered in Teams:

  1. Return to Catalio → Settings → Integrations → Microsoft Teams
  2. Click Connect Teams Workspace
  3. You’ll be redirected to Microsoft for OAuth2 authorization
  4. Sign in with your Microsoft 365 account (if not already signed in)
  5. Review the requested permissions and click Accept

The OAuth2 flow will:

  • Authenticate your Microsoft 365 identity
  • Verify you have admin permissions in the Teams workspace
  • Create a secure connection between Catalio and your Teams tenant
  • Store an encrypted access token for bot authentication

Step 4: Verify Connection

After authorization completes, you’ll be redirected back to Catalio with a success message.

Verify the connection:

  1. In Catalio, check Settings → Integrations → Microsoft Teams
  2. You should see:
    • Status: Connected ✅
    • Workspace Name: Your Microsoft 365 tenant name
    • Connected By: Your admin account email
    • Connected At: Timestamp of connection

Your Microsoft Teams workspace is now connected! Your team can immediately start using @Catalio in Teams channels and DMs.

Managing the Integration

Workspace Connection Status

To view connection details:

  1. Navigate to Settings → Integrations → Microsoft Teams
  2. View connection information:
    • Tenant ID
    • Bot Service Endpoint
    • Connection timestamp
    • Active channels

Connection Health Indicators:

  • ✅ Green badge: Bot is active and responding normally
  • ⚠️ Yellow badge: Degraded performance or authentication warnings
  • ❌ Red badge: Connection failed or bot offline

Disconnecting the Workspace

To disconnect your Teams workspace:

  1. Navigate to Settings → Integrations → Microsoft Teams
  2. Click Disconnect Workspace button
  3. Confirm disconnection in the modal dialog

What happens when you disconnect:

  • The bot will stop responding to messages in your Teams workspace
  • All active Teams conversations will be terminated
  • OAuth2 access token is revoked and removed
  • Historical conversation data remains in Catalio (not deleted)
  • The bot remains installed in Teams (but inactive)
  • You can reconnect anytime by clicking Connect Workspace again

Note: Disconnecting does NOT uninstall the bot from Microsoft Teams. To fully remove the bot, see “Uninstalling the Bot” below.

Reconnecting the Workspace

If you previously disconnected:

  1. Navigate to Settings → Integrations → Microsoft Teams
  2. Click Connect Workspace
  3. Complete OAuth2 authorization flow again
  4. Bot will resume responding to messages

Monitoring Bot Activity

View bot usage statistics:

  1. Navigate to Settings → Integrations → Microsoft Teams → Activity
  2. View metrics:
    • Total messages processed
    • Active users (last 30 days)
    • Most active channels
    • Common queries and actions
    • Error rate and response times

Activity Logs:

  • All bot interactions are logged for audit and compliance
  • Logs include: timestamp, user, channel, message text, bot response
  • Access logs via Settings → Integrations → Microsoft Teams → Logs

Managing Permissions

Bot Channel Access:

The bot can only access channels where it has been explicitly added:

  1. Open the Teams channel
  2. Click … (More options)
  3. Select Manage channel
  4. Add or remove “Catalio” bot from the channel

User Permissions:

  • All users in your Catalio organization can interact with the bot

  • User actions are subject to Catalio role-based permissions:

    • Viewers: Can search and view requirements
    • Contributors: Can create, update, and view requirements
    • Admins: Full access including admin operations

  • The bot enforces Catalio permissions when executing actions

  • Users without proper permissions will receive error messages

Troubleshooting

Bot Not Responding

Symptom: @Catalio doesn’t respond to messages in Teams

Solutions:

  1. Check connection status:

    • Go to Settings → Integrations → Microsoft Teams
    • Verify status is “Connected ✅”
    • If disconnected, click Connect Workspace

  2. Verify bot is added to channel:

    • In Teams, check if Catalio appears in channel members
    • If not, add Catalio to the channel

  3. Check OAuth2 token expiration:

    • Tokens expire after 90 days
    • Reconnect workspace to refresh token

  4. Inspect bot activity logs:

    • Navigate to Settings → Integrations → Microsoft Teams → Logs
    • Look for error messages or authentication failures

Authentication Errors

Symptom: “Unable to authenticate with Microsoft Teams” error during connection

Solutions:

  1. Verify Azure AD permissions:

    • Ensure bot registration has required permissions (see Installation Steps)
    • Admin must grant organization-wide consent

  2. Check redirect URI:

    • Azure bot registration must include Catalio OAuth2 redirect URI
    • Verify: https://your-catalio-instance.com/auth/teams/callback

  3. Inspect browser console:

    • Open browser dev tools (F12)
    • Check for CORS or authentication errors
    • Share errors with Catalio support

Bot Responds Slowly

Symptom: Bot takes >10 seconds to respond in Teams

Solutions:

  1. Check Catalio instance health:

    • Visit Catalio web app to verify it’s responsive
    • Slow bot responses often indicate backend performance issues

  2. Review activity logs:

    • Look for timeout errors or failed LLM API calls
    • LLM provider outages can cause delays

  3. Verify Bot Framework service health:

“Account Not Found” Errors

Symptom: Bot says “I couldn’t find your Catalio account”

Solutions:

  1. Verify email match:

    • Your Microsoft 365 email must match your Catalio account email
    • In Teams: Click your profile photo → View your email
    • In Catalio: Go to Settings → Account → Check email

  2. Update email address:

    • Option A: Update Microsoft 365 email to match Catalio
    • Option B: Update Catalio account email to match Microsoft 365
    • Both emails must be identical (case-insensitive)

  3. Check organization membership:

    • Ensure you’re a member of the connected Catalio organization
    • Contact your Catalio admin if you need to be added

Bot Configuration

Customizing Bot Behavior

To configure bot settings:

  1. Navigate to Settings → Integrations → Microsoft Teams → Configuration
  2. Adjust settings:
    • Response Verbosity: Concise | Detailed | Verbose
    • Default Requirement Filter: Show all | Only mine | Only active
    • AI Model: GPT-4 | GPT-3.5 (affects response quality and speed)
    • Max Requirements in List: 5 | 10 | 20 (prevents overwhelming responses)

Advanced Settings:

  • Enable Proactive Notifications: Bot can send unprompted messages (e.g., “Requirement approved”)
  • Allow Bulk Operations: Enable multi-requirement updates in a single command
  • Conversation Memory: How many previous messages bot remembers (affects context understanding)

Notification Preferences

Configure which Catalio events trigger Teams notifications:

  1. Navigate to Settings → Notifications
  2. Under “Microsoft Teams Notifications”, toggle:
    • ✅ Requirement approved
    • ✅ Requirement assigned to me
    • ✅ Comment on my requirement
    • ❌ Any requirement created (too noisy for most teams)
    • ✅ Use case linked to my requirement

Notifications appear as:

  • Channel messages: Posted in configured notification channel
  • DMs: Sent privately to affected users

Uninstalling the Bot

To completely remove Catalio from Microsoft Teams:

Step 1: Disconnect in Catalio

  1. Navigate to Settings → Integrations → Microsoft Teams
  2. Click Disconnect Workspace
  3. Confirm disconnection

Step 2: Remove from Teams

  1. In Microsoft Teams, click Apps in left sidebar
  2. Search for “Catalio”
  3. Right-click on Catalio app
  4. Select Uninstall
  5. Confirm removal

Step 3: Revoke Azure AD Permissions (Optional)

For complete cleanup, revoke Azure AD permissions:

  1. Sign into Azure Portal
  2. Navigate to Azure Active Directory → Enterprise Applications
  3. Find “Catalio Bot” application
  4. Click Delete to remove app registration
  5. Confirm deletion

Note: Deleting Azure AD registration is permanent. You’ll need to re-register the bot to reconnect in the future.

Security & Privacy

Data Privacy

  • Message Content: Bot messages are logged for audit and debugging purposes
  • User Information: Bot accesses your Microsoft 365 email and name only
  • Data Storage: All data stored in Catalio’s encrypted database (not in Microsoft servers)
  • Retention: Message logs retained according to your organization’s Catalio data retention policy

OAuth2 Token Security

  • Encryption: OAuth2 tokens encrypted at rest using AES-256
  • Scope: Tokens scoped to bot messaging only (no access to files, calendars, etc.)
  • Expiration: Tokens automatically expire after 90 days
  • Rotation: Tokens refreshed automatically before expiration
  • Revocation: Disconnecting workspace immediately revokes tokens

Compliance

  • GDPR: Bot complies with EU data privacy regulations
  • SOC 2: Catalio infrastructure is SOC 2 Type II certified
  • HIPAA: Not currently HIPAA-compliant (do not use for PHI)

For detailed security information, see Catalio Security Whitepaper.

Support & Resources

Need Help?

Documentation

Document Version: 1.0 Last Updated: 2026-01-22 Next Review: 2026-07-22 Maintained By: Catalio Documentation Team