Manifest and SDK Initialization Cheat Sheet
Every Teams app centers on manifest.json, which declares the manifestVersion (matched to a specific TeamsJS SDK compatibility range), the app's id (a GUID matching the Azure AD app registration), staticTabs or configurableTabs for tab surfaces, a bots array for conversational surfaces, and validDomains for every domain the app loads content from. Every tab must call app.initialize() from the TeamsJS SDK before calling any other TeamsJS API — skipping this is the single most common cause of a tab throwing 'This method must be called after initialization' errors during early development.
Cricket analogy: It's like a player checking in with the team management and getting kitted out before stepping onto the field — app.initialize() is that mandatory check-in, and skipping it is like trying to bat without ever being added to the playing XI.
Common TeamsJS SDK Calls
app.getContext() returns the current user, tenant, team, and channel context (useful for scoping data queries to the current team without an extra Graph call), authentication.getAuthToken() retrieves the SSO token for exchange via OBO, dialog.open() launches a modal task module for focused workflows like a form, and pages.navigateToApp() deep-links to another tab within the same app or a different installed app without leaving the Teams client. Always guard capability-specific calls (like dialog.open) with the matching isSupported() check, since mobile and Outlook hosts don't implement every capability desktop and web support.
Cricket analogy: It's like checking the scoreboard (app.getContext()) before deciding your next tactic instead of guessing the match situation — each TeamsJS call gives you a specific, targeted piece of information rather than a vague overview.
Bot and Adaptive Card Snippets
A basic bot extends TeamsActivityHandler and overrides onMessage to respond to incoming text, or onTeamsMessagingExtensionQuery to respond to message extension search queries; Adaptive Cards (currently schema version 1.5 in Teams) use an Action.Submit action type to send form data back to the bot as an invoke activity rather than a plain message. Always validate a card's JSON against the Adaptive Card schema before shipping — a malformed card silently fails to render in some Teams clients rather than throwing a visible error, which makes it a frustrating bug to chase without validation.
Cricket analogy: It's like a fielding drill where a wrongly positioned fielder doesn't get flagged during practice but costs a boundary in the real match — a malformed Adaptive Card doesn't error during dev but silently fails to render for real users.
Common Microsoft Graph Endpoints
Frequently used Graph endpoints in Teams apps include GET /me/joinedTeams (teams the signed-in user belongs to), GET /teams/{team-id}/channels (channels within a team), GET /chats (one-on-one and group chats), and POST /teams/{team-id}/channels/{channel-id}/messages to post a channel message programmatically with appropriate permissions. Remember that most of these calls require delegated permissions consented by the signed-in user (via the OBO flow) rather than application permissions, unless the scenario specifically calls for a background service acting without a signed-in user.
Cricket analogy: It's like checking the exact fixture list for a specific team (GET /teams/{id}/channels) rather than pulling every match in the tournament — Graph endpoints are scoped and specific, not broad dumps.
import { app, authentication } from '@microsoft/teams-js';
async function initTab() {
await app.initialize(); // must complete before any other TeamsJS call
const context = await app.getContext();
console.log('Tenant:', context.user?.tenant?.id, 'Team:', context.team?.internalId);
const ssoToken = await authentication.getAuthToken();
// send ssoToken to backend for OBO exchange against Microsoft Graph
}
initTab();manifestVersion in manifest.json and the TeamsJS SDK version your app imports must be compatible — check the official manifest schema version compatibility table before upgrading either one independently.
Microsoft Graph enforces per-app and per-tenant throttling; a 429 response includes a Retry-After header in seconds — always honor it with backoff rather than retrying immediately, or the throttle window can extend further.
- manifest.json declares manifestVersion, app id, tab/bot/extension surfaces, and validDomains.
- app.initialize() must be called before any other TeamsJS SDK function.
- app.getContext(), authentication.getAuthToken(), dialog.open(), and pages.navigateToApp() are the most-used TeamsJS calls.
- Adaptive Cards use Action.Submit to send form data back as an invoke activity, not a plain message.
- Malformed Adaptive Cards can silently fail to render instead of throwing a visible error — always validate against the schema.
- Common Graph endpoints include /me/joinedTeams, /teams/{id}/channels, and /chats, mostly under delegated permissions.
- Honor the Retry-After header on Graph 429 responses instead of retrying immediately.
Practice what you learned
1. What TeamsJS call must be made before any other TeamsJS API function?
2. Which TeamsJS API retrieves the current user, tenant, team, and channel context?
3. What Adaptive Card action type sends form data back to a bot as an invoke activity?
4. What is a risk of shipping a malformed Adaptive Card without schema validation?
5. What should an app do when Microsoft Graph returns a 429 response?
Was this page helpful?
You May Also Like
Teams App Best Practices
Practical guidelines for building performant, secure, and visually consistent Microsoft Teams applications that hold up in production.
Publishing to the Teams Store
How to prepare, validate, and submit a Microsoft Teams app for Teams Store publication through Partner Center.
Testing and Debugging Teams Apps
Practical techniques for local debugging, testing SSO and bots, and diagnosing issues in production Teams apps.
Microsoft Teams Interview Questions
Common technical interview questions and strong-answer strategies for Microsoft Teams app development roles.
Related Reading
Related Study Notes in Microsoft Technologies
Browse all study notesWindows 10 / UWP Development Study Notes
.NET · 30 topics
Microsoft TechnologiesWindows Batch Scripting Study Notes
Batch · 30 topics
Microsoft TechnologiesMFC (Microsoft Foundation Classes) Study Notes
C++ · 30 topics
Microsoft TechnologiesSilverlight Study Notes
.NET · 30 topics
Microsoft TechnologiesXAML Study Notes
.NET · 30 topics
Microsoft TechnologiesWPF (Windows Presentation Foundation) Study Notes
.NET · 30 topics