Langburp

Quickstart: Microsoft Teams

Introduction

This guide will walk you through the process of setting up a new Microsoft Teams bot and app for your Langburp project. By following these instructions, Microsoft will also create some resources in Azure/Entra ID (formerly known as Azure AD) in the background for you.

There are at least half a dozen ways to create the required resources in Microsoft, but the following is the simplest and best-supported way we could find.

If you're not familiar with Microsoft, setting up the Microsoft Teams integration can be daunting. We've done our best to simplify things, however, it's not as easy to setup as a Slack integration. If you have any trouble, please reach out to us at [email protected] or via the chat widget here.

Prerequisites

In addition to a Langburp account, you'll need a "school or work" Microsoft account. You won't be able to use a personal Microsoft/xBox/Outlook/etc. account to log into the Microsoft Teams Developer portal (which is required for this tutorial).

There are a few ways to get a "school or work" Microsoft account and access to Microsoft Teams:

  • One of the easiest ways is to start a free trial of Microsoft 365 (any plan will work) in order to setup your domain for Azure AD/Entra ID, MPN (later on), and finally, to get a real Microsoft Teams instance to test with
  • You can also join the Microsoft 365 Developer Program to get free Microsoft 365 sandbox licenses. Microsoft allows signing up for a Developer account with a personal Microsoft account
  • Signing up for a Microsoft Azure account will allow you to provision a new Azure AD/Entra ID instance. From there you can register an enterprise .onmicrosoft.com account that you can use to access the Teams Developer Portal, however, you will still need another Microsoft 365 account or Developer Program account to provision a Microsoft Teams sandbox

Finally, to publish your Teams App to the Microsoft App Store (not covered in this tutorial), you'll need to join Microsoft's Partner Network (MPN) and get an MPN ID. This may take some time to process, so if you're on a tight schedule, we recommend starting this process ahead of time. You can learn more about MPN and how to enroll from Microsoft.

Step 1: Create a Langburp Project

  1. If you haven't already, navigate to the Langburp Console
  2. Create a new Langburp project or select an existing project

Step 2: Open your Project's Teams Integration Page

  1. In your project sidebar, find the "Integrations" section
  2. Click on "Setup Teams"
  3. Click the "Setup your teams integration" button
  4. You'll see a form where you'll input the Teams bot credentials we'll obtain in the following steps

Step 3: Create a New Teams Bot

  1. Navigate to the Microsoft Teams Developer Portal
  2. Click the "+ New Bot" button
  3. Enter a name for your bot (this can be any name you choose)
  4. Click "Add" to create the bot

Step 4: Get the Bot ID

  1. After the bot is created, look at your browser's address bar
  2. The URL will look like: https://dev.teams.microsoft.com/bots/7650ddd8-d2c8-4bf4-939e-8d762c6c02db/configure
  3. Copy the ID portion from the URL (the string between "bots/" and "/configure")
    • In this example, it would be: 7650ddd8-d2c8-4bf4-939e-8d762c6c02db
  4. Return to the Langburp Teams integration form
  5. Paste this ID into the "Bot ID" field

Step 5: Generate Client Secret

  1. Back to the Teams Developer Portal's page for the bot you just created, click on "Client Secrets" in the left sidebar menu
  2. Click "Add a client secret for your bot"
  3. A dialog will appear with your new client secret
  4. Copy this secret immediately - you won't be able to see it again after closing the dialog
  5. Return to the Langburp Teams integration form
  6. Paste the secret into the "Bot Password" field

Step 6: Save the Teams Credentials in Langburp

  1. Review that both the Bot ID and Bot Password fields are filled in correctly
  2. Click "Save" to persist the credentials

Step 7: Bot Endpoint Configuration

  1. Once you've saved the credentials successfully, copy the "Bot Endpoint Address" that appeared below the credenntials form
  2. Click the customized Microsoft Teams Developer Portal link in Langburp to navigate to your Teams bot's endpoint configration page
  3. Paste the Endpoint Address from Langburp into the "Bot endpoint address" field in your Teams bot's endpoint configuration page
  4. Make sure to click "Save" after pasting the Endpoint Address into the Teams bot's endpoint configration page.

Step 8: Create the Teams Application

  1. In Langburp, in the "Teams Manifest" card, click "Download App Package Zip" and save the package Zip archive
  2. Navigate to the Teams Developer Portal home page
  3. Click the "Import an app" card in the Teams Developer Portal
  4. When asked to select a file, make sure to upload the package Zip archive we downloaded from Langburp
  5. That's it! You've configured your Langburp project and Microsoft Teams bot and app combo!

Testing your new Teams App

We suggest testing your Teams App from the Langburp console, however, you'll find that you can also install from your app's page in the Microsoft Teams Developer Portal.

Either option is functionally equivalent, and you should see the connection events on the Langburp Logs page once you've created your test connection.

From Langburp Console

In the Langburp console, under your new Teams integration tab or on the Connections page, click "Create a test connection" and select Microsoft Teams.

From Microsoft Teams Developer Portal

If you would like to test installing your app from the Microsoft Teams Developer Portal, click the "Preview in Teams" button in the top left of your new Teams app.

Integrating an Existing Microsoft Teams Bot and/or App

Microsoft Teams integrations require setting up two distinct resources on Microsoft's side: a 'bot' and an 'app'.

In general, if you'd like to use an existing Microsoft Teams bot and/or app with Langburp, you'll need to:

  1. Copy the bot's ID and Client Secret (aka "Bot Password") into Langburp's Bot ID and Bot Password credential fields for Teams. Make sure to save the credentials.
  2. If you're using an existing app, make sure to copy the app ID from the Teams Developer Portal -- you can find it in the manifest JSON as the id property or in your browser's address bar after the https://dev.teams.microsoft.com/apps/ part of the URL -- into Langburp's "App ID" credential field. The app ID is also a UUIDv4, so it could be easily confused with the Bot ID. Please watch out for that, or your app won't work
  3. Make sure to set the bot's Endpoint URL to point to Langburp (per the instructions above)
  4. If your existing Teams App's manifest hasn't been heavily customized, we suggest uploading the App Package Zip from Langburp directly to replace your existing app manifest. However, if you have a lot of customizations applied to your Teams App already, it's best to manually cherry-pick the necessary elements of Langburp's suggested Manifest JSON and add to your app's package manually. The Teams Developer Portal doesn't allow changes to the manifest JSON directly, so you'll have to download your App Package, unzip it, make the changes to the JSON file, zip it back up, and then upload the new zip to the Microsoft Teams Developer portal.

If you're using an existing Teams bot or app, make sure it's not being used by other services before modifying its configuration, as changes could affect existing integrations.