Translating Bots for Microsoft Teams

Overview

Bots and applications can communicate with Microsoft Teams customers through the Message.io translation service.

This guide covers the steps required to translate your application using Message.io including: setting up an Office 365 instance, registering a bot on Microsoft's Bot Framework, and configuring your application with Microsoft Teams.

Requirements to follow this guide:

Sections:


Office 365 - Activate Microsoft Teams

  1. Sign up for Office 365 - Developers get a free trial of Office 365 when registering here: dev.office.com/devprogram
  2. Go to “Services & Add-ins” and activate Microsoft Teams: portal.office.com/adminportal/home#/Settings/ServicesAndAddIns
  3. Download the Microsoft Teams app (available for desktop and mobile): teams.microsoft.com/downloads

Complete step by step instructions: msdn.microsoft.com/en-us/Microsoft-teams/setup

Review the latest docs for Microsoft Teams: msdn.microsoft.com/en-us/microsoft-teams/bots

Admin permissions for bots

Bots have to be enabled by the Office 365 tenant administrator(s). To activate, go to Admin > Settings > Services & Add-ins and turn on Microsoft Teams, bots, and side loading of bots:

Message.io - Messaging Endpoint

Before we begin registration on Bot Framework, select your registered app on message.io/mybots and select Microsoft Teams under Live platforms. If you're continuing from the registration process, you'll see the following screen:

Select Teams

On the next screen, copy the Messaging Endpoint URL in step 2 and head over to dev.botframework.com. Keep this page open as we'll be returning here shortly to fill out information from Bot Framework.

messaging-endpoint-url

Bot Framework - Bot Registration

After you've set up Office 365 and enabled Microsoft Teams, sign in to dev.botframework.com with your Office 365 account to begin registering a new bot.

Go to https://dev.botframework.com/bots and follow the instructions to register a new bot.

On the new bot page - dev.botframework.com/bots/new - you'll need to fill out the following details:

Bot profile

Bot Framework Bot profile

Bot Profile: Microsoft Bot Directory related information

  • Name: This is the name as displayed in the Microsoft Bot Directory (35 character limit)
  • Bot handle: The url version of your bot's name (must be unique and alpha numeric with underscores allowed)
  • Description: The description displayed in the Microsoft Bot Directory and on Bot detail pages

Configuration

Bot Framework Configuration

Messaging endpoint: Paste the messaging endpoint URL from Message.io here

App ID & Password: Select Create Microsoft App ID and password to generate a Microsoft App ID and Password. Make sure to save these values to complete the Microsoft Teams configuration on Message.io in the next section.

Generate Microsoft App ID and Password

Be sure to copy the password as it will not be displayed again. You can, however, generate a new password if needed as long as its replaced on all platforms requiring it.

Generated Password

Select Finish and go back to Bot Framework to return to the Bot Registration page. You should now see the app ID populated under Configuration.

Accept the terms and click Register to complete registration. On completion, you will be redirected to your bot's detail page: (example URL: https://dev.botframework.com/bots?id=<bot_handle_here>)

Bot Details Page

Let's return to Message.io and fill in the App ID and Password to make the app translation live.

Message.io - App ID and Password

Return to your Message.io Microsoft Teams configuration and paste the Microsoft App ID and password from Bot Framework):

App ID and Password

Click Save and Continue to complete setup on Message.io! Now we can return to Bot Framework and enable the bot on Microsoft Teams.

Bot Framework - Enable on Microsoft Teams

On your bot's details page, scroll down and click on Add for Microsoft Teams under Add another channel:

Add Microsoft Teams

Select I'm done configuring Microsoft Teams >

Enable Bot on Microsoft Teams

When you've successfully completed these steps, you'll be presented with a link you can use for testing your bot in Microsoft Teams:

Add to teams

Click the Add to Teams button to launch the Teams app and try out your bot in a one on one conversation!

Alternatively, select Chat in the sidebar in Teams, select New Chat (to the right of search), and paste in your bot's Microsoft App ID in the To: field.

Adding a Bot to a team

What if I need to test my bot in a team with other users?

Within Microsoft Teams, there are individual teams which enables group conversations around a particular topic (a team can have multiple channels). To add a bot to a team, we'll need to:

  • create a simple manifest describing our bot
  • sideload the manifest to a team

Bot manifest

The json manifest we need to create contains some basic information about the bot and details about you, the developer. Here's what a sample manifest looks like:

{
  "$schema": "https://statics.teams.microsoft.com/sdk/v0.4/manifest/MicrosoftTeams.schema.json",
  "manifestVersion": "0.4",
  "id": "%BOT-FRAMEWORK-APP-ID-HERE%",
  "version": "1.0",
  "developer": {
    "name": "%NAME-OF-BOT%",
    "websiteUrl": "https://website.com/teams",
    "privacyUrl": "https://website.com/privacy",
    "termsOfUseUrl": "https://website.com/app-tos"
  },
  "bots": [
    {
      "mri": "%BOT-FRAMEWORK-APP-ID-HERE%"
    }
  ],
  "needsIdentity": true
}

During your deployment to Teams within Message.io, you'll be asked to fill out some information regarding your company, your website, what your bot does and what your bot does. This will be used to populate the manifest file as outlined above. Using the details you originally entered for your master bot, we also populate the commands that your bot will use (and show up when a user talks to your bot in Teams).

After you fill this information out, you'll be presented with a manifest.zip file to download in Message.io Then, you'll be able to sideload your bot and try it out for the first time.

Sideload the bot manifest

With that in hand, go to Teams and select the team you want to sideload the bot to. Select the options button (•••) and click on View team.

Sideload bot tab in Teams

From here you should see a tab for Bots.

If you don't see this tab, make sure sideloading of bots is enabled as described in Admin permissions for bots.

Select bot to sideload in Teams

In the bottom right corner, click on Sideload a bot or tab and select the .zip file containing the manifest.json file you created. Once it's successfully added, you see it listed on this tab (along with any other bots you want to add).

successfully sideloaded bot in Teams

Return to any channel within the Team and try @mentioning your bot to see if it responds!

Removing a bot from a team

Bots can be easily removed from a team by simply selecting the options button(•••) and clicking on View team and then the Bots tab. Click the trash can icon to remove the bot from the team.

sideloaded bots tab

Bots can be re-added to a team at any time. Installation events for new conversations will be re-sent to developers any time a bot is added to a conversation. This is useful for testing bots during development.

Understanding Authentication

For Microsoft Teams, the permissions model is different than platforms such as Slack or Hipchat - bots and notification apps are simply added from the directory instead of requiring an OAuth flow.

For developers, when Microsoft Teams users add a bot to a conversation, Message.io initiates a process for obtaining the ID and Token to your Authorization redirect URL. With this Token you will be able to make response/requests as expected.

Events and Receiving Tokens from Message.io

When a Bot is added to a Channel or Direct Message, this new conversation triggers an event notification which Message.io is able to initiate a flow which resembles OAuth style token generations.

The steps for adding a OAuth powered bot to Microsoft Teams:

  1. Bot is added to a channel or direct message
  2. Message.io sends an temporary authorization code to the specific OAuth URL endpoint
  3. The developer sends the code back to Message.io: https://%platform-name-here%-api.message.io/api/oauth.access?code=%temp-code% which returns both the auth token and the channel ID.
  4. Developers are now able to post and receive messages with Microsoft Teams.

While the Authentication process is different between platforms, Message.io brokers the relationship and handles these details. In the end, the developer gets the same authentication token expected in the platform the app was originally built for.

results matching ""

    No results matching ""