# MS Teams Integration Migration Guide

In recent versions of GoClaw, the Microsoft Teams integration no longer uses the legacy **AzureBot + Local File Server** architecture, in which the agent's files were served from GoClaw's own HTTP server. Files the agent sends now go through Microsoft's **File Consent** flow, and every inbound request is checked as coming from Bot Framework.

If you configured MS Teams with the older instructions, check the steps below: a single-tenant bot needs `tenant_id`, or the Teams channel does not start.

---

## 1. What Has Changed?

*   **File Sharing:** The legacy version hosted files generated by the agent on GoClaw's own HTTP server and sent a direct link. The new version replaces this entirely, using Microsoft's official **File Consent Card** to upload the file to the user's OneDrive once the user approves. Files a user sends to the agent need no card: GoClaw downloads them directly from Microsoft.
*   **Identity:** The sender's name and ID come from the Teams activity itself. Each inbound request must carry a Bot Framework token signed by Microsoft whose audience is your bot's App ID; others are refused with `401`. GoClaw does not call the Microsoft Graph API.
*   **Replies:** GoClaw posts a placeholder message while the agent works and replaces it with the whole answer when the turn ends. An answer too long for one Teams message continues in further messages.

---

## 2. Migration Steps

You do not need to delete or recreate your existing **Azure Bot** or **App Registration**, and no Microsoft Graph API permissions are needed. Earlier versions of this guide asked for `User.Read.All` and `Files.ReadWrite.All`; GoClaw does not use them, so a tenant administrator can remove them.

### Step 1: Verify Tenant ID in `config.yaml`

A single-tenant bot needs its `Tenant ID`. GoClaw requests its Bot Framework token from the tenant in `tenant_id`; with `tenant_id` empty it uses the multi-tenant `botframework.com` endpoint, which does not issue tokens for a single-tenant app, and the Teams channel does not start (`Teams channel failed:` in the gateway log). A multi-tenant bot can leave it empty.

Check if the `tenant_id` value is filled in the `channels.msteams` section of your GoClaw `config.yaml` file.

```yaml
channels:
  msteams:
    enabled: true
    app_id: "YOUR_APP_ID"
    app_password: "YOUR_APP_PASSWORD"
    tenant_id: "YOUR_TENANT_ID" # ← required for a single-tenant bot
    bot_name: "MyGoClawBot"
```

> **Where to find the Tenant ID?**
> Go to Azure Portal -> App Registrations -> Select your App -> Overview page, and copy the **Directory (tenant) ID**.

### Step 2: Restart the Server

Once the configuration is complete, restart the GoClaw server. 

```bash
# Installed with `goclaw service install` (a per-user service, the default):
systemctl --user restart goclaw

# Installed with `sudo goclaw service install --system`:
sudo systemctl restart goclaw

# Any installed service, including launchd on macOS:
goclaw service stop && goclaw service start

# Or if you are running it directly, stop and run it again:
goclaw
```

From now on, when the agent sends you a file (an Excel report, for example), a **"File Consent Card"** asking for permission appears in Teams. Clicking "Accept" uploads the file to your OneDrive; GoClaw posts no further message after the upload. A card left unanswered for 24 hours, or across a gateway restart, has expired: clicking "Accept" then gets a reply that the file is no longer available. Files you send to the agent need no card.

---

## 3. Known Limitations

- **File Consent Cards do not work in group chats or channels.** The Microsoft Bot Framework only renders consent cards inside 1:1 DMs. If a file is sent to a group, the card will appear but users will not be able to click it—hence, this feature is only supported in DMs.
- **SSO token exchange is not implemented.** GoClaw answers a `signin/tokenExchange` invoke with HTTP 200 and a body whose `status` is `412`, so the Teams client falls back to interactive sign-in. Inbound Bot Framework requests are verified; what GoClaw does not validate is the user's SSO token, so Teams SSO cannot be used.