Getting Started with Microsoft Teams Tabs - Part 1

Microsoft Teams is a chat-based collaboration tool that is part of the Office 365 suite of services. Teams enables local and co-workers to work together and collaborate through a common work-space, using features such as team chat, one-on-one chat and document collaboration.

Teams has a few different methods that allow developers to extend it's functionality, like bots, webhooks, and tabs.  This series will focus on the tabs aspect, as I have previously blogged about the other 2.  So what are tabs?

Tabs are a way to add additional relevant content to to teams channel.  They can be added in 2 different scopes, personal or team.  It should be fairly obvious what this means, personal are visible to your user, team visible to all users in the team.  In my opinion there are 2 different types of tabs, tabs that display a static website, and tabs that use the information passed from teams, and display dynamic content.  We'll focus on the 2nd type in this series, as I deem that to be the more useful, otherwise you essentially only using the capability of a web browser.

So how do develop a tab?

There are 2 components to a tab.

1.  The manifest

2.  The web content

If you are familiar at all with Outlook or other Office add-ins the manifest concept is going to be already familiar.  The manifest and logo files, combined into a zip file, make up the entire installation.  Also like Office add-ins installation can go through the Microsoft Published Store method, or you can side load the installation if you wish to keep it inside your company.

The Teams manifest is a json file instead of an xml file like the Outlook ones, so that is one minor difference, but in my opinion it's a step in the right direction.  The manifest file also has versioning, like the Outlook ones.  Current version 1.0 and 1.1 seems to be the options.  

If you would like to look at the template you can find it here, please not this shows all the available settings, and you will most likely only need a few pieces in order to get up and running.

Sample manifest

So before you try to create a manifest you need to go and register your tab to get a Guid ID and a package name.  But Doug, why can't I just make this info on my own?  You can, but if you setup a connector at the same time, your tab / app at a later point can post messages into the channel as well.

So just navigate here and do the setup, it'll generate you a package, sample manifest and do a lot of the work for you.

https://outlook.office.com/connectors/publish

Here you can see the one I have created that is shown the first screen shot.

The easy place to get your starter manifest is here, inside the connector you select or create.

Make sure you select the options like about so your future messages can be delivered to the team of your choice.

Ok now that have a manifest let's look at some of the components.

{ "$schema": "https://statics.teams.microsoft.com/sdk/v1.0/manifest/MicrosoftTeams.schema.json", "manifestVersion": "1.0", "version": "1.0.0", "id": "%MICROSOFT-APP-ID%", "packageName": "com.example.myapp", "developer": { "name": "Publisher Name", "websiteUrl": "https://website.com/", "privacyUrl": "https://website.com/privacy", "termsOfUseUrl": "https://website.com/app-tos" }, "name": { "short": "Name of your app - 30 characters", "full": "Full name of app, if greater than 30" }, "description": { "short": "Short description of your app", "full": "Full description of your app" }, "icons": { "outline": "%FILENAME-20x20px%", "color": "%FILENAME-96x96px" }, "accentColor": "%HEX-COLOR%", "configurableTabs": [ { "configurationUrl": "https://taburl.com/config.html", "canUpdateConfiguration": true, "scopes": [ "team" ] } ], "staticTabs": [ { "entityId": "idForPage", "name": "Display name of tab", "contentUrl": "https://teams-specific-webview.website.com", "websiteUrl": "http://fullwebsite.website.com", "scopes": [ "personal" ] } ], "bots": [ { "botId": "%MICROSOFT-APP-ID-REGISTERED-WITH-BOT-FRAMEWORK%", "needsChannelSelector": "true", "isNotificationOnly": "false", "scopes": [ "team", "personal" ], "commandLists": [ { "scopes": ["team"], "commands": [ { "title": "Command 1", "description": "Description of Command 1" }, { "title": "Command N", "description": "Description of Command N" } ] }, { "scopes": ["personal"], "commands": [ { "title": "Personal command 1", "description": "Description of Personal command 1" }, { "title": "Personal command N", "description": "Description of Personal command N" } ] } ] } ], "connectors": [ { "connectorId": "GUID-FROM-CONNECTOR-DEV-PORTAL%", "scopes": [ "team"] } ], "composeExtensions": [ { "botId": "%MICROSOFT-APP-ID-REGISTERED-WITH-BOT-FRAMEWORK%", "scopes": ["team", "personal"], "commands": [ { "id": "exampleCmd", "title": "Example Command", "description": "Comamand Description e.g. Search on the web", "initialRun": "true", "parameters": [ { "name": "keyword", "title": "Search keywords", "description": "Enter the keywords to search for" } ] } ] } ], "permissions": [ "identity", "messageTeamMembers" ], "validDomains": [ "*.taburl.com", "*.otherdomains.com" ] }

So let's start and break down each component.  Why do I need to specify a schema?  Well if you do, you will get intellisense in visual studio which can help you greatly when building the file.

Version - Just make it 1.0 to be safe.

Id - This is the guid we got from the registration portal

packageName - Also filled out from the registration portal

developer - This is just information about your orginization

nane - The short and long name of your app.  30 and 100 character limits respectively.

description - The short and long description of your app.  80 and 4000 character limits respectively.

Icons - These need to be 20x20 and 96x96 respectively.  The labels are a bit confusing, I would says 99% of the time you are going to make these the same icon, a png with a transparent background.

accentColor - This is a color in hex like you would use in a website #FF0000 (red) for example

Those are the settings that are required, the rest are optional, and will determine what type of app we are registering with teams.  In our case we want a tab, so are going to fill out the staticTabs and configurableTabs sections.

The static will hold the location and description of the content page we want to be displayed when a user clicks on our tab.  Again here, I have made the 2 urls point to same location, filled out the name value with what the label of the tab should be, and made up a unique entityId.  Here I set my scopes to team so all users in the team will have access to the tab.

The configurableTabs settings will determine what is show when you install the tab app.  So if you were say using a maps in your tab, you could allow your users to select say Google or Bing for an option before install.  Teams gives your configuration page a way to save and read these settings for your content page, a top we'll cover in more detail next week.

The last thing I fill out, even those it is option is the validDomains section.  This is a list of valid domains from which your extension will load content, and wildcards are permitted.

Ok that will end the overview of the manifest discussion for today.  Next week we'll look at building some of our web content, specifically the configuration page.

Doug Routledge, C# Lync, Skype for Business, SQL, Exchange, UC, Full Stack Developer  BridgeOC Bridge Operator Console Twitter - @droutledge @ndbridge