users-medicalMicrosoft Teams

circle-info

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.

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

Outline

outline.png

32x32 pixels, PNG format, white with transparency

5. Bot Configuration

There are two options:

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:

The dry run checks:

  • Input parameters

  • Prerequisites and permissions

  • Icon file requirements

  • Azure resource access

2. Run the deployment

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

3. Save the credentials

The script prints credentials when it finishes:

circle-exclamation

4. Configure the Stack AI interface

  1. Open the Interface tab for the workflow you want to publish as a Microsoft Teams chatbot.

  2. Enter the App ID, Tenant ID, and Client Secret from the script output.

  3. 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.

  1. Go to Apps > Built for your org.

  2. Find and install your bot.

Option B: Manual upload

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

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

  3. 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

  1. Start a new chat with the bot in Teams.

  2. Send a test message.

  3. Confirm that the bot responds correctly.

Advanced usage

Full deployment with all options

Update an existing bot

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

If the script finds existing resources, it prompts you:

Type Y to update the existing bot.

Export credentials to JSON

circle-exclamation

Rollback behavior

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

  • 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

View examples

Manual Deployment

1. Open Azure Portal

Open Azure Portal and start the application setup.

Go to Azure Portalarrow-up-right

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

  1. In the left menu, under Manage, select Authentication.

  2. Under Web, select Add URI.

  3. Enter https://token.botframework.com/.auth/web/redirect.

  4. Click Save.

6. Configure the redirect URI

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

Use this redirect URI:

7. Create a client secret

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

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

  3. Enter a description and click Add.

  4. Copy the secret value immediately.

8. Add API permissions

  1. In the left menu, select API permissions.

  2. Click + Add a permission and select Microsoft Graph.

  3. Select Application permissions.

  4. Expand User and select User.Read.All.

  5. Click Add permissions.

9. Add the Application ID URI

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

  2. Set the Application ID URI to api://api.stack-ai.com/<APP_ID>.

  3. Click Save.

10. Add a scope

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

  2. Click + Add a scope.

  3. Enter access_as_user for the scope name.

  4. 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

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

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

  3. Add both Teams client IDs:

    • Teams mobile or desktop: 1fec8e78-bce4-4aaf-ab1b-5451cc387264

    • Teams web: 5e3ce6c0-2b1f-4285-8d4b-75ee78787346

  4. Select the authorized scopes checkbox.

  5. Click Add application.

12. Create the Azure Bot resource

  1. Go to Home and click + Create a resource.

  2. Search for Azure Bot.

  3. 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

  1. In the left menu, select Channels.

  2. Under Available Channels, select Microsoft Teams.

  3. Accept the Terms of Service and click Apply.

14. Add the messaging endpoint

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

  2. Set the messaging endpoint to:

  1. Replace <YOUR_PROJECT_ID> with the workflow ID from your URL.

  2. Replace <YOUR_API_KEY> with your API key.

  3. Click Apply.

15. Save the Stack AI interface

Return to Stack AI and save the interface configuration.

16. Upload the app to Teams

  1. Open Microsoft Teams.

  2. In the left sidebar, click Apps.

  1. Go to Manage your apps.

  1. 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

17. Add the app to a channel

  1. Open the channel where you want to use the bot.

  2. Click Apps.

  1. Select your app and add it to the channel.

  2. Mention the bot with @ followed by its name.

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

Last updated

Was this helpful?