ContextQMD
Back to Eliza

Microsoft Teams Connector

packages/docs/connectors/msteams.md

2.0.16.7 KB
Original Source

Microsoft Teams Connector

Connect your agent to Microsoft Teams for DMs, team channels, and threaded conversations using the @elizaos/plugin-msteams package.

Prerequisites

  • An Azure Bot registration with App ID, App Password, and Tenant ID
  • The bot registered in the Microsoft Teams admin center

Configuration

NameRequiredDescription
MSTEAMS_APP_PASSWORDYesAzure Bot App Password (client secret)
MSTEAMS_APP_IDNoAzure Bot App ID (Microsoft App ID)
MSTEAMS_TENANT_IDNoAzure AD Tenant ID
MSTEAMS_ENABLEDNoEnable or disable the connector
MSTEAMS_WEBHOOK_PATHNoWebhook endpoint path
MSTEAMS_WEBHOOK_PORTNoPort for incoming webhook events
MSTEAMS_MEDIA_MAX_MBNoMaximum media file size in MB
MSTEAMS_ALLOWED_TENANTSNoComma-separated allowed tenant list
MSTEAMS_SHAREPOINT_SITE_IDNoSharePoint site ID for file uploads in group chats

The connector auto-enables when botToken, token, or apiKey is truthy in the connector config. The appId/appPassword/tenantId fields alone do not trigger auto-enable -- you must include one of the trigger fields or add the plugin to plugins.allow.

Configure in ~/.eliza/eliza.json:

json
{
  "connectors": {
    "msteams": {
      "botToken": "YOUR_BOT_TOKEN",
      "appId": "YOUR_APP_ID",
      "appPassword": "YOUR_APP_PASSWORD",
      "tenantId": "YOUR_TENANT_ID"
    }
  }
}

If you don't have a botToken, add the plugin explicitly:

json
{
  "plugins": {
    "allow": ["@elizaos/plugin-msteams"]
  },
  "connectors": {
    "msteams": {
      "appId": "YOUR_APP_ID",
      "appPassword": "YOUR_APP_PASSWORD",
      "tenantId": "YOUR_TENANT_ID"
    }
  }
}

To disable:

json
{
  "connectors": {
    "msteams": {
      "enabled": false
    }
  }
}

Setup

  1. Register an Azure Bot in the Azure Portal.
  2. Note the App ID, App Password (client secret), and Tenant ID.
  3. Configure the bot's messaging endpoint to point to your Eliza instance.
  4. Add the bot to Microsoft Teams via the Teams admin center.
  5. Add the credentials to your Eliza config.
  6. Start your agent.

Features

Environment Variables

When the connector is loaded, the runtime can consume the following secrets from environment variables as an alternative to inline config:

VariableRequiredDescription
MSTEAMS_APP_IDNoAzure Bot App ID
MSTEAMS_APP_PASSWORDYesAzure Bot App Password (client secret)
MSTEAMS_TENANT_IDNoAzure AD Tenant ID
MSTEAMS_ENABLEDNoEnable or disable the connector
MSTEAMS_WEBHOOK_PATHNoWebhook endpoint path
MSTEAMS_WEBHOOK_PORTNoPort for incoming webhook events
MSTEAMS_MEDIA_MAX_MBNoMaximum media file size in MB
MSTEAMS_ALLOWED_TENANTSNoComma-separated list of allowed tenant IDs
MSTEAMS_SHAREPOINT_SITE_IDNoSharePoint site ID for file uploads in group chats

Full Configuration Reference

All fields are defined under connectors.msteams in eliza.json.

Core Fields

FieldTypeDefaultDescription
appIdstring—Azure Bot App ID (Microsoft App ID)
appPasswordstring—Azure Bot App Password (client secret)
tenantIdstring—Azure AD Tenant ID
enabledboolean—Explicitly enable/disable
capabilitiesstring[]—Capability flags
configWritesboolean—Allow config writes from Teams events
requireMentionboolean—Only respond when @mentioned
dmPolicy"pairing" | "allowlist" | "open" | "disabled""pairing"DM access policy. "open" requires allowFrom to include "*"
allowFromstring[]—User IDs allowed to DM
groupPolicy"open" | "disabled" | "allowlist""allowlist"Group join policy
groupAllowFromstring[]—Allowed group/team IDs
historyLimitinteger >= 0—Max messages in context
dmHistoryLimitinteger >= 0—History limit for DMs
dmsobject—Per-DM history overrides keyed by DM ID. Each value: {historyLimit?: int}
textChunkLimitinteger > 0—Max characters per message chunk
chunkMode"length" | "newline"—Long message splitting strategy
mediaMaxMbnumber > 0—Max media file size in MB (up to 100MB via OneDrive upload)
blockStreamingCoalesceobject—Coalescing settings: minChars, maxChars, idleMs
replyStyle"thread" | "top-level""thread"Reply threading mode
markdownobject—Table rendering: tables can be "off", "bullets", or "code"

Webhook Configuration

FieldTypeDescription
webhook.portinteger > 0Port for incoming webhook events
webhook.pathstringPath for webhook endpoint (e.g., /api/msteams/webhook)

Media Configuration

FieldTypeDescription
mediaAllowHostsstring[]Allowlist of hosts from which media can be downloaded
mediaAuthAllowHostsstring[]Hosts that require authentication headers for media downloads
sharePointSiteIdstringSharePoint site ID for file uploads in group chats (e.g., "contoso.sharepoint.com,guid1,guid2")

Team Configuration

Per-team settings are defined under teams.<team-id>:

FieldTypeDescription
requireMentionbooleanOnly respond when @mentioned
toolsToolPolicySchemaTool access policy
toolsBySenderobjectPer-sender tool policies (keyed by sender ID)
replyStyle"thread" | "top-level"Override reply style for this team
channelsobjectPer-channel configuration (see below)

Channel Configuration

Per-channel settings are defined within a team under teams.<team-id>.channels.<channel-id>:

FieldTypeDescription
requireMentionbooleanOnly respond when @mentioned
toolsToolPolicySchemaTool access policy
toolsBySenderobjectPer-sender tool policies (keyed by sender ID)
replyStyle"thread" | "top-level"Override reply style for this channel

Heartbeat

json
{
  "connectors": {
    "msteams": {
      "heartbeat": {
        "showOk": true,
        "showAlerts": true,
        "useIndicator": true
      }
    }
  }
}