Ingest Microsoft Teams channel messages, chats, and meeting transcripts into CortexDB.

Microsoft Teams Connector

Captures Teams channel + chat activity via the Microsoft Graph API. Change-notifications for low-latency; delta queries as a fallback.

Info

Two ways to run this connector:

  • Run it yourself (Free + paid) — pip install 'cortexdb-connectors[teams]' then cortexdb-sync sync teams. The connector reads your token from ~/.cortexdb/state.json (written by cortexdb init) or from env vars.
  • Managed sync (Starter and up) — CortexDB runs the connector as a worker on its infrastructure. Configure it once from your dashboard; CortexDB handles webhook registration, retries, backfill, and idempotency.

1. Prepare credentials in Microsoft Entra (Azure AD)

Azure portal → App registrations → New registration. Add Microsoft Graph application permissions: ChannelMessage.Read.All, Chat.Read.All, OnlineMeetingTranscript.Read.All, User.Read.All. Have an admin grant tenant-wide consent.

Create a client secret and copy it.

2. Configure in your CortexDB dashboard

  1. Sign in at cortexdb.ai/login.
  2. Settings → Connectors → Add Connector → Microsoft Teams.
  3. Paste the tenant ID, client ID, and client secret.
  4. Pick the teams to sync (comma-separated IDs; leave empty for every team the app can see).
  5. Set the scope template. Default: org:<your-org>/source:teams/team:{team_id}/channel:{channel_id}.
  6. Click Start sync.

What gets written

EventModalityNotes
Channel messageconversationrole=user; @-mentions extracted into labels
Reply in threadconversationpreceded_by links parent
1:1 / group chat messageconversationScope template adapted
Meeting transcriptconversationPer-speaker turns; observed_actor set to speaker
File sharedocument (with content.kind=blob_ref)File uploaded via /v1/blobs first

idempotency_key shape: teams:<team>:<channel>:<message_id>.

Run it yourself

If you'd rather host the connector yourself instead of using CortexDB's managed worker, every connector ships in the cortexdb-connectors PyPI package:

pip install 'cortexdb-connectors[teams]'

# Step 1: get a CortexDB token + actor (one-time, free tier)
pip install cortexdb-cli
cortexdb init

# Step 2: supply the connector's third-party credentials
export TEAMS_TENANT_ID=...                # required
export TEAMS_CLIENT_ID=...                # required
export TEAMS_CLIENT_SECRET=...                # required

# Step 3: one-shot sync, or `watch` for a poll loop
cortexdb-sync sync teams
cortexdb-sync watch teams --interval 60

cortexdb-sync reads your CortexDB token + actor from ~/.cortexdb/state.json automatically. Cursor state is persisted in ~/.cortexdb/connectors-state.json, so re-running picks up where the last cycle left off.

See also