Branch: master
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Messaging Extension

In this demo, you will send post a message in a channel regarding a candidate using a messaging extension.


Developing apps for Microsoft Teams requires preparation for both the Office 365 tenant and the development workstation.

For the Office 365 Tenant, the setup steps are detailed on the Prepare your Office 365 Tenant page.

Download ngrok

As Microsoft Teams is an entirely cloud-based product, it requires all services it accesses to be available from the cloud using HTTPS endpoints. To enable the exercises to work within Microsoft Teams, a tunneling application is required.

This lab uses ngrok for tunneling publicly-available HTTPS endpoints to a web server running locally on the developer workstation. ngrok is a single-file download that is run from a console.

Update Demo solution

Make the following updates to the demo solution.

  1. Launch Visual Studio 2017 as an administrator.

  2. In Visual Studio 2017, select File > Open > Project/Solution.

  3. Select the officedev-talent-management.sln file from the Demos\02-messaging-extension folder.

Find the project URL

  1. In Solution Explorer, double-click on Properties.

  2. In the properties designer, select the Web tab.

  3. Note the project URL.

    Screenshot of Solution Explorer highlighting project URL.

Run the ngrok secure tunnel application

  1. Open a new Command Prompt window.

  2. Change to the directory that contains the ngrok.exe application.

  3. Run the command ngrok http [port] -host-header=localhost:[port]. Replace [port] with the port portion of the URL noted above.

  4. The ngrok application will fill the entire prompt window. Make note of the forwarding address using HTTPS. This address is required in the next step.

  5. Minimize the ngrok command prompt window. It is no longer referenced in this lab, but it must remain running.

    Screenshot of ngrok command prompt with local host highlighted.

Register the bot

  1. Go to the Microsoft Bot Framework and sign in. The bot registration portal accepts a work or school account or a Microsoft account.

NOTE: You must use this link to create a new bot: If you select the Create a bot button in the Bot Framework portal instead, you will create your bot in Microsoft Azure instead.

  1. Complete the bot profile section, entering a display name, unique bot handle and description.

    Screenshot of bot profile information page.

  2. Complete the configuration section.

    • For the Messaging endpoint, use the forwarding HTTPS address from ngrok prepended to the route to the MessagesController in the Visual Studio project. In the example, this is

    • Select the Create Microsoft App ID and password button. This opens a new browser window.

    • In the new browser window, the application is registered in Azure Active Directory. Select Generate an app password to continue.

    • An app password is generated. Copy the password and save it. You will use it in a subsequent step.

    • Select OK to close the dialog box.

    • Select the Finish and go back to Bot Framework button to close the new browser window and populate the app ID in the Paste your app ID below to continue textbox.

      Screenshot of configuration page with messaging endpoint and app ID displayed.

  3. Move to the bottom of the page. Agree to the privacy statement, terms of use and code of conduct and select the Register button. Once the bot is created, select OK to dismiss the dialog box. The Connect to channels page is displayed for the newly-created bot.

Note: The Bot migration message (shown in red) can be ignored for Microsoft5 Teams bots. Additional information can be found in the Microsoft Teams developer documentation, on the Create a bot page.

  1. The bot must be connected to Microsoft Teams. Select the Microsoft Teams logo.

    Screenshot of Microsoft Bot Framework with Microsoft Teams logo highlighted.

  2. Once the connection is complete, ensure the connection is enabled and select Done. The bot registration is complete.

    Screenshot of Microsoft Bot Framework with configuration message displayed.

    Note: Selecting Settings in the top navigation will re-display the profile and configuration sections. This can be used to update the messaging endpoint in the event ngrok is stopped, or the bot is moved to staging & production.

Configure the web project

The bot project must be configured with information from the registration.

  1. In Visual Studio, open the Web.config file. Locate the <appSettings> section.

  2. Enter the BotId. The BotId is the Bot handle from the Configuration section of the registration.

  3. Enter the MicrosoftAppId from the Configuration section of the registration.

  4. Enter the MicrosoftAppPassword, the auto-generated app password displayed in the dialog box during registration.

    Note: If you do not have the app password, the bot must be deleted and re-registered. An app password cannot be reset nor displayed.

  5. Open the manifest.json file just added to the project. The manifest.json file requires several updates:

    • The id property must contain the app ID from registration. Replace the token [microsoft-app-id] with the app ID.
    • The packageName property must contain a unique identifier. The industry standard is to use the bot's URL in reverse format. Replace the token [from-ngrok] with the unique identifier from the forwarding address.
    • The developer property has three URLs that should match the hostname of the Messaging endpoint. Replace the token [from-ngrok] with the unique identifier from the forwarding address.
    • The botId property in the bots collection property also requires the app ID from registration. Replace the token [microsoft-app-id] with the app ID.
    • Save and close the manifest.json file.
  6. Press F5 to build the solution and package and start the web service in the debugger. The debugger will start the default browser, which can be ignored. The next step uses the teams client.

Upload app into Microsoft Teams

Although not strictly necessary, in this lab the bot will be added to a new team.

  1. In the Microsoft Teams application, select the Add team link. Then select the Create team button.

    Screenshot of Microsoft Teams with Create Team button highlighted.

  2. Enter a team name and description. In this example, the team is named teams-bot-1. Select Next.

  3. Optionally, invite others from your organization to the team. This step can be skipped in this lab.

  4. The new team is shown. In the left-side panel, select the ellipses next to the team name. Choose Manage team from the context menu.

    Screenshot of Microsoft Teams with Manage Team highlighted.

  5. On the Manage team display, select Apps in the tab strip. Then select the Upload a custom app link at the bottom right corner of the application.

  6. Select the zip file from the bin folder that represents your app. Select Open.

  7. The app is displayed. The description and icon for the app is displayed.

    Screenshot of Microsoft Teams with new app displayed.

    The app is now uploaded into the Microsoft Teams application and the bot is available.

    Note: Adding the bot to a team invokes the system message ConversationUpdated. The code in MessageHelpers.cs determines if the message is in response to the bot being added, and initiates a 1:1 message with each member of the team.

    Screenshot of Microsoft Teams displaying new bot installed.

The bot is now installed and ready to run.

Send a message using the messaging Extension

The messaging extension must be invoked in a channel due to the scopes entered in the manifest.

  1. The extension is invoked by selecting the ellipsis below the compose box and selecting the bot.

    Screenshot of Microsoft Teams messaging extension.

  2. The initialRun property of a command is set to true, so Microsoft Teams will issue a command immediately when the extension is opened.

    Screenshot of messaging extension with prepopulated results.

  3. Selecting an item in the messaging extension will populate the message compose area the result. The user can then augment the message.

    Screenshot of Microsoft Teams message compose area with extension result shown.

  4. Show the MessagesController class. Highlight the code block at lines 44-52 that determine if the activity represents a messaging extension request. Point out that this code block returns the messaging extension results in the body of the response (line 51). This is different than other operations performed by the bot, which simply return a status (line 58).

  5. Review the MessagingExtensionHelper.cs file, pointing out the code used to respond to messaging extension requests.