Microsoft Teams

What is Microsoft Teams#

Microsoft Teams is a communication and collaboration platform that combines workplace chat, video meetings, file storage, and application integration.

This integration will let you connect your yellow messenger bot with Microsoft Team Channel. Using Azure bot service you can create bot and connect with different channels including MS Team. The message that users send can be received at YM configured endpoint and YM bot would be able to reply to the conversation on both Personal chat or channels on MS Team.

How does an MS Teams app integrate with YM?

Getting Started#

Creating a new Teams App#

For Integrating Yellow Messenger MS Team channel, you will need to create a new azure bot service for which you will receive Client ID, Client Secret.

Note: You can not perform these actions if you don't have access to YM azure portal. Please reach out to Syed Parvez or Rashid Khan to create a bot service for you. You can also do it using a trial azure account with your email ID if you’re just trying things out.

Steps to create a bot service :

Step 1: Goto https://portal.azure.com/ then Search for Bot Services and click on Add Button.

Azure Home > Bot Services

Step 2: Select the Bot Channel Registration and Click on the Create button.

Bot Services > Create

Step 3: Fill the form according to the below image.

Bot Handle: Set a unique bot identifier Subscription: Create new if haven’t created earlier. Resource Group: Create new if haven’t created earlier. Messaging endpoint: https://app.yellowmessenger.com/integrations/botframework/[botID] Microsoft App ID and Password: Auto create.

Step 4: After successfully deployment of Bot Service, Go to Azure Home > App Registrations and select your created App.

Save the Application/Client ID and tenant ID for future use and go to Certificates & Secrets

Step 5: Click on the New client secret > Fill the description & select expires to Never, After clicking on Add button a Client Secret will be generated, save the value of the Client Secret for future use.

Adding Redirect URL Goto Authentication > Add a platform > Web > Add the redirect url > Save Redirect-Url: https://app.yellowmessenger.com/integrations/azureauth/

Add / Remove permission and Grant Admin consent for the App Goto API Permissions > Add the required permissions

Step 6: Now go back to Bot Services and select your Bot service from the list and click on the Channels option.

Add the MS Team channel using Add a featured channel, then click on the Microsoft Teams (with Running health) and open it using Web or Window App.

You will find your bot added in the MS Team chat and can start interacting after the next step.

Connect your Teams app with YM bot#

Go to yellow messenger MS Team channel and fill those Client ID and Client Secret, now you are ready to use MS team with Yellow Messenger bot. Test by sending a message using app.sendTextMessage() .

Create your app manifest using your Azure bot service with Teams App Studio#

Add App Studio from App Store which allows you to create bot manifest, Command Suggestions, Message Extensions, publishing your app etc.

Install App Studio to your MS Team

For creating a new App in App Studio: Click on the Create a new App and fill the app details, enter client ID in App ID field. Connect your app studio bot with azure bot services by configuring Client ID in the Bots Section, For Testing: Install bot using Test & Distribute Section.

Authentication : Active Directory & Graph APIs#

App Registration on Azure AD: Click here. Connecting YM bot to MS Teams : Please follow Section 'Getting Started' from above for Team Integration.

How to set dynamic scopes in Login url:

let consent = "&prompt=consent"
let scopeMp = "People.Read User.ReadBasic.All Presence.Read"
{
"type": "Action.OpenUrl",
"title": "Login",
"url": app.azure.auth() + encodeURIComponent(scopeMp) + consent
}

Add / Remove permission and Grant Admin consent for the App, Goto Azure Portal > App Registration > API Permissions

For enabling multi tenant: Enable multi tenant in the Azure AD integration in Yellow messenger and enable multi tenant on the App registration > Authentication

Graph APIs: Documentation: https://docs.microsoft.com/en-US/graph/api/overview?view=graph-rest-1.0

Explorer: https://developer.microsoft.com/en-us/graph/graph-explorer

Note: For APIs that require Admin consent, Admin can consent for their organisation via Azure Portal or at the time of Login itself.

Adaptive cards in MS Teams#

Adaptive Cards are an open card exchange format enabling developers to exchange UI content in a common and consistent way.

Designer: https://adaptivecards.io/designer/

Documentation: https://docs.microsoft.com/en-us/adaptive-cards/

Designer functionality: https://adaptivecards.io/explorer/AdaptiveCard.html

Sending Adaptive Card using yellow messenger:

let CARD_PAYLOAD_FROM_DESIGNER = {
"type": "AdaptiveCard",
"body": [
{
"type": "TextBlock",
"text": "sOME TEXT"
}
],
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"version": "1.0"
}
let card = {
"contentType": "application/vnd.microsoft.card.adaptive",
"content": CARD_PAYLOAD_FROM_DESIGNER
}
app.sendAdaptiveCard(card).then(() => {
resolve();
})
Sending a Carousel Card:
let card = {
"type": "adaptive",
"content": CARD_PAYLOAD_FROM_DESIGNER
}
let cardCarousal = [card,card,card] //array of cards
app.sendCards(cardCarousal).then(() => {
resolve();
})

Receiving Form Submission data from Adaptive Card in YM bot:

Adaptive Card Example

//Received app.data
app.log(app.data);
---In Log---
{
"message":"form-data",
"value":{
"action":"saveName",
"namearea":"Adam"
}
}

Advanced features#

Command Suggestions

Step 1: Goto App Studio > Select your App > Bots > Setup your bot using Client ID and click on the Add button in the Commands section to add suggestion commands.

Step 2: Fill the new command fields > Click on Save. You would find Bot suggesting you the commands after reinstalling the app.

Message Extensions

Messaging extensions allow users to interact with your web service through buttons and forms in the Microsoft Teams client. They can search, or initiate actions, in an external system from the compose message area, the command box, or directly from a message

Documentation: https://docs.microsoft.com/en-us/microsoftteams/platform/messaging-extensions/what-are-messaging-extensions

Steps to integrate ME with Yellow Messenger:

Step 1: Goto App Studio > Select your App > Messaging extensions > Set up

Step 2: Configure your bot and change messaging endpoint to: https://app.yellowmessenger.com/integrations/sync/microsoft/extensions/[botID]

Step 3: Click on Add Button and choose method according to the requirement then fill out the details and parameters for your message extensions.

Action Type: Allows you to open a pop up and take multiple field values. (e.g: Add Task) Query Type: Allows you to run a query in the search field itself. (e.g: Wikipedia Search)

Receiving responses in yellow messenger:

Query Type:
app.log(app.data)
//In logs----------
{
"commandType": "composeExtension/query",
"value": {
"commandID" : "findwikipedia",
"parameters" : [
{
"name": "searchquery",
"value":"Bumblebee"
}
]
}
}

Note: For initial run or empty query , app.data.value.parameters[0].name = "initialRun"

Action Type Submission:

app.log(app.data)
//In logs----------
{
"commandType": "composeExtension/submitAction",
"value": {
"commandID" : "addtask",
"data" : {
"taskname": "Some Task",
"taskduedate":"2020-09-10"
}
}
}

Responding to the Message Extensions:

let messageExt = {
"composeExtension": {
"type": "result",
"attachmentLayout": "list",
"attachments": [
{
"contentType": "application/vnd.microsoft.card.adaptive",
"content": {
"type": "AdaptiveCard",
"body": [
{
"type": "Container",
"items": [
{
"type": "TextBlock",
"text": "Some Details",
}
]
}
],
"version": "1.0"
},
"preview": {
"contentType": "application/vnd.microsoft.card.thumbnail",
"content": {
"title": "Preview Title",
"text": "Preview Text"
}
}
}
]
}
}
//Send reply directly to message extensions
app.sendAdaptiveCard(messageExt);
//Note: For multiple responses use attachments as an Array.

To run Message extension from Search bar, @mention the bot (example @Bumblebee) and select your bot from suggestion.

Message Extension using Search bar

After clicking on the preview user can view the Adaptive Card attached with the preview.

Message Extension using Search bar

Message Extension using Compose area

Task Module#

Task modules allow you to create modal popup experiences in your Teams application. Inside the popup you can run your own custom HTML/JavaScript code, show an [iframe]-based widget such as a YouTube or Microsoft Stream video or display an Adaptive card.

Documentation: https://docs.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/what-are-task-modules

Create TM using Deeplink:

let adaptiveCard = {
"contentType": "application/vnd.microsoft.card.adaptive",
"content": ADAPTIVE_CARD_PAYLOAD
}
let cardLoad = encodeURIComponent(JSON.stringify(adaptiveCard))
let deeplink= `https://teams.microsoft.com/l/task/<App ID from App Studio>?card=${cardLoad}&height=300&width=600&title=Some Title&completionBotId=<Client ID>`;
app.sendQuickReplies({
title: 'Task Module Check',
options: [{
title: 'Open',
url: deeplink
}]
})

Group Conversation: (Teams / Channel)

The bot must be @mentioned. Your bot will not receive a message when the team or channel is mentioned, or when someone replies to a message from your bot without @mentioning it.

Documentation: https://docs.microsoft.com/en-us/microsoftteams/platform/bots/how-to/conversations/channel-and-group-conversations?tabs=json

Adding a bot in a team or channel: Goto channel and click on the + button with the tabs

For published bot: you can add using the search. For development bot:

  1. Goto App studio and download the bot that you want to add in the teams.
  2. Click on the Manage apps and then Upload a custom app from the bottom-right.
  3. Upload the downloaded .zip of the app.

More References

  1. Try to learn as much about Teams apps as you can. Try to install different apps and observe the workflow and user experience.
  2. Learn basics of MS Teams
    1. Getting started with Teams
    2. Guidebook
    3. Tutorial, examples of use cases (retail, cpg, fmcg, sales, etc)
    4. More links
  3. MS Teams UI elements
    1. Learn about bots, tabs, message extensions
    2. Learn about adaptive cards
  4. Additional
    1. App templates
    2. Webhook for Graph API
    3. MS Graph Web Toolkit
    4. REST API integration with BotFramework
  5. Learn about Active Directory authentication
    1. Auth flow
    2. Auth in Teams tabs