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
- Read
<SKILL_DIR>/references/provider-config.yaml
- Append BOTH provider blocks (
ms-teams and ms-graph) to ~/.sig/config.yaml under providers:
- Ask the user: "Do you need a proxy to access this site?" — if yes, add
networkProxy: <url> under each provider in config.yaml
- Run
sig login ms-teams (with --network-proxy <url> if proxy was specified) — this covers both providers
- 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:
- Stored region from
memory/user-profile.md
--region CLI argument (if provided)TEAMS_REGION environment variable- 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.
| Script | Purpose | Token(s) |
|---|
teams_conversations.py | List/search conversations | Chat |
teams_messages.py | Get messages from a conversation | Chat |
teams_send.py | Send message or threaded reply | Chat |
teams_chat.py | Find 1:1 chat or create group chat | Chat + Graph |
teams_members.py | Get conversation members | Chat + Graph |
teams_meetings.py | Get recordings and transcripts | Chat |
teams_calendar.py | Get calendar events | Graph |
teams_people.py | Search people, manager, reports, profile | Graph |
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
| Error | Cause | Fix |
|---|
| 401 Unauthorized | Token expired | Auto-run sig login (no user prompt needed), retry |
| 403 Forbidden | No access to conversation | User lacks permission |
| 404 Not found | Invalid conversation ID | Check ID format, conversation may not exist |
NOT_FOUND (people) | No user matching query | Try a more specific name or email |
MISSING_ARGS | Required arguments missing | Check script --help for required args |
| Multiple candidates | Ambiguous people search | Ask user to specify more precisely |
Workflow Examples
Send a message to someone
- 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'
- 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
- Search:
sig run ms-teams -- bash -c 'python scripts/teams_conversations.py --token "$SIG_MS_TEAMS_ACCESS_TOKEN" --search "project standup"'
- 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'
- Summarize the returned messages
Get a meeting transcript
- Find recordings:
sig run ms-teams -- bash -c 'python scripts/teams_meetings.py --token "$SIG_MS_TEAMS_ACCESS_TOKEN" --conversation-id "$CONV_ID"'
- 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
sig run ms-graph -- bash -c 'python scripts/teams_calendar.py --graph-token "$SIG_MS_GRAPH_ACCESS_TOKEN" --range today'
Look up a colleague
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
- Manager:
sig run ms-graph -- bash -c 'python scripts/teams_people.py --graph-token "$SIG_MS_GRAPH_ACCESS_TOKEN" --action manager'
- 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
- 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'
- 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!"'