msteams

Microsoft Teams

Send and read messages, search conversations, look up people, check calendar, get meeting transcripts, and manage chats via Microsoft Teams.

Setup (run FIRST — every time, before any operation)

You MUST complete this setup before running any script. Do NOT skip this step.

sig status ms-teams 2>&1
sig status ms-graph 2>&1

Check the JSON output fields configured and valid for BOTH providers:

• configured: false → run Provider Setup below. Do NOT proceed without completing it.
• valid: false (but configured: true) → run sig login ms-teams, then re-check.
• valid: true → detect proxy (see below), then execute the user's request.

Provider Setup

1. Read <SKILL_DIR>/references/provider-config.yaml
2. Append BOTH provider blocks (ms-teams and ms-graph) to ~/.sig/config.yaml under providers:
3. Ask the user: "Do you need a proxy to access this site?" — if yes, add networkProxy: <url> under each provider in config.yaml
4. Run sig login ms-teams (with --network-proxy <url> if proxy was specified) — this covers both providers
5. Verify: run sig status ms-teams and sig status ms-graph again — both must show valid: true before proceeding

Proxy Detection (after provider is valid)

grep -A15 "^\s*ms-teams:" ~/.sig/config.yaml | grep networkProxy | awk '{print $2}'

If this outputs a URL, prefix ALL python3 commands with HTTPS_PROXY=<url> HTTP_PROXY=<url>. If using socks5, convert to socks5h for python (e.g. socks5://... → socks5h://...). If empty, no proxy needed.

Running Scripts

All scripts require setup to be completed first (see above).

User Profile & Region Configuration

Before using this skill, check memory/user-profile.md for the user's stored profile (name, email, region, etc.). See CLAUDE.md for details.

All scripts support a --region parameter for the Teams Chat API regional endpoint. Resolution order:

1. Stored region from memory/user-profile.md
2. --region CLI argument (if provided)
3. TEAMS_REGION environment variable
4. Default: apac

Common regions: apac, emea, amer.

Region: If the region is not in memory/user-profile.md or the env var, ask the user once, then store it immediately in memory/user-profile.md.

Profile enrichment: When you call teams_people.py --action profile (or Graph /me), persist the user's name, email, and I-number to memory/user-profile.md so other skills can use them without re-querying.

Scripts Reference

All scripts are in this skill's scripts/ directory. Run via Bash tool.

teams_conversations.py

--token TOKEN          Chat API token (required)
--search TEXT          Filter by topic, participant, or content
--limit N             Max conversations (default: 20)
--since ISO_DATE      Only conversations after this time
--until ISO_DATE      Only conversations before this time
--region REGION        Teams region (default: $TEAMS_REGION or 'apac')

teams_messages.py

--token TOKEN          Chat API token (required)
--conversation-id ID   Conversation ID (required)
--search TEXT          Filter messages by content
--limit N             Max messages (default: 20, use 50+ for summarization)
--since ISO_DATE      Only messages after this time
--until ISO_DATE      Only messages before this time
--region REGION        Teams region (default: $TEAMS_REGION or 'apac')

teams_send.py

--token TOKEN          Chat API token (required)
--conversation-id ID   Conversation ID (required)
--message TEXT         Message content (required)
--format FORMAT        "html" (default) or "markdown"
--parent-message-id ID Parent message ID (for threaded replies)
--region REGION        Teams region (default: $TEAMS_REGION or 'apac')

teams_chat.py

--token TOKEN          Chat API token (required)
--graph-token TOKEN    Graph API token (required)
--query TEXT           Person name/email (finds 1:1 chat)
--members GUIDS        Comma-separated user GUIDs (creates group chat)
--topic TEXT           Group chat topic (optional)
--region REGION        Teams region (default: $TEAMS_REGION or 'apac')

teams_members.py

--token TOKEN          Chat API token (required)
--graph-token TOKEN    Graph API token (for name resolution, optional)
--conversation-id ID   Conversation ID (required)
--region REGION        Teams region (default: $TEAMS_REGION or 'apac')

teams_meetings.py

--token TOKEN          Chat API token (required)
--conversation-id ID   List recordings in conversation
--transcript-url URL   Fetch transcript content (Teams AMS URL only)
--region REGION        Teams region (default: $TEAMS_REGION or 'apac')

teams_calendar.py

--graph-token TOKEN    Graph API token (required)
--range RANGE          "today", "week", or "month"
--start ISO_DATE       Custom start date (alternative to --range)
--end ISO_DATE         Custom end date (use with --start)
--limit N             Max events (default: 50)

teams_people.py

--graph-token TOKEN    Graph API token (required)
--action ACTION        "search" (default), "manager", "reports", or "profile"
--query TEXT           Search query (required for search action)
--limit N             Max results (default: 10)
--enrich              Fetch extra details (I-number, city, country)

Message Formatting

When sending messages, use --format html (default) for rich formatting:

<b>Bold</b>, <i>Italic</i>, <a href="url">Link</a>
<ul>
    <li>Item</li>
</ul>
,
<ol>
    <li>Item</li>
</ol>
<pre>Code block</pre>
, <code>Inline code</code>

Or --format markdown for Teams markdown:

**bold**, _italic_, ~~strikethrough~~
`code`, [link](url), - bullet, 1. numbered

See references/messaging-guide.md for complete formatting reference.

Key Concepts

Conversation IDs — Unique identifiers for chats/channels. Format varies by type:

• 1:1 chat: 19:{guid1}_{guid2}@unq.gbl.spaces
• Group/channel: 19:{hash}@thread.tacv2

User GUIDs — Microsoft 365 user identifiers (e.g., abc12345-def6-7890-...). Get from teams_people.py --action search.

Transcript URLs — Only Teams AMS URLs (asyncgw.teams.microsoft.com) work with the Chat API token. SharePoint URLs require different auth.

Time parameters — All use ISO 8601: 2025-01-15 or 2025-01-15T09:00:00Z.

Error Handling

Workflow Examples

Send a message to someone

1. Find their chat:

   sig run ms-teams ms-graph -- bash -c 'python scripts/teams_chat.py --token "$SIG_MS_TEAMS_ACCESS_TOKEN" --graph-token "$SIG_MS_GRAPH_ACCESS_TOKEN" --query "John Smith" --region apac'
   

2. Send: sig run ms-teams -- bash -c 'python scripts/teams_send.py --token "$SIG_MS_TEAMS_ACCESS_TOKEN" --conversation-id "$CONV_ID" --message "Hello!" --region apac'

Summarize a conversation

1. Search: sig run ms-teams -- bash -c 'python scripts/teams_conversations.py --token "$SIG_MS_TEAMS_ACCESS_TOKEN" --search "project standup"'
2. Get messages: sig run ms-teams -- bash -c 'python scripts/teams_messages.py --token "$SIG_MS_TEAMS_ACCESS_TOKEN" --conversation-id "$CONV_ID" --limit 50'
3. Summarize the returned messages

Get a meeting transcript

1. Find recordings: sig run ms-teams -- bash -c 'python scripts/teams_meetings.py --token "$SIG_MS_TEAMS_ACCESS_TOKEN" --conversation-id "$CONV_ID"'
2. Fetch transcript: sig run ms-teams -- bash -c 'python scripts/teams_meetings.py --token "$SIG_MS_TEAMS_ACCESS_TOKEN" --transcript-url "$AMS_URL"'

Check today's calendar

1. sig run ms-graph -- bash -c 'python scripts/teams_calendar.py --graph-token "$SIG_MS_GRAPH_ACCESS_TOKEN" --range today'

Look up a colleague

1. sig run ms-graph -- bash -c 'python scripts/teams_people.py --graph-token "$SIG_MS_GRAPH_ACCESS_TOKEN" --action search --query "Jane Doe" --enrich'

Check org chart

1. Manager: sig run ms-graph -- bash -c 'python scripts/teams_people.py --graph-token "$SIG_MS_GRAPH_ACCESS_TOKEN" --action manager'
2. Reports: sig run ms-graph -- bash -c 'python scripts/teams_people.py --graph-token "$SIG_MS_GRAPH_ACCESS_TOKEN" --action reports'

Reply to a message in a thread

1. Get messages to find the parent message ID: sig run ms-teams -- bash -c 'python scripts/teams_messages.py --token "$SIG_MS_TEAMS_ACCESS_TOKEN" --conversation-id "$CONV_ID" --limit 10'
2. Reply: sig run ms-teams -- bash -c 'python scripts/teams_send.py --token "$SIG_MS_TEAMS_ACCESS_TOKEN" --conversation-id "$CONV_ID" --parent-message-id "$MSG_ID" --message "Thanks!"'