npm package: @joshuanode/n8n-nodes-teamsbot
Description: n8n community nodes for Microsoft Teams Bot Framework (single-tenant ready).
Author: @joshuanode
Latest version: 0.0.4

# n8n-nodes-teamsbot

[![npm version](https://img.shields.io/npm/v/@joshuanode/n8n-nodes-teamsbot.svg)](https://www.npmjs.com/package/@joshuanode/n8n-nodes-teamsbot)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![n8n](https://img.shields.io/badge/n8n-community%20node-orange.svg)](https://n8n.io/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
[![GitHub](https://img.shields.io/badge/GitHub-repo-black.svg?logo=github)](https://github.com/ajoshuasmith/n8n-nodes-teamsbot)

This is an n8n community node for Microsoft Teams bots built on the Bot Framework API. It is designed for modern single-tenant bot registrations and gives you dedicated trigger and action nodes for receiving messages, replying, sending proactive messages, working with adaptive cards, managing conversation references, and calling Bot Framework conversation APIs directly from n8n.

[Installation](#installation) | [Operations](#operations) | [Credentials](#credentials) | [Usage](#usage) | [Resources](#resources)

## Installation

Follow the [installation guide](https://docs.n8n.io/integrations/community-nodes/installation/) in the n8n community nodes documentation.

### Community Nodes (Recommended)

1. Go to **Settings > Community Nodes**
2. Select **Install**
3. Enter `@joshuanode/n8n-nodes-teamsbot` in **Enter npm package name**
4. Agree to the [risks](https://docs.n8n.io/integrations/community-nodes/risks/) of using community nodes
5. Select **Install**

After installation, restart n8n to load the node.

### Manual Installation

```bash
npm install @joshuanode/n8n-nodes-teamsbot
```

## Operations

This package includes two nodes:

- **Microsoft Teams Bot Trigger** for incoming Bot Framework activities from Teams
- **Microsoft Teams Bot** for outbound Bot Framework actions and conversation utilities

### Trigger Node

The trigger node supports these activity types:

- `conversationUpdate`
- `event`
- `installationUpdate`
- `message`
- `messageDelete`
- `messageReaction`
- `messageUpdate`

Trigger features:

- Command router with configurable prefix and command definition JSON
- Webhook response mode selection: `onReceived`, `lastNode`, `responseNode`
- Proactive conversation reference capture
- Debug output
- Dedupe window controls
- Ignore bot-originated activities
- Include raw activity in output
- Validate channel endorsements
- Validate incoming JWT signatures using Bot Framework OpenID metadata and JWKS

### Action Node

| Resource | Operations |
|----------|------------|
| **Activity** | Send Activity, Reply To Activity, Update Activity, Delete Activity, Send Typing Indicator |
| **Adaptive Card** | Send Adaptive Card, Reply With Adaptive Card, Update Adaptive Card |
| **Attachment** | Send File Attachment, Send Inline Attachment |
| **Conversation** | Create Conversation, Create Direct Conversation, Get Conversation Details, Get Conversation Member, Get Conversation Members, Get Paged Conversation Members |
| **Proactive** | List References, Get Reference, Upsert Reference, Delete Reference, Send Proactive Message |
| **Reaction** | Add Reaction, Remove Reaction |

Additional action node features:

- Mention helper for sender auto-mention or explicit mention entity creation
- Retry count and retry delay controls
- Debug output with attempts and request metadata
- Output mode control: `Pass Through`, `Merge`, `Response Only`

## Credentials

This node uses Microsoft Bot Framework app credentials with single-tenant token acquisition.

### Required Fields

| Field | Description |
|-------|-------------|
| **Microsoft App ID** | The Azure app registration client ID for your bot |
| **Microsoft App Secret** | The client secret for your bot app registration |
| **Tenant ID** | The Microsoft Entra tenant ID used for single-tenant token acquisition |

The node requests access tokens from:

`https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token`

Using scope:

`https://api.botframework.com/.default`

## Usage

### Azure Messaging Endpoint

Point your bot's messaging endpoint in Azure to the production webhook URL of the trigger node:

`<your-n8n-webhook-base>/<workflow-webhook-path>/webhook`

Use the exact production URL configured by n8n for the active workflow.

### Minimal Reply Workflow

1. Add **Microsoft Teams Bot Trigger**
2. Configure your Azure bot messaging endpoint to the trigger webhook URL
3. Add **Microsoft Teams Bot** after the trigger
4. Select **Activity** as the resource
5. Select **Reply To Activity** or **Send Activity** as the operation
6. Map these fields from the trigger output:
   - **Service URL**: `{{$json.botContext.serviceUrl}}`
   - **Conversation ID**: `{{$json.botContext.conversationId}}`
   - **Activity ID**: `{{$json.botContext.activityId}}`

### Output Behavior

The action node defaults to `Pass Through` output mode. This preserves incoming trigger data such as `botContext` and appends:

- `teamsBotResponse`
- `teamsBotMeta`

Use `Merge` if you want the node fields merged into the current item, or `Response Only` if you want only the Bot Framework response payload.

### Common Use Cases

- Reply to incoming bot messages in Teams chats and channels
- Send proactive messages using stored conversation references
- Post adaptive cards for approvals or status updates
- Send typing indicators before long-running workflow steps
- Inspect conversation members and metadata

## Compatibility

- n8n version: 1.0+
- Authentication model: single-tenant Bot Framework app registration
- Designed for Bot Framework-based Teams bot workflows, not the standard Microsoft Teams Graph node model

## Resources

- [n8n Community Nodes Documentation](https://docs.n8n.io/integrations/community-nodes/)
- [Microsoft Bot Framework REST API](https://learn.microsoft.com/azure/bot-service/rest-api/bot-framework-rest-connector-api-reference)
- [Bot Framework authentication troubleshooting](https://learn.microsoft.com/azure/bot-service/bot-service-troubleshoot-authentication-problems)
- [Microsoft identity platform client credentials flow](https://learn.microsoft.com/entra/identity-platform/v2-oauth2-client-creds-grant-flow)

## Contributing

Contributions welcome. Open an issue or submit a pull request on [GitHub](https://github.com/ajoshuasmith/n8n-nodes-teamsbot).

## License

[MIT](LICENSE)