​

Microsoft Teams Integration Setup Guide

This guide explains how to set up the Microsoft Teams bot integration with Collate.

​

Prerequisites

• Azure subscription with admin access.
• Collate instance with public HTTPS endpoint.
• Microsoft Teams workspace.

​

Step 1: Create Azure Bot Registration

1. Go to Azure Portal.
2. Search for “Azure Bot” and click Create
3. Fill in the required fields:
   • Bot handle — collate-bot (or your preferred name).
   • Subscription — Select your Azure subscription.
   • Resource group — Create new or use existing.
   • Pricing tier — Free (F0) for testing, Standard for production.
   • Type of App — Multi Tenant (recommended) or Single Tenant.
   • Creation type — Create new Microsoft App ID.
4. Click Review + Create, then Create.

​

Step 2: Get App Credentials

1. After deployment completes, go to your Bot resource.
2. Click Configuration in the left menu.
3. Copy the Microsoft App ID - you will need this later.
4. Click Manage Password next to Microsoft App ID.
5. In the App Registration page, go to Certificates & secrets.
6. Click New client secret.
7. Add a description (e.g., “Collate Bot Secret”) and set expiration.
8. Click Add and immediately copy the secret value (it’s only shown once).

​

Step 3: Configure Messaging Endpoint

1. In your Azure Bot resource, go to Configuration.
2. Set the Messaging endpoint to:
   https://<your-collate-domain>/api/v1/teams/messages
   
   Replace <your-collate-domain> with your actual Collate server domain.
3. Click Apply.

​

Step 4: Enable Teams Channel

1. In your Azure Bot, go to Channels.
2. Select the Microsoft Teams icon.
3. Read and accept the terms of service.
4. Click Apply.
5. The Teams channel should now show status Running.

​

Step 5: Configure in Collate

1. Log into Collate as an Admin user.
2. Select the Profile icon and navigate to Settings > Applications.
3. Click Add App abd select the Microsoft Team application.
4. Click Install.
5. Click Configure and enter the configuration details:
   • Microsoft App ID — The App ID from Step 2
   • Microsoft App Password — The client secret from Step 2
   • Microsoft App Tenant ID — Leave empty for multi-tenant bots, or enter your tenant ID for single-tenant
   
6. Click Save.

​

Step 6: Setup Microsoft App API permissions

1. Open the Microsoft registere application.
2. In the laeft navigation bar, click Manage > API permission.
3. Click Add a Permission.
4. In the Application permissions, click Microsoft Graph.
5. Search an select the User.Read.All or User.ReadBasic.All permission.
   • Select any one of above permission and click add permissions

​

Step 7: Add Bot to Teams

​

Option A: Multi-tenant Bots (from Azure Portal)

1. In Azure Bot > Channels > Teams, click Open in Teams
2. Click Add to add the bot to your personal chat.

​

Option B: Single-tenant Bots (requires App Package)

Single-tenant bots don’t appear in Teams app search. You must create and upload an app package.

​

Create the App Package

1. Navigate to the app-package directory:
   cd docs/integrations/teams/app-package
   
2. Generate the icons (if not already present):
   python3 create_icons.py
   
3. Edit manifest.json:
   • Replace YOUR_MICROSOFT_APP_ID with your Azure App ID (appears twice)
   • Replace YOUR_COLLATE_DOMAIN with your Collate domain (e.g., collate.example.com)
   
   {
     "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",
     "manifestVersion": "1.16",
     "version": "1.0.0",
     "id": "<YOUR_MICROSOFT_APP_ID>",
     "packageName": "io.collate.teams",
     "developer": {
       "name": "Collate",
       "websiteUrl": "https://www.getcollate.io",
       "privacyUrl": "https://www.getcollate.io/privacy",
       "termsOfUseUrl": "https://www.getcollate.io/terms"
     },
     "name": {
       "short": "Collate Bot",
       "full": "Collate AI Assistant"
     },
     "description": {
       "short": "Chat with Collate AI",
       "full": "Collate Teams bot for searching entities and AI-powered data insights"
     },
     "icons": {
       "outline": "<your_icon.png>",
       "color": "<your_color.png>"
     },
     "accentColor": "#7147E8",
     "bots": [
       {
         "botId": "<YOUR_MICROSOFT_APP_ID>",
         "scopes": [
           "personal",
           "team",
           "groupchat"
         ],
         "supportsFiles": false,
         "isNotificationOnly": false
       }
     ],
     "permissions": [
       "identity",
       "messageTeamMembers"
     ],
     "validDomains": [
       "<YOUR_COLLATE_DOMAIN>"
     ]
   }
   
   
4. Create the zip package:
   zip collate-teams-bot.zip manifest.json color.png outline.png
   

​

Upload to Teams

For personal use:

1. Open Microsoft Teams.
2. Click Apps in the left sidebar.
3. Click Manage your apps at the bottom.
4. Click Upload an app > Upload a custom app.
5. Select collate-teams-bot.zip.
6. Click Add.

For organization-wide deployment (requires Teams admin):

1. Go to Teams Admin Center.
2. Navigate to Teams apps > Manage apps.
3. Click Upload and select your zip file.
4. Approve the app for your organization.

​

Option C: Search in Teams (Multi-tenant only)

1. In Microsoft Teams, go to Apps.
2. Search for your bot name.
3. Click Add to add to personal chat, or add to a specific channel.

​

Step 7: Test the Integration

1. Send a message to the bot: “Hello”.
2. The bot should respond with a welcome message.
3. Try some example queries:
   • “Search for tables”
   • “What dashboards do we have?”
   • “Show me the lineage for [table name]“

​

Troubleshooting

​

Security Considerations

• Credential Storage — The Microsoft App Password is stored encrypted in the Collate database
• HTTPS Required — The messaging endpoint must use HTTPS
• Secret Rotation — Consider rotating the client secret periodically
• Single-tenant — For enterprise deployments, consider using single-tenant bot registration

​

Additional Resources

• Azure Bot Service Documentation
• Microsoft Teams Bot Development
• Adaptive Cards Documentation