add-teams

# Add Microsoft Teams Channel

Connect NanoClaw to Microsoft Teams for interactive chat in team channels, group chats, and direct messages.

## Install

NanoClaw doesn't ship channels in trunk. This skill copies the Teams adapter in from the `channels` branch.

### Pre-flight (idempotent)

Skip to **Credentials** if all of these are already in place:

- `src/channels/teams.ts` exists
- `src/channels/teams-registration.test.ts` exists
- `src/channels/index.ts` contains `import './teams.js';`
- `@chat-adapter/teams` is listed in `package.json` dependencies

Otherwise continue. Every step below is safe to re-run.

### 1. Fetch the channels branch

```bash
git fetch origin channels
```

### 2. Copy the adapter and its registration test

```bash
git show origin/channels:src/channels/teams.ts                 > src/channels/teams.ts
git show origin/channels:src/channels/teams-registration.test.ts > src/channels/teams-registration.test.ts
```

### 3. Append the self-registration import

Append to `src/channels/index.ts` (skip if the line is already present):

```typescript
import './teams.js';
```

### 4. Install the adapter package (pinned)

```bash
pnpm install @chat-adapter/teams@4.27.0
```

### 5. Build and validate

```bash
pnpm run build
pnpm exec vitest run src/channels/teams-registration.test.ts
```

Both must be clean before proceeding. `teams-registration.test.ts` is the one integration test: it imports the real channel barrel and asserts the registry contains `teams`. It goes red if the `import './teams.js';` line is deleted or drifts, if the barrel fails to evaluate, or if `@chat-adapter/teams` isn't installed (the import throws) — so it also implicitly verifies the dependency from step 4. The adapter also calls core's `createChatSdkBridge(...)`; that typed core-API consumption is guarded by `pnpm run build`.

End-to-end message delivery against a real Teams workspace is verified manually once the service is running — see Next Steps and the webhook setup above.

## Credentials

Two paths — manual (Azure Portal) or auto (Teams CLI).

### Auto: Teams CLI

Requires Node.js 18+, a Microsoft 365 account with sideloading permissions, and a public HTTPS endpoint (ngrok, Cloudflare Tunnel, or similar).

1. Install the CLI:

   ```bash
   npm install -g @microsoft/teams.cli@preview
   ```

2. Sign in and verify:

   ```bash
   teams login
   teams status
   ```

3. Create the Entra app, client secret, and bot registration:

   ```bash
   teams app create \
     --name "NanoClaw" \
     --endpoint "https://your-domain/api/webhooks/teams"
   ```

   The CLI prints the credentials as `CLIENT_ID`, `CLIENT_SECRET`, and `TENANT_ID`. Map them to NanoClaw's env keys:

   - `CLIENT_ID` → `TEAMS_APP_ID`
   - `CLIENT_SECRET` → `TEAMS_APP_PASSWORD`
   - `TENANT_ID` → `TEAMS_APP_TENANT_ID`

4. Pick **Install in Teams** from the post-create menu and confirm in the Teams dialog.

Continue to [Configure environment](#configure-environment).

---

The steps below describe the **manual Azure Portal path**.

### Step 1: Create an Azure AD App Registration

1. Go to [Azure Portal](https://portal.azure.com) > **App registrations** > **New registration**
2. Name it (e.g., "NanoClaw")
3. Supported account types: **Single tenant** (your org only) or **Multi tenant** (any org)
4. Click **Register**
5. Copy the **Application (client) ID** and **Directory (tenant) ID** from the Overview page

### Step 2: Create a Client Secret

1. In the App Registration, go to **Certificates & secrets**
2. Click **New client secret**, description "nanoclaw", expiry 180 days
3. Click **Add** and **copy the Value immediately** (shown only once)

### Step 3: Create an Azure Bot

1. Go to Azure Portal > search **Azure Bot** > **Create**
2. Fill in:
   - **Bot handle**: unique name (e.g., "nanoclaw-bot")
   - **Type of App**: match your app registration (Single or Multi Tenant)
   - **Creation type**: **Use existing app registration**
   - **App ID**: paste from Step 1
   - **App tenant ID**: paste from Step 1 (Single Tenant only)
3. Click **Review + create** > **Create**

Or use Azure CLI:

```bash
az group create --name nanoclaw-rg --location eastus
az bot create \
  --resource-group nanoclaw-rg \
  --name nanoclaw-bot \
  --app-type SingleTenant \
  --appid YOUR_APP_ID \
  --tenant-id YOUR_TENANT_ID \
  --endpoint "https://your-domain/api/webhooks/teams"
```

### Step 4: Configure Messaging Endpoint

1. Go to your Azure Bot resource > **Configuration**
2. Set **Messaging endpoint** to `https://your-domain/api/webhooks/teams`
3. Click **Apply**

### Step 5: Enable Teams Channel

1. In the Azure Bot resource, go to **Channels**
2. Click **Microsoft Teams** > Accept terms > **Apply**

Or via CLI:

```bash
az bot msteams create --resource-group nanoclaw-rg --name nanoclaw-bot
```

### Step 6: Create and Sideload Teams App

Create a `manifest.json`:

```json
{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",
  "manifestVersion": "1.16",
  "version": "1.0.0",
  "id": "YOUR_APP_ID",
  "packageName": "com.nanoclaw.bot",
  "developer": {
    "name": "NanoClaw",
    "websiteUrl": "https://your-domain",
    "privacyUrl": "https://your-domain",
    "termsOfUseUrl": "https://your-domain"
  },
  "name": { "short": "NanoClaw", "full": "NanoClaw Assistant" },
  "description": {
    "short": "NanoClaw assistant bot",
    "full": "NanoClaw personal assistant powered by Claude."
  },
  "icons": { "outline": "outline.png", "color": "color.png" },
  "accentColor": "#4A90D9",
  "bots": [{
    "botId": "YOUR_APP_ID",
    "scopes": ["personal", "team", "groupchat"],
    "supportsFiles": false,
    "isNotificationOnly": false
  }],
  "permissions": ["identity", "messageTeamMembers"],
  "validDomains": ["your-domain"]
}
```

Create two icon PNGs (32x32 `outline.png`, 192x192 `color.png`), zip all three files together.

**Sideload in Teams:**
1. Open Teams > **Apps** > **Manage your apps**
2. Click **Uploa