Microsoft Teams Integration

Connect Microsoft Teams so your team can message the Assemble bot in channels, group chats, and direct messages.

Prerequisites

• An Azure account with permissions to create Bot resources
• A Microsoft Teams environment where you can install custom apps
• Your Assemble workspace's webhook URL (found in Settings > Integrations)

Step 1: Create an Azure Bot

1. Go to the Azure Portal and search for Azure Bot
2. Click Create and fill in the required fields:
   • Bot handle: A unique name (e.g., assemble-bot)
   • Subscription: Your Azure subscription
   • Resource group: Create new or use existing
3. Under Microsoft App ID, select Create new Microsoft App ID
4. Select Single Tenant for enterprise use (or Multi Tenant for broader access)
5. Click Review + Create → Create

Step 2: Get your credentials

Once the bot resource is created, you need three values:

App ID

Bot resource → Configuration → copy the Microsoft App ID

App Password

1. In the Configuration page, click Manage Password
2. This opens Certificates & secrets
3. Click New client secret → add a description → choose expiry
4. Copy the Value column (not the Secret ID)

Tenant ID

Bot resource → Overview → copy the Directory (tenant) ID

Step 3: Set the messaging endpoint

1. In the bot resource, go to Configuration
2. Set the Messaging endpoint to:

https://YOUR_DEPLOYMENT.convex.site/webhooks/teams

3. Click Apply

Step 4: Enable the Teams channel

1. In the bot resource, go to Channels
2. Click Microsoft Teams
3. Accept the terms of service
4. Click Apply

Step 5: Create the app manifest

Create a file called manifest.json:

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",
  "manifestVersion": "1.16",
  "version": "1.0.0",
  "id": "YOUR_APP_ID",
  "packageName": "com.yourcompany.assemble",
  "developer": {
    "name": "Your Company",
    "websiteUrl": "https://your-domain.com",
    "privacyUrl": "https://your-domain.com/privacy",
    "termsOfUseUrl": "https://your-domain.com/terms"
  },
  "name": {
    "short": "Assemble",
    "full": "Assemble Data Analyst"
  },
  "description": {
    "short": "Chat with Assemble AI",
    "full": "Talk to the Assemble data analyst from Teams. Ask questions, run analyses, and get insights."
  },
  "icons": {
    "outline": "outline.png",
    "color": "color.png"
  },
  "accentColor": "#FFFFFF",
  "bots": [
    {
      "botId": "YOUR_APP_ID",
      "scopes": ["personal", "team", "groupchat"],
      "supportsFiles": false,
      "isNotificationOnly": false
    }
  ],
  "permissions": ["identity", "messageTeamMembers"],
  "validDomains": []
}

Replace YOUR_APP_ID with the App ID from step 2.

Icons

You need two PNG icons in the same directory as the manifest:

• outline.png — 32×32 pixels, transparent background
• color.png — 192×192 pixels, your app icon with background color

ZIP the manifest and both icons together into a single .zip file.

Step 6: Upload to Teams

For testing (sideload)

1. Open Microsoft Teams
2. Go to Apps → Manage your apps
3. Click Upload an app → Upload a custom app
4. Select your ZIP file

For your organization

1. Go to the Teams Admin Center
2. Navigate to Teams apps → Manage apps
3. Click Upload new app
4. Select your ZIP file

Step 7: Connect in Assemble

1. In your Assemble workspace, go to Settings > Integrations
2. Click Connect Teams
3. Paste the App ID (from step 2)
4. Paste the App Password (from step 2)
5. Optionally paste the Tenant ID (required for single-tenant apps)
6. Click Connect

Send a message to the bot in Teams to start chatting with Assemble.

Usage

Personal chat

Find the bot in your Teams apps and start a 1:1 conversation.

Channel mentions

@mention the bot in a team channel. It will reply in a thread.

Group chats

Add the bot to a group chat — it responds when mentioned.

Artifacts

When the bot creates an artifact, it posts a summary with a link to view the full report in the web app.

Receiving all channel messages

By default, the bot only receives @mentions in channels. To receive all messages without being mentioned, add Resource-Specific Consent (RSC) permissions to your manifest:

{
  "authorization": {
    "permissions": {
      "resourceSpecific": [
        {
          "name": "ChannelMessage.Read.Group",
          "type": "Application"
        }
      ]
    }
  }
}

Add this block at the top level of your manifest.json.

Limitations

Troubleshooting

Bot doesn't respond

• Check that the integration is Enabled in Settings > Integrations
• Verify the messaging endpoint URL in Azure Bot Configuration
• Make sure the Teams channel is enabled in the bot resource

Authentication errors

• Verify the App Password (client secret) hasn't expired
• For single-tenant apps, ensure the Tenant ID is set correctly
• Check that the App ID matches between the Azure Bot and Assemble settings

App doesn't appear in Teams

• Wait a few minutes after uploading — it can take time to propagate
• Check the Teams Admin Center for any policy restrictions
• Try sideloading for testing first