Share via

root object

  • Article

Syntax

{
  "$schema": "{string}",
  "manifestVersion": "devPreview | m365DevPreview",
  "version": "{string}",
  "id": "{string}",
  "packageName": "{string}",
  "localizationInfo": {
    "defaultLanguageTag": "{string}",
    "defaultLanguageFile": "{string}",
    "additionalLanguages": [
      {
        additionalLanguages object
      }
    ]
  },
  "developer": {
    "name": "{string}",
    "mpnId": "{string}",
    "websiteUrl": "{string}",
    "privacyUrl": "{string}",
    "termsOfUseUrl": "{string}",
    "contactInfo": {
      contactInfo object
    }
  },
  "name": {
    "short": "{string}",
    "full": "{string}",
    "abbreviated": "{string}"
  },
  "description": {
    "short": "{string}",
    "full": "{string}"
  },
  "icons": {
    "outline": "{string}",
    "color": "{string}",
    "color32x32": "{string}"
  },
  "accentColor": "{string}",
  "configurableTabs": [
    {
      "id": "{string}",
      "configurationUrl": "{string}",
      "canUpdateConfiguration": {boolean},
      "scopes": [
        "team | groupChat"
      ],
      "meetingSurfaces": [
        "sidePanel | stage"
      ],
      "context": [
        "personalTab | channelTab | privateChatTab | meetingChatTab | meetingDetailsTab | meetingSidePanel | meetingStage | callingSidePanel"
      ],
      "supportedPlatform": [
        "desktop | mobile | teamsMeetingDevices"
      ],
      "sharePointPreviewImage": "{string}",
      "supportedSharePointHosts": [
        "sharePointFullPage | sharePointWebPart"
      ]
    }
  ],
  "staticTabs": [
    {
      "entityId": "{string}",
      "name": "{string}",
      "contentUrl": "{string}",
      "contentBotId": "{string}",
      "websiteUrl": "{string}",
      "searchUrl": "{string}",
      "scopes": [
        "team | personal | groupChat"
      ],
      "context": [
        "personalTab | channelTab | privateChatTab | meetingChatTab | meetingDetailsTab | meetingSidePanel | meetingStage | teamLevelApp"
      ],
      "supportedPlatform": [
        "desktop | mobile | teamsMeetingDevices"
      ],
      "requirementSet": {
        elementRequirementSet object
      }
    }
  ],
  "bots": [
    {
      "botId": "{string}",
      "configuration": {
        configuration object
      },
      "needsChannelSelector": {boolean},
      "isNotificationOnly": {boolean},
      "requiresSecurityEnabledGroup": {boolean},
      "supportsFiles": {boolean},
      "supportsCalling": {boolean},
      "supportsVideo": {boolean},
      "scopes": [
        "team | personal | groupChat"
      ],
      "commandLists": [
        {
          commandLists object
        }
      ],
      "requirementSet": {
        elementRequirementSet object
      }
    }
  ],
  "connectors": [
    {
      "connectorId": "{string}",
      "configurationUrl": "{string}",
      "scopes": [
        "team"
      ]
    }
  ],
  "subscriptionOffer": {
    "offerId": "{string}"
  },
  "composeExtensions": [
    {
      "id": "{string}",
      "botId": "{string}",
      "composeExtensionType": "botBased | apiBased",
      "authorization": {
        authorization object
      },
      "apiSpecificationFile": "{string}",
      "canUpdateConfiguration": boolean | null,
      "commands": [
        {
          commands object
        }
      ],
      "messageHandlers": [
        {
          messageHandlers object
        }
      ],
      "requirementSet": {
        elementRequirementSet object
      }
    }
  ],
  "scopeConstraints": {
    "teams": [
      {
        teams object
      }
    ],
    "groupChats": [
      {
        groupChats object
      }
    ]
  },
  "permissions": [
    "identity | messageTeamMembers"
  ],
  "devicePermissions": [
    "geolocation | media | notifications | midi | openExternal"
  ],
  "validDomains": [
    "{string}"
  ],
  "webApplicationInfo": {
    "id": "{string}",
    "resource": "{string}"
  },
  "graphConnector": {
    "notificationUrl": "{string}"
  },
  "showLoadingIndicator": {boolean},
  "isFullScreen": {boolean},
  "activities": {
    "activityTypes": [
      {
        activityTypes object
      }
    ]
  },
  "supportedChannelTypes": [
    "sharedChannels | privateChannels"
  ],
  "configurableProperties": [
    "name | shortDescription | longDescription | smallImageUrl | largeImageUrl | accentColor | developerUrl | privacyUrl | termsOfUseUrl"
  ],
  "defaultBlockUntilAdminAction": {boolean},
  "publisherDocsUrl": "{string}",
  "defaultInstallScope": "personal | team | groupChat | meetings",
  "defaultGroupCapability": {
    "team": "tab | bot | connector",
    "groupchat": "tab | bot | connector",
    "meetings": "tab | bot | connector"
  },
  "meetingExtensionDefinition": {
    "scenes": [
      {
        scenes object
      }
    ],
    "videoFilters": [
      {
        videoFilters object
      }
    ],
    "videoFiltersConfigurationUrl": "{string}",
    "supportsStreaming": {boolean},
    "supportsAnonymousGuestUsers": {boolean}
  },
  "authorization": {
    "permissions": {
      permissions object
    }
  },
  "extensions": [
    {
      "requirements": {
        requirementsExtensionElement object
      },
      "runtimes": [
        {
          extensionRuntimesArray object
        }
      ],
      "ribbons": [
        {
          extensionRibbonsArray object
        }
      ],
      "autoRunEvents": [
        {
          extensionAutoRunEventsArray object
        }
      ],
      "alternates": [
        {
          extensionAlternateVersionsArray object
        }
      ],
      "audienceClaimUrl": "{string}",
      "appDeeplinks": [
        {
          extensionAppDeeplinksArray object
        }
      ],
      "contentRuntimes": [
        {
          extensionContentRuntimeArray object
        }
      ],
      "getStartedMessages": [
        {
          extensionGetStartedMessageArray object
        }
      ],
      "contextMenus": [
        {
          extensionContextMenuArray object
        }
      ]
    }
  ],
  "actions": [
    {
      "id": "{string}",
      "intent": "create | addTo | open | preview | share | sign | custom",
      "displayName": "{string}",
      "description": "{string}",
      "icons": [
        {
          icons object
        }
      ],
      "handlers": [
        {
          handlers object
        }
      ]
    }
  ],
  "dashboardCards": [
    {
      "id": "{string}",
      "displayName": "{string}",
      "description": "{string}",
      "pickerGroupId": "{string}",
      "icon": {
        dashboardCardIcon object
      },
      "contentSource": {
        dashboardCardContentSource object
      },
      "defaultSize": "medium | large"
    }
  ],
  "intuneInfo": {
    "supportedMobileAppManagementVersion": "{string}"
  },
  "copilotAgents": {
    "declarativeAgents": [
      {
        declarativeAgentRef object
      }
    ],
    "customEngineAgents": [
      {
        customEngineAgents object
      }
    ]
  },
  "elementRelationshipSet": {
    "oneWayDependencies": [
      {
        oneWayDependency object
      }
    ],
    "mutualDependencies": [
      [
        {
          elementReference object
        }
      ]
    ]
  }
}

{
  "$schema": "{string}",
  "manifestVersion": "1.19",
  "version": "{string}",
  "id": "{string}",
  "localizationInfo": {
    "defaultLanguageTag": "{string}",
    "defaultLanguageFile": "{string}",
    "additionalLanguages": [
      {
        additionalLanguages object
      }
    ]
  },
  "developer": {
    "name": "{string}",
    "mpnId": "{string}",
    "websiteUrl": "{string}",
    "privacyUrl": "{string}",
    "termsOfUseUrl": "{string}"
  },
  "name": {
    "short": "{string}",
    "full": "{string}"
  },
  "description": {
    "short": "{string}",
    "full": "{string}"
  },
  "icons": {
    "outline": "{string}",
    "color": "{string}"
  },
  "accentColor": "{string}",
  "configurableTabs": [
    {
      "configurationUrl": "{string}",
      "canUpdateConfiguration": {boolean},
      "scopes": [
        "team | groupChat"
      ],
      "meetingSurfaces": [
        "sidePanel | stage"
      ],
      "context": [
        "personalTab | channelTab | privateChatTab | meetingChatTab | meetingDetailsTab | meetingSidePanel | meetingStage"
      ],
      "sharePointPreviewImage": "{string}",
      "supportedSharePointHosts": [
        "sharePointFullPage | sharePointWebPart"
      ]
    }
  ],
  "staticTabs": [
    {
      "entityId": "{string}",
      "name": "{string}",
      "contentUrl": "{string}",
      "contentBotId": "{string}",
      "websiteUrl": "{string}",
      "searchUrl": "{string}",
      "scopes": [
        "team | personal | groupChat"
      ],
      "context": [
        "personalTab | channelTab | privateChatTab | meetingChatTab | meetingDetailsTab | meetingSidePanel | meetingStage | teamLevelApp"
      ]
    }
  ],
  "bots": [
    {
      "botId": "{string}",
      "configuration": {
        configuration object
      },
      "needsChannelSelector": {boolean},
      "isNotificationOnly": {boolean},
      "supportsFiles": {boolean},
      "supportsCalling": {boolean},
      "supportsVideo": {boolean},
      "scopes": [
        "team | personal | groupChat"
      ],
      "commandLists": [
        {
          commandLists object
        }
      ]
    }
  ],
  "connectors": [
    {
      "connectorId": "{string}",
      "configurationUrl": "{string}",
      "scopes": [
        "team"
      ]
    }
  ],
  "subscriptionOffer": {
    "offerId": "{string}"
  },
  "composeExtensions": [
    {
      "botId": "{string}",
      "composeExtensionType": "botBased | apiBased",
      "authorization": {
        authorization object
      },
      "apiSpecificationFile": "{string}",
      "canUpdateConfiguration": boolean | null,
      "commands": [
        {
          commands object
        }
      ],
      "messageHandlers": [
        {
          messageHandlers object
        }
      ]
    }
  ],
  "permissions": [
    "identity | messageTeamMembers"
  ],
  "devicePermissions": [
    "geolocation | media | notifications | midi | openExternal"
  ],
  "validDomains": [
    "{string}"
  ],
  "webApplicationInfo": {
    "id": "{string}",
    "resource": "{string}"
  },
  "graphConnector": {
    "notificationUrl": "{string}"
  },
  "showLoadingIndicator": {boolean},
  "isFullScreen": {boolean},
  "activities": {
    "activityTypes": [
      {
        activityTypes object
      }
    ]
  },
  "configurableProperties": [
    "name | shortDescription | longDescription | smallImageUrl | largeImageUrl | accentColor | developerUrl | privacyUrl | termsOfUseUrl"
  ],
  "supportedChannelTypes": [
    "sharedChannels | privateChannels"
  ],
  "defaultBlockUntilAdminAction": {boolean},
  "publisherDocsUrl": "{string}",
  "defaultInstallScope": "personal | team | groupChat | meetings",
  "defaultGroupCapability": {
    "team": "tab | bot | connector",
    "groupchat": "tab | bot | connector",
    "meetings": "tab | bot | connector"
  },
  "meetingExtensionDefinition": {
    "scenes": [
      {
        scenes object
      }
    ],
    "supportsStreaming": {boolean},
    "supportsAnonymousGuestUsers": {boolean}
  },
  "authorization": {
    "permissions": {
      permissions object
    }
  },
  "extensions": [
    {
      "requirements": {
        requirementsExtensionElement object
      },
      "runtimes": [
        {
          extensionRuntimesArray object
        }
      ],
      "ribbons": [
        {
          extensionRibbonsArray object
        }
      ],
      "autoRunEvents": [
        {
          extensionAutoRunEventsArray object
        }
      ],
      "alternates": [
        {
          extensionAlternateVersionsArray object
        }
      ],
      "audienceClaimUrl": "{string}"
    }
  ],
  "dashboardCards": [
    {
      "id": "{string}",
      "displayName": "{string}",
      "description": "{string}",
      "pickerGroupId": "{string}",
      "icon": {
        dashboardCardIcon object
      },
      "contentSource": {
        dashboardCardContentSource object
      },
      "defaultSize": "medium | large"
    }
  ],
  "copilotAgents": {
    "declarativeAgents": [
      {
        declarativeAgentRef object
      }
    ]
  }
}

Properties

$schema

The https:// URL referencing the JSON Schema for the app manifest. Optional, but recommended.

Type
string

Required
—

Constraints

Supported values

manifestVersion

The version of the app manifest schema that this app is using.

Type
string

Required
✅

Constraints

Supported values
Allowed values: devPreview, m365DevPreview.

manifestVersion

The version of the app manifest schema that this app is using.

Type
string

Required
✅

Constraints

Supported values
Allowed values: 1.19.

version

The version of the app, in semver standard (http://semver.org) format.

Update or additions to your app manifest require the version to be incremented. This way, when the new app manifest is installed, it overwrites the existing one and the user gets the new functionality. If the app was submitted to the Microsoft Teams Store, the new app manifest must be resubmitted and revalidated. After it's approved, users of this app receive the new updated app manifest automatically.

If there is a change to the app's requested permissions, users are prompted to upgrade and re-consent to the app.

Note

If your app includes an Office Add-in, each segment of the version string is limited to a maximum of five digits. The semver standard's prerelease and metadata version string extensions aren't supported.

Type
string

Required
✅

Constraints
Maximum string length: 256.

Supported values

id

Microsoft Entra application registration ID for your app.

The ID is a unique Microsoft-generated identifier for the app in the form of a GUID. You have an ID if your bot is registered through the Microsoft Bot Framework. You have an ID if your tab's web app already signs in with Microsoft. You must enter the ID here. Otherwise, you must generate a new ID at the Microsoft Application Registration Portal. Use the same ID if you add a bot.

The ID stored in Teams admin center is the External App ID and it's visible as ExternalID on the traces.

Note

If you are submitting an update to your existing app in AppSource, the ID in your app manifest must not be modified.

Type
string

Required
✅

Constraints

Supported values
The string value must be a guid.

packageName

A unique identifier for this app in reverse domain notation. E.g: com.example.myapp

Type
string

Required
—

Constraints
Maximum string length: 64.

Supported values

localizationInfo

Allows the specification of a default language, and pointers to additional language files. See localization.

Type
localizationInfo

Required
—

Constraints

Supported values

developer

Specifies information about your company. For apps submitted to the Teams Store, these values must match the information in your Teams Store listing. For more information, see the Teams Store publishing guidelines. Developer name helps improve your app discoverability in the Teams Store.

Type
developer

Required
✅

Constraints

Supported values

name

The name of your app experience, displayed to users in the Teams experience. For apps submitted to AppSource, these values must match the information in your AppSource entry. The values of short and full must be different. App name helps improve your app discoverability in the Teams Store.

Type
name

Required
✅

Constraints

Supported values

description

Describes your app to users.

Type
description

Required
✅

Constraints

Supported values

icons

Icons used within the Teams app. The icon files must be included as part of the upload package. For more information, see Icons.

Type
icons

Required
✅

Constraints

Supported values

accentColor

A color to use in conjunction with the icon. The value must be a valid HTML color code starting with '#', for example #4464ee.

Type
string

Required
✅

Constraints

Supported values
Value must be a hexidecimal color value, like #FFFFF.

configurableTabs

These are tabs users can optionally add to their channels and 1:1 or group chats and require extra configuration before they are added. Configurable tabs are not supported in the personal scope. Currently only one configurable tab per app is supported.

Type
Array of configurableTabs

Required
—

Constraints
Maximum array items: 1.

Supported values

staticTabs

A set of tabs that may be 'pinned' by default, without the user adding them manually. Static tabs declared in personal scope are always pinned to the app's personal experience. Static tabs do not currently support the 'teams' scope.

This property is required only for solutions that provide a static tab solution.

Type
Array of staticTabs

Required
—

Constraints
Maximum array items: 16. Array items must be unique.

Supported values

bots

The set of bots for this app. Currently only one bot per app is supported.

Type
Array of bots

Required
—

Constraints
Maximum array items: 1.

Supported values

connectors

The set of Office365 connectors for this app. Currently only one connector per app is supported.

Type
Array of connectors

Required
—

Constraints
Maximum array items: 1.

Supported values

subscriptionOffer

Subscription offer associated with this app.

Type
subscriptionOffer

Required
—

Constraints

Supported values

composeExtensions

The set of compose extensions for this app. Currently only one compose extension per app is supported.

Type
Array of composeExtensions

Required
—

Constraints
Maximum array items: 1.

Supported values

scopeConstraints

The scope constraints imposed on an app to specify in which threads you can install the app. When no constraints are specified, you can install the app to all threads within the specific scope.

Type
scopeConstraints

Required
—

Constraints

Supported values

permissions

Deprecated. Specifies the permissions the app requests from users.

Type
Array of enum

Required
—

Constraints
Maximum array items: 2.

Supported values
Allowed values: identity, messageTeamMembers.

devicePermissions

Specifies the permissions the app requests for accessing the user's device capabilities.

Type
Array of enum

Required
—

Constraints
Maximum array items: 5.

Supported values
Allowed values: geolocation, media, notifications, midi, openExternal.

validDomains

A list of valid domains from which the tabs expect to load any content. Domain listings can include wildcards, for example *.example.com. If your tab configuration or content UI needs to navigate to any other domain besides the one use for tab configuration, that domain must be specified here.

Do not include the domains of identity providers supported by your app.

If your app relies on SharePoint, you can include the associated root SharePoint site as a valid domain using the Teams JavaScript client library teamSiteDomain property from the SharePointSiteInfo context interface.

Office Add-ins, configured with an extensions property in the manifest, disregard domains containing a wildcard. If your app incorporates an Office Add-in, specify the full domain name for the domains that the add-in accesses.

Important

Don't add domains that are outside your control, either directly or through wildcards (). For example,.yoursite.com is valid, but *.onmicrosoft.com isn't valid as it isn't under your control.

When using wildcards, the following rules apply:

  • If a subdomain segment includes a wildcard, it must be the only character in the segment.
  • Any segment preceding a wildcard segment must also be a wildcard segment.

For example, *.*.domain.com is valid, but foo.*.myteam.domain.com is not valid.

Type
Array of string

Required
—

Constraints
Maximum string length: 2048. Maximum array items: 16.

Supported values

webApplicationInfo

Specifies information about the app's Microsoft Entra ID application registration.

If your app is registered with Microsoft Entra ID, use this object to provide application ID information. Administrators can easily review permissions and grant consent in Teams admin center.

The webApplicationInfo property is related to a single domain and isn't supported for multiple domains. Therefore, if you've two apps hosted on different domains, you need to create separate app manifests for each app.

Type
webApplicationInfo

Required
—

Constraints

Supported values

graphConnector

Specify the app's Graph connector configuration. If this is present then webApplicationInfo.id must also be specified.

Type
graphConnector

Required
—

Constraints

Supported values

showLoadingIndicator

Specifies whether or not to display a loading indicator when opening a tab or dialog in the app. If you set as true, follow the Teams platform guidance to show a native loading indicator, otherwise your page won't load correctly and will display the error message There was a problem reaching this app.

Type
boolean

Required
—

Constraints

Supported values
Default value: False.

isFullScreen

Specifies if a tab app is rendered without a tab header bar (signifying full screen mode).

This property only applies to apps published to your organization; it's ignored for uploaded and published third-party apps.

An isFullScreen value of true eliminates the app header bar and title for apps with tabs and dialogs. Best practice for chat bot apps is to leave this parameter as false.

Type
boolean

Required
—

Constraints

Supported values
Default value: False.

activities

Defines the notifications your app posts to the user's activity feed in Teams.

Type
activities

Required
—

Constraints

Supported values

supportedChannelTypes

Enables your app in non-standard channels. If your app supports a team scope and this property is defined, Teams enables your app in each channel type accordingly.

If your app supports a team scope, it functions in the standard channels regardless of the values that are defined in this property.

Your app can account for the unique properties of each of the channel types to function properly. To enable your tab for private and shared channels, see retrieve context in private channels and get context in shared channels.

Type
Array of enum

Required
—

Constraints
Maximum array items: 2.

Supported values
Allowed values: sharedChannels, privateChannels.

configurableProperties

Defines the app properties that Administrators can customize. For more information, see Enable customization for your app.

If present, a minimum of one property must be specified.

App customization isn't supported for custom apps uploaded or built for your org (line-of-business apps).

Administrators can define any of the following properties:

  • name: The app's display name.
  • shortDescription: The app's short description.
  • longDescription: The app's detailed description.
  • smallImageUrl: The app's outline icon.
  • largeImageUrl: The app's color icon.
  • accentColor: The color to use with and as a background for your outline icons.
  • developerUrl: The HTTPS URL of the developer's website.
  • privacyUrl: The HTTPS URL of the developer's privacy policy.
  • termsOfUseUrl: The HTTPS URL of the developer's terms of use.

Type
Array of enum

Required
—

Constraints
Maximum array items: 9.

Supported values
Allowed values: name, shortDescription, longDescription, smallImageUrl, largeImageUrl, accentColor, developerUrl, privacyUrl, termsOfUseUrl.

defaultBlockUntilAdminAction

A value indicating whether an app is blocked by default until admin allows it.

Type
boolean

Required
—

Constraints

Supported values
Default value: False.

publisherDocsUrl

The https:// URL to a page that provides additional information about your app.

Type
string

Required
—

Constraints
Maximum string length: 2048.

Supported values
The string must start with https://.

defaultInstallScope

The install scope defined for this app by default. This will be the option displayed with a Recommended option adjacent to the corresponding scope in the scope selection dialog, after the user adds the app.

Type
string

Required
—

Constraints

Supported values
Allowed values: personal, team, groupChat, meetings.

defaultGroupCapability

When a group install scope is selected, this will define the default capability when the user installs the app.

Type
defaultGroupCapability

Required
—

Constraints

Supported values

meetingExtensionDefinition

Specify meeting extension definition.

Type
meetingExtensionDefinition

Required
—

Constraints

Supported values

authorization

Specify and consolidates authorization related information for the App.

Type
authorization

Required
—

Constraints

Supported values

extensions

Type
Array of elementExtensions

Required
—

Constraints
Maximum array items: 1.

Supported values

actions

Defines one or more custom file handling actions your app can perform when invoked by the user from the context menu of a file in Microsoft 365 (Office) app.

Type
Array of elementActions

Required
—

Constraints
Minimum array items: 1.

Supported values

dashboardCards

Defines a list of cards that can be pinned to a dashboard, such as Microsoft Viva Connections, to provide a summarized view of app information. To learn more about creating cards for Viva Connections Dashboard, see Overview of Bot Powered Adaptive Card Extensions.

Type
Array of dashboardCard

Required
—

Constraints

Supported values

intuneInfo

The Intune-related properties for the app.

Type
intuneInfo

Required
—

Constraints

Supported values

copilotAgents

Defines one or more agents to Microsoft 365 Copilot. Declarative agents are customizations of Microsoft 365 Copilot that run on its same orchestrator and foundation models.

Type
copilotAgents

Required
—

Constraints

Supported values

elementRelationshipSet

Describes relationships among individual app capabilities, including staticTabs, configurableTabs, composeExtensions, and bots. It's used to specify runtime dependencies to ensure that the app only launches in applicable Microsoft 365 hosts, such as Teams, Outlook, and the Microsoft 365 (Office) app. For more information, see how to specify runtime requirements in your app manifest.

Type
elementRelationshipSet

Required
—

Constraints

Supported values