The developer’s guide

to building Microsoft
Teams apps
 App development 2
with Microsoft Teams

CONTENTS

01 / . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 05 / . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
The Microsoft Teams Bring Teams into your app
developer journey
06 / . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
02 / . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Publish and certify your app
Why Teams?
Build collaborative apps 07 / . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Bring app solutions to life Microsoft 365 Developer Program

03 / . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 08 / . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Getting started with Teams apps Next steps

04 / . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
App development experience
Teams development tools and SDKs
Teams Toolkit
Yeoman Generator
SDKs for building Teams apps
Developer Portal for Teams
 App development 3
with Microsoft Teams

01
The Microsoft Teams With app development in Teams, you own the
technology stack and the entire user experience.

developer journey The full stack of Microsoft technologies means

you can build and distribute collaborative apps in
ways that make sense to you—just choose the right
Teams capabilities combination of your preferred tools, programming
languages, and SDKs to target specific business needs:
Collaborative apps represent a paradigm shift away from
an application-centric work model to one centered on the
Extend app functionality by adding
team. People don’t go to apps—apps come to people.
more Teams capabilities and using
Collaborative apps meet users how, where, and when they Microsoft Graph to connect the data
need and want to work, and bring insights, appropriate and insights from Microsoft 365.
business workflows, and accurate data into the right user
and team interactions. This facilitates seamless access to
and navigation between workflows and business data Take advantage of an integrated
without interruption. developer environment and the
DevOps benefits of GitHub, Microsoft
Visual Studio, and Visual Studio Code
With engaging, collaborative apps in Teams, your
with Microsoft 365 and Azure.
organization can modernize communications and
delight users at the same time. Everyone—from decision
makers to developers—can experience unique and Use the robust Developer Portal
compelling benefits using Teams, including improved to manage, configure, deploy, and
productivity, greater user satisfaction, and powerful distribute your apps.
development features. Teams offers an unmatched
opportunity for developers to effectively plan, design,
Monetize your apps with options
build, and distribute collaborative apps using a flexible
like SaaS offers, in-app purchases,
development environment and a rich set of features, and more.
frameworks, tools, and SDKs. Offering diverse capabilities
and entry points, Teams enables developers to create
functionality that encourages deeper engagement, such
This e-book takes a closer look at how you
as allowing users to explore an app from a specific tab.
can extend Teams to help users collaborate
and employ the tooling that Microsoft offers
to make building apps easier. It covers the
key capabilities developers need to build rich
collaborative experiences that help users
thrive in the flow of work.
 App development 4
with Microsoft Teams

02
Why Teams?
Dedicated to supporting where, when, and how colleagues and peers are using. Likewise, with
people want to work, Teams is the collaboration Teams, you can certify your app through the
platform of choice across industries, borders, and Microsoft 365 App Compliance program, which
organizations of every size and shape. With focuses on security, privacy, and data-handling
Teams apps, you can bring business workflows standards. To monetize your app, include it as a SaaS
and insights to users where they work, helping offering on the Microsoft Commercial Marketplace,
them collaborate, drive better and faster or add an in-app purchasing option that includes a
decisions, and accelerate business outcomes. paywall experience directly from within the app.

Build collaborative apps

Collaborative apps—an app pattern designed
A collaborative app example:
to bring people, processes, and data together to
MURAL for Teams
help users thrive in the hybrid workplace—are
transforming how people in every organization MURAL for Teams extends the Teams app’s personal
work together. With more than 270 million active tabs and search-based message extensions to other
users, Teams offers developers an unmatched Microsoft-hosted apps. For example, it enables you to
opportunity to build collaborative apps. You can deliver a connected experience across Teams, Outlook,
and Office. With a search-based message extension, you
create collaborative experiences with low-code tools
can insert a MURAL directly into an Outlook message
like Power Platform and professional code options as an interactive Adaptive Card.
like Visual Studio and Visual Studio Code. You can
build your app once and deploy it anywhere, helping MURAL for Teams is the first app in the Visual
to ensure maximum adoption and user reach. Apps Collaboration category to achieve Microsoft 365
built for Teams work across all desktops and mobile, certification, which validates that the app offers:
and app permission policies can be created and
assigned through the Teams admin center. Increased confidence that
member data is protected
Teams promotes stronger app discoverability and
product awareness by allowing you to push, list, Trusted, strong security
and distribute your app on the Teams store. The that reduces customer risk
Teams store helps people find your apps through
Reduced time spent investigating
updated app categories, curated app collections,
security and compliance
and intelligent recommendations based on what
 App development 5
with Microsoft Teams

Bring app solutions to life

Teams apps serve as a bridge between the Teams client (web, mobile, or desktop) and APIs, folding these
directly into the context of Teams. You can bring your solutions to life through Teams capabilities like tabs,
bots, Adaptive Cards, messaging extensions, webhooks, and task modules. These capabilities, in turn, can be
powered by Microsoft Azure, Microsoft Graph, SharePoint Framework, or Power Platform. The Teams SDK also
enables you to build apps for Teams, Outlook, and Office using a single application and deployment model.
Your collaborative apps build on top of the world-class security, governance, and compliance of the Microsoft
365 platform, making it easier for you to build apps that are both secure to use and compliant.

03
Getting started Note that the Teams client provides the extension
point that people use to interact with your app, while
with Teams apps you host the APIs and logic that power your app.¹ A
Teams app package containing icons and a manifest
JSON file is installed in Teams. The manifest file
Teams apps consist of cloud services that integrate includes details about:
with Teams extension points (also known as features)
and a manifest that registers these services with • App metadata (like the app name)
the Teams platform. Teams core features and
• Teams extensibility points that the app
functionalities that you can build in your app are uses (like tabs, bots, or messaging extensions)
called Teams extension points because they enable
integration and interaction. Creating apps with • Pointers to the APIs that power the
Teams involves deciding what to build (based on app (like the ID or tab URL)
Teams extension points and user engagement),
building the APIs, creating a Teams app package,
and distributing the package to target users.

¹The Teams platform is not a hosting service; the APIs powering your app must be hosted by you and accessible by HTTPS over the internet.
 App development 6
with Microsoft Teams

Before building your Teams app, it’s important to understand the different extensibility points
available across the Teams UI, including tabs, bots, and messaging extensions. By extending Teams
capabilities, you tap into the power of contextual relevance, making the user experience clearer, fuller,
and more effective. For example, you can build your services with context-specific information like
messages your app was triggered from or information related to the channel your app is installed in.

Tabs display web-based content in a central location

where people can discuss and work on it together. Meeting extensions deliver a specific user experience
You can add tabs as part of a channel inside a team, for each stage of the meeting life cycle, including
group chat, or personal app for an individual user. pre-meeting, in-meeting, and post-meeting. Example
An example use case would be exposing your existing use cases include preparing the meeting agenda
web application inside Teams. before a meeting, using the agenda to support the
conversation and take notes and actions during a
meeting, and sharing the outcomes with participants
after a meeting.

Bots in Teams can range from simple notifications

to conversational bots with AI-powered language
understanding. Examples include a customer service
bot or a weather forecasting bot. Adaptive Cards are actionable snippets of content
that can be added to a conversation through a bot
or messaging extension. They simplify the sharing of
structured data in conversations in a consistent way
across all devices and applications. An example use
case is gathering information through input forms.
Messaging extensions enable users to search and share
external information in conversation, such as sending
a card or creating a help ticket based on the content of
a channel post. For example, users can look up order or
customer information in an external system and share
it in a conversation without leaving Teams. Microsoft Graph API provides access to data and
insights stored in Microsoft 365 as well as information
about teams, channels, users, and messages. Example
use cases include showing upcoming meetings
or retrieving information about people in your
organization or the files you’ve been working on.
Webhooks and connectors allow users to subscribe
to a channel for notifications and messages from an
external system, such as your APIs.

Depending on business needs, you might choose a single extension point (like a personal conversation bot)
or combine multiple extension points. For more information, see Microsoft Docs | Teams app features.
 App development 7
with Microsoft Teams

04
App development experience
Because Teams is a collaborative social framework, there are many options available to solve your users’ needs.
Building an app in Teams sets you on the path for successful development, distribution, and future-state goals.
Based on your business requirements and preferred programming language, you can choose from multiple options
for developer tools and SDKs in Teams. Collectively, these choices enable you to design, build, debug, distribute,
and manage Teams apps. For environments, consider the Teams Toolkit, the open-source community tool Yeoman
Generator for Microsoft Teams (Yo Teams), or the Developer Portal. Supported frameworks include Blazor, SharePoint
Framework, and Bot Framework. For building solutions, web frameworks like React, Angular, and VueJS are available.
For programming languages, choose from familiar options like JavaScript, TypeScript, .NET, Java, or Python.

Design Development

Use the Teams UI Kit and UI Library to Use popular IDEs like Visual Studio or
create the right experience and design Visual Studio Code, command-line tools,
a UI that fits diverse user requirements. APIs, and SDKs to integrate apps into
Teams conversations and channels.

Integration with Microsoft 365 Testing, deployment, distribution,

and management
Access data and insights stored in Microsoft 365
using Microsoft Graph, expose Teams apps across Test and debug your app locally or in the cloud.
Microsoft 365 (including Outlook and Office.com), Then, deploy the app to SharePoint or Azure using
and publish to the marketplace. Teams Toolkit or Yo Teams. Finally, configure,
manage, and distribute the app directly to the
store with the Developer Portal.
 App development 8
with Microsoft Teams

Teams development tools and SDKs

The tools and SDKs available for app development in Teams are not alternatives of each other; rather, a
combination of these different tools and SDKs can be used in your solution. Table 1 provides an overview of
the tools and SDKs available, their intended users or purpose, and how they can help with app development.

Tool or SDK Intended users or purpose Benefits for Teams app development

Teams Toolkit for JavaScript and TypeScript Create new projects in Teams, set up apps in the Teams
Visual Studio Code developers Developer Portal, run and debug in Teams, and configure
cloud hosting.
Add other Teams capabilities (such as tabs or bots) and more
Azure resources to your Teams app. Collaborate on Teams
projects and add SSO, CI/CD pipelines, and API connections.

Teams Toolkit for .NET developers Create new projects in Teams, set up apps in the Teams
Visual Studio Developer Portal, run and debug in Teams, and configure
cloud hosting.

Yo Teams CLI tool for developers who are Create and scaffold projects that include one or more Teams
familiar with Yeoman and Gulp features such as bots, messaging extensions, tabs, and more.

TeamsFx CLI tool for JavaScript, CLI offers the keyboard-centric equivalent of the Teams
TypeScript, and .NET developers; Toolkit functionality, including deployment from CI/CD
includes SDK pipelines. SDK offers simplified authentication to APIs
secured with the Microsoft identity platform, such as
Microsoft Graph and custom APIs.

Bot Framework Build conversational Teams Bot SDK offers a rich bot SDK to create Teams
bots with C#, Java, Python, and bots and message extensions.
JavaScript

Teams JS SDK Integrate apps with Teams client When you expose your web application in Teams as a tab,
capabilities make it Teams-aware and build task modules that integrate
with your application.

Microsoft Graph SDK Connect data and insights from Simplify building high-quality, efficient, and resilient apps
Microsoft 365 that access Microsoft Graph.

SharePoint Build Microsoft 365–hosted Host tabs and task modules on Microsoft 365 without
Framework solutions with single sign- additional services on Azure. Easily access resources secured
on (SSO) using TypeScript or with the Microsoft identity platform, like Microsoft Graph or
JavaScript custom APIs.

Adaptive Cards SDK Build declarative UI elements Extend bots and messaging extensions with a rich and
with JSON, which transforms interactive UI that works on any platform.
into a native Teams UI on web,
desktop, and mobile versions

Fluent UI SDK Implement web UI that is Use web components that implement Microsoft Design
consistent with Teams; supports Language and seamlessly integrate with Teams UI, such as
React buttons, dropdowns, grids, people and date pickers, and
more.

Table 1: Teams tools and SDKs and their uses

 App development 9
with Microsoft Teams

Teams Toolkit Yeoman Generator

The Teams Toolkit guides you through the process of The Yeoman Generator for Microsoft Teams (also
creating your app, providing everything you need to known as Yo Teams) scaffolds a project once the
quickly build, debug, and launch. It allows you to integrate developer has answered a few questions about
your application with all extensibility points in Microsoft the Teams app they’re building. It consists of the
Teams. It also offers templates for common scenarios that Yeoman Generator for Teams Apps (generator-
you can use as a starting point, such as bot notifications, teams) and the package of Gulp tasks (yoteams-
command bots, or apps that are available in Teams, build-core and yoteams-deploy). It offers additional
Outlook, and Office.com. features such as simple deployment, a unit testing
framework, sample unit tests, and more. Visit the
The Teams Toolkit enables you to create and deploy Microsoft Teams App Project Generator – #YoTeams
Teams apps with integrated identity, access to cloud GitHub page to learn more.
storage, data from Microsoft Graph, and other services
in Azure and Microsoft 365. It offers full-stack debugging,
hot reload, secure tunneling, integrated support for
hosting, support for serverless functions, and CI/CD
actions for GitHub and Azure DevOps. It also provides
integrations with the various tools, programming
languages, and frameworks developers use most often,
including first-class support for React, SharePoint
Framework, and ASP.NET Core Blazor. The Teams Toolkit
can also be used to debug and deploy front-end web
apps from other frameworks such as Angular.

The Teams Toolkit allows you to build Teams apps faster.

If you prefer to use JavaScript or TypeScript, you can use
Teams Toolkit for Visual Studio Code; if you’re a .NET
developer, use Teams Toolkit for Visual Studio; and if you
prefer command-line tooling, use the TeamsFx CLI. TeamsFx
CLI is a feature of TeamsFx that runs tasks with a keyboard-
centric experience while building Teams apps. TeamsFx
includes a library that simplifies connecting to services
secured with the Microsoft identity platform and lets you
build apps with zero configuration.
 App development 10
with Microsoft Teams

SDKs for building Teams apps

There are multiple SDKs available for you to power your Teams app.
You can combine them based on what you need to build.

Teams JavaScript (Teams JS) SDK TeamsFx SDK

The Teams JS SDK allows you to make web apps TeamsFx can help you build apps that use the
Teams-aware. Whether you’re bringing an existing Microsoft Graph API or any API secured with
web app into Teams or building task modules, using the Microsoft identity platform to fetch data
the Teams JS SDK gives you access to the context of like basic user information. Teams Fx handles the
Teams, Outlook, and Office.com. OAuth 2.0 authorization code grant flow, getting
access tokens that can be used to make Microsoft
Bot Framework SDK Graph API calls.
The Bot Framework SDK helps you build
SharePoint Framework
messaging extensions and conversational bots.
It supports the C#, JavaScript, Python, and Build Microsoft 365–hosted apps with
Java programming languages. It also helps you SharePoint Framework using code, Teams tabs,
build conversational experiences with language and task modules. Easily access resources secured
understanding, QnA Maker, and a sophisticated with the Microsoft identity platform, such as
composition of bot replies. Microsoft Graph and custom APIs.

Microsoft Graph SDK Adaptive Cards SDK

Microsoft Graph SDK lets you simplify building Adaptive Cards are actionable snippets of
high-quality, efficient, and resilient apps that content that can be added to conversations
access data and insights from Microsoft 365. through bots or messaging extensions. These
It’s available for the C#, PowerShell, TypeScript, cards provide rich communication to your
JavaScript, Java, Go, PHP, and Python (preview) audience using text, graphics, and buttons.
programming languages.
Fluent UI SDK

Fluent UI implements Microsoft Design

Language, which allows developers to build
apps that seamlessly integrate with Teams.
These components work across different use
cases, Teams themes, and screen sizes.
 App development 11
with Microsoft Teams

Developer Portal for Teams • Microsoft identity platform management to

register apps with Azure Active Directory to
help users sign in and provide access to APIs
The Developer Portal offers a tool for configuring,
distributing, and managing Teams apps. It provides a • Teams store app validation to check the app
dedicated app management console where you can package against the test cases that Microsoft
register, configure, and distribute your app to your uses to review your app
organization or the Teams store. You can also evaluate
• Bot management to add conversational bots to
and debug your app, analyze usage insights, and an app that communicate with users, respond to
access other tools, including: their questions, and proactively notify them about
changes and other events
• Scene studio to help you design custom
Together Mode scenes for Teams meetings

• An Adaptive Cards editor to help you create and

preview Adaptive Cards to include with the build apps
 App development 12
with Microsoft Teams

05
Bring Teams into your app
When building Teams apps, you can expose your app
inside Teams—but you can also bring some Teams
functionality to your app with a rich set of features.
Azure Communication Services, which power Teams,
enable real-time audio and video conferences in your
existing app. Similarly, the Microsoft Graph API brings
Teams (chats and channels) collaboration to your app.
By bringing Teams into your app, you can improve users’
experience by helping them get all the relevant information
they need for their work, enabling them to stay in their
flow and collaborate seamlessly without having to switch
back and forth across apps.

Microsoft Graph exposes REST APIs and client libraries

to access data in Microsoft 365 and Teams. It easily
extends your app with Teams functionality (like video
calling or chat) using the building blocks in Microsoft
365. Plus, Microsoft is introducing new capabilities—like
enabling chats with federated users, identifying which
messages are read and unread by the current user, and
subscribing to user chats and membership changes—with
Microsoft Graph APIs.

Azure Communication Services are cloud-based

services with REST APIs and client library SDKs available
to help developers integrate communication (voice
and video calling, telephony, chat, SMS, and email
notifications) into their apps. Azure Communication
Services’ interoperability with Teams enables you to
develop apps that interact with external customers and
Teams users by streamlining voice, video, telephony,
and chat capabilities. You can also add SMS and email
notification capabilities to extend the value of Teams
to further suit specific needs. Plus, with the sample app
builder, you can easily build and deploy a sample app for
virtual appointments with Azure Communication Services
in just a few minutes—no coding needed.
 App development 13
with Microsoft Teams

06
Publish and
07
Microsoft 365
certify your app Developer Program
To publish your app to the Teams store, you need to review The Microsoft 365 Developer Program offers a free,
the Teams store validation guidelines and submit your app instant sandbox for you to prototype your apps and
for publishing based on these parameters. This validation solutions. The sandbox comes pre-provisioned and
helps users and admins verify the authenticity of your app. configured for development with sample Teams
The Microsoft 365 App Compliance Program is designed to data so you can start quickly, saving time so you can
evaluate, validate, and highlight your app security, privacy, focus on what matters: exploring and learning the
and data trustworthiness based on industry standards, capabilities of the Microsoft 365 platform.
including the Service Organization Control Report (SOC The Teams sample data pack includes:
2) and the Payment Card Industry Data Security Standard
(PCI DSS). With the App Compliance Automation tool, • User, mail, and calendar data with 16 sample users,
plus user data and content, to help you model
developers can automate various tasks to achieve the
your solutions. The data includes user mailboxes,
certification faster and more easily. The tool produces calendar events, and integration into a Teams
reports that developers can share with IT to gain visibility developer environment with simulated chats and
into app security and compliance. team memberships.

• A customized developer environment featuring

pre-configured Teams app sideloading and five
sample teams, channels, tabs, and chat sessions
built around the 16 sample users.

• A developer portal that’s pre-installed and pinned

to offer easy access to configure and manage apps
that developers build.

• The ability to choose from the SharePoint sample

data and six site templates that can be installed
and evaluated for your organization (with one
pre-installed in your instant sandbox).
 App development 14
with Microsoft Teams

08
Next steps
Teams is collaborative by design. It’s uniquely suited to
build and deploy collaborative apps into every corner of
your organization, empowering employees, optimizing
operations, and fully engaging your customers. Do you
have an app idea that can harness the power of Teams
for your organization or your customers? Take advantage
of Teams’ rich and flexible set of extensibility points,
UI constructs, and APIs to build powerful collaborative
apps with your existing development skills and the tools
provided by Microsoft 365 and Azure.

Get started by joining the

Microsoft 365 Developer Program

Learn more with

Teams developer documentation

Download the infographic:

Build collaborative apps with Microsoft Teams

© 2022 Microsoft Corporation. All rights reserved.