teams app create
Create a new Teams app with bot
Usage​
teams app create [options]
Options​
| Flag | Description |
|---|---|
-n, --name <name> | App/bot name |
-e, --endpoint <url> | [OPTIONAL] Messaging endpoint URL |
--messaging-mode <mode> | [OPTIONAL] How Teams delivers messages: socket or http |
--env <path> | [OPTIONAL] Path to credentials file (.env or appsettings.json) |
--env-file <path> | [OPTIONAL] Alias for --env |
--no-secret | [OPTIONAL] Skip client secret generation (for managed identity or federated credentials) |
--azure | [OPTIONAL] Create bot in Azure (requires az CLI) |
--teams-managed | [OPTIONAL] Create bot managed by Teams (default) |
--service-management-reference <id> | [OPTIONAL] ServiceTree service ID for Microsoft Entra app attribution |
--sign-in-audience <audience> | [OPTIONAL] Microsoft Entra sign-in audience: myOrg or multipleOrgs |
--subscription <id> | [OPTIONAL] Azure subscription ID (defaults to az CLI default) |
--resource-group <name> | Azure resource group (required for --azure) |
--create-resource-group | [OPTIONAL] Create the resource group if it doesn't exist |
--region <name> | [OPTIONAL] Azure region for resource group (default: westus2) |
--color-icon <path> | [OPTIONAL] Path to color icon (192x192 PNG) |
--outline-icon <path> | [OPTIONAL] Path to outline icon (32x32 PNG) |
--json | [OPTIONAL] Output as JSON |
Details​
Creates a complete Teams bot app in a single command: AAD app registration, client secret, manifest, Teams app import, and bot registration.
Manifest Version​
New apps use manifest schema version 1.30. The generated manifestVersion and $schema URL use the same pinned version, updated with CLI releases rather than discovered through an API. Existing apps and their manifest versions are not changed.
Bot Location​
By default, the bot is Teams-managed (no Azure subscription needed). Use --azure to create an Azure Bot instead, which is required for OAuth and SSO features.
Precedence: --azure/--teams-managed flag > teams config set default-bot-location > Teams-managed default.
See Bot Locations for details on the trade-offs.
Messaging Mode​
Use --messaging-mode socket to receive messages without a public HTTP endpoint or tunnel:
teams app create --name "My Bot" --messaging-mode socket
The CLI uses the production Teams Developer Portal to configure socket mode for both Teams-managed and Azure bots. Interactive creation offers a messaging-mode choice; scripted creation keeps HTTP mode unless socket mode is requested. --messaging-mode socket cannot be combined with --endpoint.
New Entra apps are created through the TDP v2 API so the caller is an owner, as required by the bot communication API. Service-attributed apps still use the legacy creation endpoint; socket mode may fail if the caller is not an owner.
If the app is created but enabling socket mode fails, the CLI prints a retry hint. JSON output includes socketMode: false and socketModeError in that case.
Scopes​
During interactive creation, you can customize which scopes the bot supports:
| Scope | Description |
|---|---|
| Personal | 1:1 chat with the bot (default) |
| Team | Channel conversations (default) |
| Group Chat | Group chat conversations (default) |
| Copilot | Available as a custom engine agent in M365 Copilot |
Selecting Copilot automatically adds the copilotAgents.customEngineAgents block to the manifest and ensures the Personal scope is included (required by M365 Copilot).
The built-in Chat (conversations) and About tabs are added only when Personal scope is enabled. Team-only and group-chat-only bots do not get personal tabs.
Channel Compatibility​
New apps include supportsChannelFeatures: "tier1" to declare support across all channel types. To add this declaration to an existing app after confirming compatibility:
teams app manifest update <appId> --set-json 'supportsChannelFeatures="tier1"'
Changing bot scopes does not change an existing channel compatibility declaration.
Examples​
Create with defaults (Teams-managed, generated manifest):
teams app create --name "My Bot"
Create with Azure bot and write credentials to .env:
teams app create --name "My Bot" --azure --subscription <id> --resource-group my-rg --env .env
For C# projects, write credentials to appsettings.json instead:
teams app create --name "My Bot" --env appsettings.json
This writes credentials under a Teams section with PascalCase keys (ClientId, ClientSecret, TenantId).
Skipping Secret Generation​
Use --no-secret to skip client secret generation when using managed identity or federated credentials:
teams app create --name "My Bot" --no-secret
Only CLIENT_ID and TENANT_ID are output. You can generate a secret later with teams app auth secret create.
Service-Attributed Apps​
Some tenants require new Microsoft Entra app registrations to be attributed to a service. Use --service-management-reference with the ServiceTree service ID, and --sign-in-audience myOrg when tenant policy requires a single-tenant app:
teams app create --name "My Bot" --service-management-reference <service-id> --sign-in-audience myOrg --no-secret
Output​
On success, outputs:
CLIENT_ID=<app-client-id>
CLIENT_SECRET=<generated-secret>
TENANT_ID=<your-tenant-id>
Portal Equivalent​
In the Teams Developer Portal, this is equivalent to: Apps → New app, then separately configuring bot registration and generating credentials. The CLI does it all in one step.