> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcollate.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Microsoft Teams Integration Setup Guide
> Set up the Microsoft Teams bot integration with Collate, including Azure Bot registration, credentials, and Teams app setup.
# 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](https://portal.azure.com).
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:///api/v1/teams/messages
```
Replace `` 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:
```bash theme={null}
cd docs/integrations/teams/app-package
```
2. Generate the icons (if not already present):
```bash theme={null}
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`)
```json theme={null}
{
"$schema": "https://developer.microsoft.com/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",
"manifestVersion": "1.16",
"version": "1.0.0",
"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": "",
"color": ""
},
"accentColor": "#7147E8",
"bots": [
{
"botId": "",
"scopes": [
"personal",
"team",
"groupchat"
],
"supportsFiles": false,
"isNotificationOnly": false
}
],
"permissions": [
"identity",
"messageTeamMembers"
],
"validDomains": [
""
]
}
```
4. Create the zip package:
```bash theme={null}
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](https://admin.teams.microsoft.com).
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
| Issue | Possible Cause | Solution |
| ---------------------------------- | ---------------------------- | ------------------------------------------------------------------- |
| Bot not found in Teams search | Single-tenant bot | Single-tenant bots require app package upload (see Step 6 Option B) |
| "You do not have permission" error | Single-tenant or org policy | Upload app package manually or contact Teams admin |
| Bot not responding | Messaging endpoint incorrect | Verify the endpoint URL in Azure Bot Configuration |
| 401 Unauthorized | Invalid credentials | Double-check App ID and Password match Azure configuration |
| No AI responses | AI Platform not enabled | Ensure AI Platform is enabled in Collate configuration |
| Timeout errors | Network issues | Check network connectivity between Teams and Collate server |
| Bot added but can't message | Teams channel not enabled | Verify Teams channel is enabled in Azure Bot Channels |
| Can't upload custom app | Sideloading disabled | Ask Teams admin to enable custom app uploads in admin center |
## 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](https://docs.microsoft.com/en-us/azure/bot-service/)
* [Microsoft Teams Bot Development](https://docs.microsoft.com/en-us/microsoftteams/platform/bots/what-are-bots)
* [Adaptive Cards Documentation](https://adaptivecards.io/)
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**.
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:
```bash theme={null}
cd docs/integrations/teams/app-package
```
2. Generate the icons (if not already present):
```bash theme={null}
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`)
```json theme={null}
{
"$schema": "https://developer.microsoft.com/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",
"manifestVersion": "1.16",
"version": "1.0.0",
"id": "
5. Select `collate-teams-bot.zip`.
6. Click **Add**.
**For organization-wide deployment (requires Teams admin):**
1. Go to [Teams Admin Center](https://admin.teams.microsoft.com).
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
| Issue | Possible Cause | Solution |
| ---------------------------------- | ---------------------------- | ------------------------------------------------------------------- |
| Bot not found in Teams search | Single-tenant bot | Single-tenant bots require app package upload (see Step 6 Option B) |
| "You do not have permission" error | Single-tenant or org policy | Upload app package manually or contact Teams admin |
| Bot not responding | Messaging endpoint incorrect | Verify the endpoint URL in Azure Bot Configuration |
| 401 Unauthorized | Invalid credentials | Double-check App ID and Password match Azure configuration |
| No AI responses | AI Platform not enabled | Ensure AI Platform is enabled in Collate configuration |
| Timeout errors | Network issues | Check network connectivity between Teams and Collate server |
| Bot added but can't message | Teams channel not enabled | Verify Teams channel is enabled in Azure Bot Channels |
| Can't upload custom app | Sideloading disabled | Ask Teams admin to enable custom app uploads in admin center |
## 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](https://docs.microsoft.com/en-us/azure/bot-service/)
* [Microsoft Teams Bot Development](https://docs.microsoft.com/en-us/microsoftteams/platform/bots/what-are-bots)
* [Adaptive Cards Documentation](https://adaptivecards.io/)