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 | Operations | Credentials | Usage | Resources

Installation

Follow the installation guide 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 of using community nodes
5. Select Install

After installation, restart n8n to load the node.

Manual Installation

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
• Microsoft Bot Framework REST API
• Bot Framework authentication troubleshooting
• Microsoft identity platform client credentials flow

Contributing

Contributions welcome. Open an issue or submit a pull request on GitHub.

License

MIT