Microsoft Teams

BEFORE YOU START: Confirm your Microsoft Teams license allows custom apps before starting this set up.

Confirm the plan they have and understand if custom apps are allow and if with any limits.
Publishing custom StackAI agents to Microsoft Teams requires the organization to have a Microsoft 365 plan that supports custom app sideloading (Microsoft 365 Business Basic or higher; free and Teams Essentials tiers do not support this).

Use Microsoft Teams to expose a workflow inside your workspace.

You can deploy a Teams bot to Azure in two ways:

If you plan to use multiple agents, use the automated deployment flow.

Automated Deployment (PowerShell)

Use the deploy_teams_bot.ps1 script to automate the Azure setup.

Read the overview, review and prepare the prerequisites, and then follow the deployment steps.

Overview

The deploy_teams_bot.ps1 script automates:

Azure AD app registration for a single-tenant app
Azure Bot Service creation
Teams app manifest package generation
Optional upload to your organization's Teams app catalog

The script also includes:

Pre-flight validation
Rollback support
Idempotency, so it is safe to re-run
Dry-run mode
Detailed logging

Prerequisites

1. Deployment script

Download deploy_teams_bot.ps1.

53KB

deploy_teams_bot.ps1

Open

2. Required software

This is the easiest option. It requires no local installation.

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. Icon Files

To deploy the chatbot, two icon files must be provided: color.png and outline.png. The table below outlines the specifications for these files:

Icon Type

File Name

Requirements

Example Files

Color

color.png

192x192 pixels, PNG format, max 1000 KB

color.png

Outline

outline.png

32x32 pixels, PNG format, white with transparency

outline.png

5. Bot Configuration

There are two options:

Create a bot-config.json file and update it with your values:

{
  "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"
}

.\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"

Script parameters

Parameter

Description

-botName

Azure resource name. Use 3-63 characters, letters, numbers, and hyphens only.

-resourceGroup

Azure resource group name

-subscriptionId

Azure subscription ID in GUID format

-messagingEndpoint

HTTPS endpoint for Teams messages. Use your Stack AI endpoint.

Deployment Steps

1. Prepare your environment

Make sure the prerequisites are installed and configured.
Gather your Azure subscription details from the Subscriptions section in Azure.

Go to StackAI Interface.
1. Select the Microsoft Teams Interface option in the options menu.
2. Copy your Messaging Endpoint from the StackAI deployment interface.
Validate your configuration

Run a dry run before you create resources:

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

The dry run checks:

Input parameters
Prerequisites and permissions
Icon file requirements
Azure resource access

2. Run the deployment

Go to https://shell.azure.com.
Select the PowerShell environment.
Upload the deploy_teams_bot.ps1., icon files, and bot-config.json.
Run the script:

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

If validation succeeds, you can also save credentials and logs:

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

3. Save the credentials

The script prints credentials when it finishes:

=== 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

Save the client secret immediately. Azure will not show it again.

4. Configure the Stack AI interface

Open the Interface tab for the workflow you want to publish as a Microsoft Teams chatbot.
Enter the App ID, Tenant ID, and Client Secret from the script output.
Verify that the messaging endpoint matches.

5. Upload the app to Teams

Open Microsoft Teams.

Option A: Organization catalog

Use this option if you ran the script with -uploadToOrgCatalog.

Go to Apps > Built for your org.
Find and install your bot.

Option B: Manual upload

Go to Apps > Manage your apps > Upload a custom app.
Select Upload for [your organization] or Upload for me or my teams.
Upload the [BotName].zip file.

If you need a bot in group messages, it needs to be uploadedto the whole org instead of making it a personal app.

6. Test the bot

Start a new chat with the bot in Teams.
Send a test message.
Confirm that 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

Update an existing bot

The script is idempotent, so you can safely run it again:

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

If the script finds existing resources, it prompts you:

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

Type Y to update the existing bot.

Export credentials to JSON

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

Keep exported credential files secure. Do not commit them to source control.

Rollback behavior

If deployment fails, the script prompts you to roll back:

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

Type Y to delete resources created during this run
Type N to leave resources for manual inspection
Use -noRollback to disable rollback prompts

The script only deletes resources it created during the current run. It does not delete pre-existing resources.

Troubleshooting

View full help

Get-Help .\deploy_teams_bot.ps1 -Full

View examples

Get-Help .\deploy_teams_bot.ps1 -Examples

Manual Deployment

1. Open Azure Portal

Open Azure Portal and start the application setup.

Go to Azure Portal

2. Create a new app registration

Go to App registrations and click New registration.

3. Register the application

Enter an app name, select Accounts in any organizational directory, and click Register.

4. Copy the Application ID

After registration, the Microsoft Entra ID overview page opens.

Copy the Application (client) ID and save it for later.

5. Add web authentication

In the left menu, under Manage, select Authentication.
Under Web, select Add URI.
Enter https://token.botframework.com/.auth/web/redirect.
Click Save.

6. Configure the redirect URI

Add your redirect URI and enable Access tokens and ID tokens.

Use this redirect URI:

{BASE_INFERENCE_URL}/auth-end

7. Create a client secret

In the left menu, under Manage, select Certificates & secrets.
Under Client secrets, select + New client secret.
Enter a description and click Add.
Copy the secret value immediately.

8. Add API permissions

In the left menu, select API permissions.
Click + Add a permission and select Microsoft Graph.
Select Application permissions.
Expand User and select User.Read.All.
Click Add permissions.

9. Add the Application ID URI

In the left menu, under Manage, select Expose an API.
Set the Application ID URI to api://api.stack-ai.com/<APP_ID>.
Click Save.

10. Add a scope

In the left menu, under Manage, select Expose an API.
Click + Add a scope.
Enter access_as_user for the scope name.
Under Who can consent?, select Admins and users.

Use these values:

Admin consent display name: Teams can access the user's profile
Admin consent description: Allows Teams to call the app's web APIs as the current user
User consent display name: Teams can access the user profile and make requests on the user's behalf
User consent description: Enable Teams to call this app's APIs with the same rights as the user
State: Enabled

Then click Add scope.

11. Add authorized client applications

In the left menu, under Manage, select Expose an API.
Under Authorized client applications, click + Add a client application.
Add both Teams client IDs:
- Teams mobile or desktop: 1fec8e78-bce4-4aaf-ab1b-5451cc387264
- Teams web: 5e3ce6c0-2b1f-4285-8d4b-75ee78787346
Select the authorized scopes checkbox.
Click Add application.

12. Create the Azure Bot resource

Go to Home and click + Create a resource.
Search for Azure Bot.
Select Azure Bot and click Create.

Use these settings:

Bot handle: your bot name
Subscription: your Azure subscription
Resource group: select an existing group or create a new one
Pricing: F0 Free
Microsoft App ID type: Single Tenant
Creation type: Use existing app registration
App ID: the Application ID you copied earlier

13. Add the Microsoft Teams channel

In the left menu, select Channels.
Under Available Channels, select Microsoft Teams.
Accept the Terms of Service and click Apply.

14. Add the messaging endpoint

In the left menu, under Settings, select Configuration.
Set the messaging endpoint to:

https://api.stack-ai.com/msft-teams/<YOUR_PROJECT_ID>/messages?api_key=<YOUR_API_KEY>

Replace <YOUR_PROJECT_ID> with the workflow ID from your URL.
Replace <YOUR_API_KEY> with your API key.
Click Apply.

15. Save the Stack AI interface

Return to Stack AI and save the interface configuration.

16. Upload the app to Teams

Open Microsoft Teams.
In the left sidebar, click Apps.

Go to Manage your apps.

Click Upload an app and choose the upload option you want.

You need a package that contains:

manifest.json
color.png
outline.png

Use the template below for manifest.json.

Replace:

"botId" with the Microsoft App ID from step 4
"id" with a unique UUID for this Teams app package

{
  "$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 the app to a channel

Open the channel where you want to use the bot.
Click Apps.

Select your app and add it to the channel.
Mention the bot with @ followed by its name.

If you update the workflow later, publish it again so Teams uses the latest version.

PreviousSlack App NextWhatsApp / SMS with Twilio

Last updated 6 days ago

Was this helpful?

hashtagAutomated Deployment (PowerShell)

hashtagOverview

hashtagPrerequisites

hashtag1. Deployment script

hashtag2. Required software

hashtag3. Required permissions

hashtag4. Icon Files

hashtag5. Bot Configuration

hashtagDeployment Steps

hashtag1. Prepare your environment

hashtag2. Run the deployment

hashtag3. Save the credentials

hashtag4. Configure the Stack AI interface

hashtag5. Upload the app to Teams

hashtag6. Test the bot

hashtagAdvanced usage

hashtagFull deployment with all options

hashtagUpdate an existing bot

hashtagExport credentials to JSON

hashtagRollback behavior

hashtagTroubleshooting

hashtagView full help

hashtagView examples

hashtagManual Deployment

hashtag1. Open Azure Portal

hashtag2. Create a new app registration

hashtag3. Register the application

hashtag4. Copy the Application ID

hashtag5. Add web authentication

hashtag6. Configure the redirect URI

hashtag7. Create a client secret

hashtag8. Add API permissions

hashtag9. Add the Application ID URI

hashtag10. Add a scope

hashtag11. Add authorized client applications

hashtag12. Create the Azure Bot resource

hashtag13. Add the Microsoft Teams channel

hashtag14. Add the messaging endpoint

hashtag15. Save the Stack AI interface

hashtag16. Upload the app to Teams

hashtag17. Add the app to a channel

Automated Deployment (PowerShell)

Overview

Prerequisites

1. Deployment script

2. Required software

3. Required permissions

4. Icon Files

5. Bot Configuration

Deployment Steps

1. Prepare your environment

2. Run the deployment

3. Save the credentials

4. Configure the Stack AI interface

5. Upload the app to Teams

6. Test the bot

Advanced usage

Full deployment with all options

Update an existing bot

Export credentials to JSON

Rollback behavior

Troubleshooting

View full help

View examples

Manual Deployment

1. Open Azure Portal

2. Create a new app registration

3. Register the application

4. Copy the Application ID

5. Add web authentication

6. Configure the redirect URI

7. Create a client secret

8. Add API permissions

9. Add the Application ID URI

10. Add a scope

11. Add authorized client applications

12. Create the Azure Bot resource

13. Add the Microsoft Teams channel

14. Add the messaging endpoint

15. Save the Stack AI interface

16. Upload the app to Teams

17. Add the app to a channel