Microsoft Teams

Configure your Microsoft Teams application to use your workflow within your workspace.

You can deploy your Microsoft Teams bot to Azure using one of two methods:

1. Automated Deployment (PowerShell)

2. Manual Deployment (Azure Portal)

Automated Deployment (PowerShell)

Deploy a Microsoft Teams bot to Azure using the automated PowerShell deployment script.

Overview

The deploy_teams_bot.ps1 script automates the entire deployment process:

• Azure AD App Registration (Single Tenant)

• Azure Bot Service resource

• Teams app manifest package generation

• Optional upload to your organization's Teams app catalog

The script includes pre-flight validation, rollback capabilities, idempotency (safe to re-run), dry-run mode, and comprehensive logging.

Prerequisites

1. Deployment Script

Download deploy_teams_bot.ps1.

53KB

deploy_teams_bot.ps1

Open

2. Required Software

Option A: Azure Cloud Shell (Recommended - No Installation Required)

1. Navigate to https://shell.azure.com

2. Select PowerShell environment

3. Upload the deployment script and icon files

4. Run the script directly in the cloud shell

Option B: Local Installation

• Azure CLI - Install from https://aka.ms/installazurecli

• Az PowerShell Module - Install with:

  Install-Module -Name Az -Scope CurrentUser

3. Required Permissions

Permission	Purpose
Azure AD: Application Developer or Global Admin	Create app registrations
Azure Subscription: Contributor	Create bot resources
Teams Admin (optional)	Required only for -uploadToOrgCatalog

4. Required Files

File	Requirements
Color Icon (color.png)	192x192 pixels, PNG format, max 1000KB
Outline Icon (outline.png)	32x32 pixels, PNG format, white with transparency

Quick Start

Basic Deployment

.\deploy_teams_bot.ps1 `
  -botName "MyCompanyBot" `
  -teamsDisplayName "My Company Assistant",
  -botDescription "My company's customer support assistant" `
  -resourceGroup "rg-bots" `
  -subscriptionId "12345678-1234-1234-1234-123456789012" `
  -messagingEndpoint "https://api.stack-ai.com/msft-teams/YOUR_BOT_ID/messages?api_key=YOUR_API_KEY"

Using a Configuration File

Create a bot-config.json file:

{
  "botName": "MyCompanyBot",
  "teamsDisplayName": "My Company Assistant",
  "botDescription": "My company's customer support assistant",
  "resourceGroup": "rg-bots",
  "location": "westus",
  "subscriptionId": "12345678-1234-1234-1234-123456789012",
  "messagingEndpoint": "https://api.stack-ai.com/msft-teams/YOUR_BOT_ID/messages?api_key=YOUR_API_KEY",
  "colorIconPath": "color.png",
  "outlineIconPath": "outline.png"
}

Run the script:

.\deploy_teams_bot.ps1 -configFile "bot-config.json"

Script Parameters

Required Parameters

Parameter	Description
-botName	Azure resource name (3-63 chars, alphanumeric and hyphens, must start with letter)
-resourceGroup	Azure resource group name
-subscriptionId	Azure subscription ID (GUID format)
-messagingEndpoint	HTTPS endpoint for Teams messages (your Stack AI endpoint)

Optional Parameters

Parameter	Default	Description
-teamsDisplayName	Same as botName	Display name shown in Teams (can include spaces)
-botDescription	"[teamsDisplayName] Teams bot"	Description shown in Teams app listing
-location	westus	Azure region ( westus, or westeurope)
-colorIconPath	color.png	Path to 192x192 color icon
-outlineIconPath	outline.png	Path to 32x32 outline icon
-configFile	-	JSON config file path (CLI params override file values)
-outputFile	-	Save credentials to JSON file
-logFile	-	Save detailed logs for troubleshooting
-uploadToOrgCatalog	$false	Upload to organization's Teams app catalog
-noRollback	$false	Disable automatic rollback on failure
-dryRun	$false	Validate without creating resources

Deployment Steps

1. Prepare Your Environment

1. Ensure all prerequisites are installed

2. Prepare your icon files (color.png and outline.png)

3. Gather your Azure subscription details

4. Copy your messaging endpoint URL from the Stack AI deployment interface

2. Validate Configuration (Dry Run)

Before creating resources, validate your configuration:

.\deploy_teams_bot.ps1 -configFile "bot-config.json" -dryRun

The dry run will:

• Validate all input parameters

• Check prerequisites and permissions

• Verify icon files meet requirements

• Confirm Azure resource access

3. Run the Deployment

Once validation passes:

.\deploy_teams_bot.ps1 `
  -configFile "bot-config.json" `
  -outputFile "credentials.json" `
  -logFile "deployment.log"

4. Save the Credentials

The script displays credentials at completion:

=== Configuration for Stack AI Platform ===
  Bot Name:           MyCompanyBot
  Teams Display Name: My Company Assistant
  App ID:             a1b2c3d4-e5f6-7890-abcd-ef1234567890
  Tenant ID:          12345678-1234-1234-1234-123456789012
  Client Secret:      abc123def456ghi789jkl012mno345pqr678
  Messaging Endpoint: https://api.stack-ai.com/msft-teams/...
  App Package:        C:\path\to\MyCompanyBot.zip

IMPORTANT: Save the Client Secret immediately - you won't be able to see it again!

5. Configure Stack AI

1. Navigate to your Stack AI bot configuration

2. Enter the App ID, Tenant ID, and Client Secret

3. Verify the messaging endpoint matches

6. Upload to Teams

Option A: Organization Catalog (with -uploadToOrgCatalog)

The app is already available:

1. Open Microsoft Teams

2. Go to Apps > Built for your org

3. Find and install your bot

Option B: Manual Upload

1. Open Microsoft Teams

2. Go to Apps > Manage your apps > Upload a custom app

3. Select Upload for [your organization] or Upload for me or my teams

4. Choose the [BotName].zip file

7. Test the Bot

1. In Teams, start a new chat with your bot

2. Send a test message

3. Verify the bot responds correctly

Advanced Usage

Full Deployment with All Options

.\deploy_teams_bot.ps1 `
  -botName "ProductionBot" `
  -teamsDisplayName "Production Assistant" `
  -botDescription "Production customer support bot with AI assistance" `
  -resourceGroup "rg-prod-bots" `
  -location "westus" `
  -subscriptionId "12345678-1234-1234-1234-123456789012" `
  -messagingEndpoint "https://api.stack-ai.com/msft-teams/YOUR_BOT_ID/messages?api_key=YOUR_API_KEY" `
  -colorIconPath "assets/bot-color.png" `
  -outlineIconPath "assets/bot-outline.png" `
  -outputFile "prod-credentials.json" `
  -logFile "prod-deployment.log" `
  -uploadToOrgCatalog

Updating an Existing Bot

The script is idempotent and can safely update existing resources:

.\deploy_teams_bot.ps1 -configFile "bot-config.json"

When existing resources are detected:

⚠ Existing resources detected!
Continue and update existing resources? (Y/N)

Type Y to update the existing bot configuration.

Secure Credential Export

Export credentials to a JSON file for programmatic access:

.\deploy_teams_bot.ps1 `
  -configFile "bot-config.json" `
  -outputFile "secure-credentials.json"

Security Note: Keep this file secure and never commit it to source control!

Rollback Behavior

If deployment fails at any step, the script prompts for rollback:

!!! Deployment failed at: [Step Name] !!!
Would you like to rollback and delete created resources? (Y/N)

• Type Y to delete all resources created during this run

• Type N to leave resources for manual inspection

• Use -noRollback flag to disable rollback prompts entirely

Note: The script only rolls back resources it created. Pre-existing resources (like an existing app registration or bot) are never deleted during rollback.

Troubleshooting

View Script Help

Get-Help .\deploy_teams_bot.ps1 -Full

View Examples

Get-Help .\deploy_teams_bot.ps1 -Examples

Manual Deployment

1. Navigate to Azure Portal

Navigate to Azure Portal to create your application.

Go to Azure Portal

2. New Registration

Select App registrations and Click on "New Registration" to create a new app.

3. Register Application

Enter the name of your app and select "Accounts in any organizational directory" and click on "Register".

4. Application ID

Your app is registered in Microsoft Entra ID. The app overview page appears.

Copy the Application (client) ID from Microsoft Entra ID, and paste it in your configuration.

5. Add Web Authentication

In the left pane, under Manage, select Authentication. Under Web, select Add URI.

Enter https://token.botframework.com/.auth/web/redirect and Select Save.

6. Configure Redirect URI

Enter the redirect URI and enable Access tokens and ID tokens.

The redirect URI should be: {BASE_INFERENCE_URL}/auth-end

7. Create a client secret

1. In the left pane, under Manage, select Certificates & secrets.

2. Under Client secrets, select + New client secret.

3. The Add a client secret window appears, enter the description and select Add.

Select Copy to clipboard to save the client secret value for further use.

8. Add API permissions

1. In the left pane, select API permissions.

2. Select "+ Add a permission", then select Microsoft Graph.

3. Under "What type of permissions does your application need?", select Application permissions.

4. Under "Select permissions", expand User and select User.Read.All.

5. Click "Add permissions" to save the changes.

9. Add Application ID URI

1. In the left pane, under Manage, select Expose an API.

2. Update the Application ID URI to api://api.stack-ai.com/<APP_ID> and select Save.

10. Add a scope

1. In the left pane, under Manage, select Expose an API.

2. Select + Add a scope.

3. Enter access_as_user as the Scope name.

4. Under Who can consent?, select Admins and users.

Update the values for the rest of the fields as follows:

• Enter "Teams can access the user's profile" as Admin consent display name.

• Enter "Allows Teams to call the app's web APIs as the current user" as Admin consent description.

• Enter "Teams can access the user profile and make requests on the user's behalf" as User consent display name.

• Enter "Enable Teams to call this app's APIs with the same rights as the user" as User consent description.

• Ensure that State is set to Enabled.

• Select Add scope.

11. Add client application

1. In the left pane, under Manage, select Expose an API.

2. Under Authorized client applications, select + Add a client application.

3. Add Teams mobile or desktop and Teams web application:

   • For Teams mobile or desktop: Enter Client ID as 1fec8e78-bce4-4aaf-ab1b-5451cc387264

   • For Teams web: Enter Client ID as 5e3ce6c0-2b1f-4285-8d4b-75ee78787346

4. Select the Authorized scopes checkbox.

5. Select Add application.

12. Create Azure Bot Resource

1. Go to Home and select + Create a resource

2. In the search box, enter "Azure Bot" and select Enter

3. Select Azure Bot, then select Create

For the bot configuration:

• Enter a name for your bot in Bot handle

• Select your Subscription from the dropdown

• Select or create a Resource group

• Under Pricing, select "FO Free" plan

• For Microsoft App ID, select Type of App as "Single Tenant"

• In Creation type, select "Use existing app registration"

• Enter the App ID from your previous registration

13. Add a Teams channel

1. In the left pane, select Channels.

2. Under Available Channels, select Microsoft Teams.

3. Select the checkbox to accept the Terms of Service and Apply.

14. Add Messaging Endpoint

1. In the left pane, under Settings, select Configuration.

2. Update the Messaging endpoint with the following URL: https://api.stack-ai.com/msft-teams/<YOUR_PROJECT_ID>/messages?api_key=<YOUR_API_KEY>

3. Replace <YOUR_PROJECT_ID> with the workflow id in your URL.

Click Apply to save the configuration.

15. Save StackAI Interface

Go back to StackAI's website and save the StackAI interface in the top right corner.

16. Upload App to Teams

Now, go to Microsoft Teams. On the left sidebar, click Apps.

Now, go to 'Manage Your Apps'.

Click, 'Upload an App.' Then, choose an option.

Here, you will be prompted to upload your app's manifest. The manifest file should contain a JSON file, and two .PNG files, named color.png and outline.png. These two images will serve as the icons of your app. The JSON file must be named manifest.json. Feel free to use the following template, replace "botId" with the Microsoft App ID from step 4. "id" can be a randomly generated UUID, but must be unique to each bot you upload to Microsoft Teams.

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.19/MicrosoftTeams.schema.json",
  "manifestVersion": "1.19",
  "version": "1.0.0",
  "id": "<YOUR_APP_ID>",
  "developer": {
    "name": "Stack AI",
    "websiteUrl": "https://www.stack-ai.com",
    "privacyUrl": "https://www.stack-ai.com/privacy",
    "termsOfUseUrl": "https://www.stack-ai.com/terms"
  },
  "name": {
    "short": "Stack AI Bot",
    "full": "Stack AI Bot"
  },
  "description": {
    "short": "Stack AI Microsoft Teams bot",
    "full": "Stack AI Microsoft Teams bot"
  },
  "icons": {
    "outline": "outline.png",
    "color": "color.png"
  },
  "accentColor": "#ffffff",
  "bots": [
    {
      "botId": "<YOUR_APP_ID>",
      "needsChannelSelector": false,
      "isNotificationOnly": false,
      "supportsFiles": true,
      "scopes": [
        "personal",
        "team",
        "groupChat"
      ]
    }
  ],
  "authorization": {
    "permissions": {
      "resourceSpecific": [
        {
          "name": "ChannelMessage.Read.Group",
          "type": "Application"
        }
      ]
    }
  },
  "webApplicationInfo": {
    "id": "<YOUR_APP_ID>",
    "resource": "api://botid-<YOUR_APP_ID>"
  },
  "permissions": [],
  "validDomains": [
    "api.stack-ai.com"
  ]
}

17. Add App to a Channel

Open a channel where you'd like to use your chatbot. Click on apps.

Select your app and add it to the channel. Now you can reference your bot as if it's a member of your channel by typing @ and the name of your bot.

Don't forget the publish if you make changes to your agent's workflow so that your bot is updated!