Microsoft Teams apps are web applications that can be hosted on an organization's web server or in the cloud. These apps can consists of tab pages, bots, connectors and rich cards delivered via messaging extensions. The definition of the app is contained in an application package that is uploaded to Teams and installed in channels. The most significant part of the application package is the manifest.json file which conforms to the Teams App schema and contains metadata which allows Teams to correctly present the app to users. In this walkthrough we’ll use The Teams App Studio to create the application package and upload it to Teams which can then be installed in a channel.
1. Enable external apps in Teams
Before deploying custom apps, the Teams administrator must first enable Teams to allow side loading of external apps. This is a tenant wide setting as shown below:
2. Host the app
For the Teams platform to load our app, our app must be reachable from the internet. To make our app reachable from the internet, we need to host our app. We can either host it in Microsoft Azure for free or create a tunnel to the local process on our development machine using
ngrok. When we finish hosting our app make a note of its root URL. It will look something like:
For quick testing we can run the app on our local machine and create a tunnel to it through a web endpoint. ngrok is a free tool that let us do just that. With ngrok we can get a web address such as https://d0ac14a5.ngrok.io (this URL is just an example). We can download and install ngrok for our environment. Make sure we add it to a location in our PATH.
Once we install it, we can open a new terminal window and run the following command to create a tunnel. The sample uses port 3333, so be sure to specify it here. Copy “ngrok http 3333 -host header= localhost:3333” in git bash.
Ngrok will listen to requests from the internet and will route them to your app running on port 3333. We can verify by opening our browser and going to https://d0ac14a5.ngrok.io/hello to load our app's hello page. Please be sure to use the forwarding address displayed by ngrok in our console session instead of this URL.
Tip: It is a good idea to run ngrok in a different terminal window to keep it running without interfering with the app which we might later have to stop, rebuild and rerun. The ngrok session will return useful debugging information in this window.
The app will only be available during the current session on our development machine. If the machine is shut down or goes to sleep the service will no longer be available. Remember this when sharing the app for testing by other users. If we have to restart the service it will return a new address and we will have to update every place that uses that address. The paid version of Ngrok does not have this limitation.
Another option is to use Azure but we'll need an Azure subscription with credits to host the app.
3. Create Application Package
To create the application package, we first install Teams App Studio (Preview) which is a Teams app that can be downloaded and installed directly from the Teams Store. Once installed, we open the Manifest Editor tab which allows us to create a new app as shown below:
On the App details section we can generate a unique app ID using the button as shown below. The remaining fields are just informational and those with * are required entries:
The next section is where we define the apps capabilities. Note that there are four types of capabilities Tabs, Bots, Connectors and Messaging Extensions (for Rich Cards) as mentioned earlier.
The Team tab is where our configuration page goes. Click on the ... symbol at the end of the entry and choose Edit from the drop-down. Change the URL to https://yourteamsapp.ngrok.io/configure where yourteamsapp.ngrok.io should be replaced by the URL that we used above when hosting our app.
If we used Azure for hosting the app then In the Team tab we simply enter the URL of the app that has been uploaded to Azure and click "Save".
Finally, we export the app package as a zip file using the 'Distribute->Test and submit' function of Teams App Studio. This will allow us to save the package as a zip file.
4. Deploy the App
Now that we have the zip file, we simply go the Teams App store and click on the "Upload a custom App" link and choose the zip file that we exported earlier:
This then allows us to specify which team to deploy the app and it will then be available to all users in the team:
So we have successfully uploaded the custom app to the Teams. As can be seen, deploying custom apps in Teams is really not difficult but of course, we did not cover the actual development of the app itself as we are simply using a sample app that doesn't really do much. Below is what the app looks like if everything went well: