# Microsoft Teams

Symi connects to Microsoft Teams via the **Bot Framework** — you register a bot in Azure, configure a messaging endpoint, and the Symi gateway receives activities over HTTPS.

## Prerequisites

- An Azure account with permission to create an Azure Bot resource (free tier works for development).
- An Entra ID (Azure AD) tenant. Can be your work tenant or a personal "Microsoft 365 Developer Program" tenant.
- A publicly reachable HTTPS endpoint for Symi. During development you can use a Tailscale funnel or ngrok; for production, any TLS-terminated host works.
- Teams admin approval to sideload or publish the bot in your org (the sideload path is simplest for personal/dev use).

## Setup

1. **Create the Azure Bot**
   In the Azure Portal: _Create a resource_ → search _Azure Bot_ → Create. Choose:
   - Bot handle (e.g., `symi-bot`)
   - Subscription + resource group
   - Pricing tier (F0 Free is fine)
   - Microsoft App ID type: _Multi Tenant_ (easiest) or _Single Tenant_
   - Creation type: _Create new Microsoft App ID_

2. **Grab credentials**
   After creation → _Configuration_ tab. Note:
   - _Microsoft App ID_ (`appId`)
   - _Tenant ID_ (`tenantId`) — shown if Single Tenant
     _Manage Password_ → generate a client secret. Copy the secret value **immediately** — Azure only shows it once. That's your `appPassword`.

3. **Set the messaging endpoint**
   Same _Configuration_ tab → _Messaging endpoint_ → enter `https://<your-symi-host>/msteams/messages`. Save.

4. **Enable the Teams channel**
   Left sidebar → _Channels_ → _Microsoft Teams_ → _Apply_. Accept the terms.

5. **Add to `~/.symi/symi.json`**

   ```json
   {
     "channels": {
       "msteams": {
         "appId": "...",
         "appPassword": "...",
         "tenantId": "..."
       }
     }
   }
   ```

   Omit `tenantId` if the bot is multi-tenant.

6. **Restart the gateway** to load the new config.

## Install the bot in Teams

Azure's bot registration isn't automatically visible inside Teams — you need an app package.

1. Go to [Teams Developer Portal](https://dev.teams.microsoft.com/) → _Apps_ → _New app_.
2. Under _Basic information_ fill in the app name, descriptions, etc.
3. Under _App features_ → _Bot_ → select _Enter a bot ID_ and paste your `appId` from step 2.
4. Scope: _Personal_, _Team_, and/or _Group Chat_ depending on where you want to use it.
5. _Preview in Teams_ → install to yourself or your team.

For organization-wide rollout, submit the app via the Teams admin center's custom app catalog.

## Pairing

Like Slack, Teams DMs default to pairing mode — first-time users receive a pairing prompt so unauthorized people can't invoke the agent. Configure in `channels.msteams.pairing` (see full channel docs).

## Troubleshooting

- **Bot responds in Azure test but not in Teams** — Teams channel is not enabled yet (step 4), or the app package wasn't installed to Teams (above).
- **401 Unauthorized on incoming activities** — `appId` / `appPassword` mismatch, or `tenantId` set but the bot is actually multi-tenant (remove it).
- **Bot installed but silent** — check that the messaging endpoint is publicly reachable over HTTPS. Azure must be able to POST to it. Test with `curl -X POST https://<your-host>/msteams/messages` — you should see a 401 or 400 from Symi (meaning the route exists), not a connection failure.
- **Secret expired** — client secrets in Entra ID expire (default 2 years). Generate a new one in _Manage Password_ and update `appPassword`.

## Limitations

- Adaptive Cards beyond simple text are experimental.
- File attachments and inline images are not fully supported in all flows.
- Meeting and call actions (join, transcribe, etc.) are out of scope — Teams voice is handled separately.
- Each bot is tied to a specific Azure tenant's App ID — you can't share one bot registration across disconnected tenants without using multi-tenant mode.
