Microsoft Teams

Teams setup requires a single-tenant Azure Bot, a Teams application and known conversation details. Replies are visible to members of the conversation. Start in a personal bot chat when project information should stay private.

Before you start

You need permission to register an Entra application, configure Azure Bot, and install a custom Teams app in your tenant. Your OpenShip API must be reachable through public HTTPS. See connector prerequisites.

This connector currently requires the exact conversation.id and serviceUrl from a trusted, authenticated incoming Teams bot activity. It does not discover conversations during setup. For a new bot, collect those fields using your existing bot development endpoint before moving its messaging endpoint to OpenShip. A team ID, channel link or guessed service URL is not a substitute. See Microsoft's conversation reference guidance.

1. Register the bot

1. Create a single-tenant Microsoft Entra app. Record its Application (client) ID and Directory (tenant) ID.
2. Create a client secret and save its Value, not its secret ID.
3. Create an Azure Bot using that application ID, tenant and single-tenant identity. Enable the Microsoft Teams channel.
4. In the Teams Developer Portal, create a Teams app, add the existing bot by its application ID, and enable the scopes you need, such as personal or team.
5. Install the app in the intended scope. Your tenant's app policies must permit it.

Microsoft documents Azure bot configuration and testing a bot in Teams. Multi-tenant registrations and sovereign-cloud connector endpoints are not supported by this OpenShip connector.

2. Identify the allowed conversations

Send a message to your bot through its current development endpoint. From the authenticated activity, record only:

Keep message contents and authorization headers out of setup notes. The service URL must be the Microsoft connector URL from that activity, using smba.trafficmanager.net or smba.infra.teams.microsoft.com (including their subdomains). OpenShip checks that incoming activities match the configured tenant, conversation and service URL. Use separate connectors if conversations use different service URLs.

3. Save and route the bot to OpenShip

In Settings → Chat apps → Microsoft Teams, choose a name and bot role. Enter the application's client ID, tenant ID, client secret value, connector service URL and allowed conversation IDs. Select Save connector, then Enable bot.

Copy Bot webhook URL into the Azure Bot's Messaging endpoint and save. This moves delivery from the development endpoint to OpenShip. Bot credentials are encrypted in OpenShip and are never returned by the settings API.

4. Link and test

In a personal bot conversation, send /openship help. In a channel, mention the bot first, then enter /openship help.

Send /openship link, complete the OpenShip permission dialog and send the returned verification command from the original account and conversation. Use /openship projects to check access. Follow the deployment example to test a confirmed action.

Talk to your assistant

Select Assistant for conversations. Also select Control plane to use the same bot for deployment commands. Use a separate provider bot/application if you also want a dedicated deployment-command bot. After opt-in, /openship chats lists your earlier conversations here, /openship resume <conversation-id> continues one, and /openship chat opens the same conversation in OpenShip. You can continue it in either place. In Discord, enter chats, resume <conversation-id> or chat in the command’s text option.

Complete the assistant opt-in. In your personal bot chat, send Check my latest deployment, or /openship ask Check my latest deployment. In a channel, mention the bot with your question so Teams forwards it. Use /openship new to start a fresh conversation or /openship stop to stop your turn.

Replies are visible to members of that conversation, so prefer a personal bot chat for private app information. Each person must connect their own agent. The assistant's context is scoped to the sender and the provider's conversation ID.

Troubleshooting

• The bot cannot be installed: check your tenant's custom app policies, bot ID, enabled scopes and Azure Bot Teams channel.
• Requests are rejected: check tenant and application IDs, the exact conversation ID and service URL, and the secret value/expiry. Preserve the raw request and Authorization header at the proxy. Do not disable signature checks.
• No reply in a channel: mention the bot and verify the activity's conversation.id is allowed. Channel IDs copied from links may differ from this value.
• Replies stop after a configuration change: compare the current authenticated activity's service URL with the saved one. Recreate the connector with corrected settings and update its messaging endpoint.

See all commands and privacy behavior. A missing reply does not prove a deployment failed; check its history before repeating a write action.