> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roomote.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Teams

> Configure Microsoft sign-in and Microsoft Teams bot messaging for Roomote.

Microsoft can be used for Roomote sign-in through Microsoft Entra and for
Teams messaging through a Microsoft Bot Framework bot. Configure sign-in when
users should authenticate with Microsoft. Configure the Teams bot when Roomote
should receive Teams messages, mentions, and replies.

Use `<public-url>` below for your stable public Roomote URL.

## Microsoft sign-in

Create a Microsoft Entra app registration:

1. open the [Microsoft Entra admin center](https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade)
2. go to **Applications > App registrations > New registration**
3. choose the tenant or account type this Roomote deployment should accept
4. under **Authentication**, add this **Web** redirect URI:

```text theme={null}
<public-url>/api/auth/oauth2/callback/microsoft-entra-id
```

5. under **Certificates & secrets**, create a client secret
6. save the client ID, secret value, and tenant ID in Roomote setup or env vars

```sh theme={null}
R_MICROSOFT_CLIENT_ID=...
R_MICROSOFT_CLIENT_SECRET=...
R_MICROSOFT_TENANT_ID=...
```

Roomote enables Microsoft sign-in only when all three values are present.

For a single-purpose Teams deployment, use the same Entra app for Microsoft
sign-in and the Teams bot. During Roomote setup, Roomote stores hidden Teams bot
credentials copied from the Microsoft client ID, secret, and tenant values. You
can override those bot credentials later from **Settings > Comms** if you need a
separate bot identity.

After Microsoft sign-in, **Settings > Linked Accounts** shows the Microsoft
Teams account. Users who signed in with another provider can link Microsoft
from that settings page.

## Teams bot registration

Create an [Azure Bot resource](https://learn.microsoft.com/en-us/azure/bot-service/abs-quickstart?view=azure-bot-service-4.0)
in the Azure portal. Use one bot registration per Roomote deployment.

Set the bot messaging endpoint to:

```text theme={null}
<public-url>/api/webhooks/teams
```

Enable the Microsoft Teams channel in the bot resource. Roomote setup stores
these bot values automatically from the Microsoft app values. If you configure
with env vars instead, set:

```sh theme={null}
R_TEAMS_BOT_APP_ID=<microsoft-app-id>
R_TEAMS_BOT_APP_PASSWORD=<client-secret>
R_TEAMS_BOT_TENANT_ID=<tenant-id>
R_TEAMS_BOT_NAME=<bot-display-name>
```

`R_TEAMS_BOT_NAME` is optional, but recommended when your Teams app is not named
Roomote. Roomote uses it in generated Teams app packages and user-facing
invocation guidance.

Advanced token overrides are available when your tenant or cloud environment
requires custom Bot Framework token settings:

```sh theme={null}
R_TEAMS_BOT_TOKEN_ENDPOINT=<token-endpoint-url>
R_TEAMS_BOT_OAUTH_SCOPE=<oauth-scope>
```

Restart Roomote after changing Teams env vars.

## Teams app package

Roomote generates the Teams app package for you: a zip with the app manifest
and icons, pre-filled with your bot app ID and deployment URL. Download it:

* during setup, from the **Configure Microsoft Teams app** step
* later, from the Microsoft Teams card in **Settings > Comms**

Upload the package in Teams under **Apps > Manage your apps > Upload an app**,
or import it in the
[Microsoft Teams Developer Portal](https://dev.teams.microsoft.com/apps).

The generated manifest uses Teams manifest v1.25, declares channel feature
readiness, and enables all three messaging scopes:

* **Personal** - direct messages to the bot start tasks
* **Team** - channel messages that mention the bot start tasks
* **Group chat** - group-chat messages that mention the bot start tasks

If you prefer to build the app package yourself in the Developer Portal, add a
bot capability that uses the same Microsoft App ID as `R_TEAMS_BOT_APP_ID` and
include the bot entry in the manifest:

```json theme={null}
{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.25/MicrosoftTeams.schema.json",
  "manifestVersion": "1.25",
  "accentColor": "#d6ee26",
  "authorization": {
    "permissions": {
      "resourceSpecific": [
        { "name": "Channel.Create.Group", "type": "Application" },
        { "name": "ChannelMember.Read.Group", "type": "Application" },
        { "name": "ChannelMessage.Read.Group", "type": "Application" },
        { "name": "ChannelMessage.Send.Group", "type": "Application" },
        { "name": "ChannelSettings.Read.Group", "type": "Application" },
        { "name": "ChatMessage.Read.Chat", "type": "Application" },
        { "name": "ChatMessage.Send.Chat", "type": "Application" },
        { "name": "Member.Read.Group", "type": "Application" }
      ]
    }
  },
  "bots": [
    {
      "botId": "<R_TEAMS_BOT_APP_ID>",
      "scopes": ["personal", "team", "groupChat"],
      "supportsFiles": true,
      "isNotificationOnly": false
    }
  ],
  "supportsChannelFeatures": "tier1",
  "validDomains": ["<public-host-without-scheme>"]
}
```

Upload and install the app in the Teams tenant you are using. Install it
personally to test DMs, and add it to a team or group chat to test mentions.

## Verify setup

1. run Roomote with the public URL you entered in Azure
2. send a direct message to the bot, or mention the bot in a channel or group chat
3. confirm Roomote starts a task and posts a Teams reply with the task link
4. reply in the same Teams conversation to send a follow-up to the task

The first verified Teams message also captures the conversation Roomote uses
for proactive output. When Slack and Telegram are not connected, setup
onboarding messages and automation summaries post to the most recently active
captured conversation, preferring team channels. Until Roomote captures a
conversation — typically from that first message, though other verified Teams
activity such as adding the app to a team can also capture one — the Microsoft
Teams card in **Settings > Comms** shows a reminder to open the app and send
the bot one message.

When an inbound Teams activity includes a Microsoft Entra AAD object ID,
Roomote can map it to an existing Microsoft sign-in account. If no mapping
exists yet, Roomote asks the sender to link their Microsoft account before
starting a task rather than launching it under another owner.

## Local URL changes

When the public URL changes, update the Azure Bot messaging endpoint, update
the Teams app package if its valid domain changed, reinstall the app if the
manifest changed, and restart Roomote with the matching URL.