- name
- ms-graph-calendar
- description
- Find available meeting times and free/busy slots for company employees using Microsoft Graph API. Use when user asks to schedule a meeting, find a free slot, check when employees are available, or look up someone's calendar availability.
- version
- 1.0.0
- metadata
- {"openclaw": {"emoji": "📅", "requires": {"env": ["AZURE_TENANT_ID", "AZURE_CLIENT_ID", "AZURE_CLIENT_SECRET"], "bins": ["node", "curl"]}, "primaryEnv": "AZURE_CLIENT_SECRET"}}
Microsoft Graph Calendar — Find Free Slots
Use this skill when the user wants to:
- Find a time when multiple employees are all free
- Check if a specific person is available at a given time
- List upcoming meetings / busy blocks for one or more people
- Suggest meeting slots across the company
Setup (ทำครั้งแรกครั้งเดียว)
ถ้าผู้ใช้ยังไม่เคย setup หรือระบบแจ้งว่าขาด credentials ให้ทำดังนี้:
- ถามผู้ใช้ 3 ค่านี้ทีละค่า:
- AZURE_TENANT_ID (Azure Portal → Azure Active Directory → Overview) - AZURE_CLIENT_ID (App registrations → your app → Application (client) ID) - AZURE_CLIENT_SECRET (App registrations → your app → Certificates & secrets)
- เมื่อได้ครบแล้ว รันคำสั่ง:
node skills/ms-graph-calendar/scripts/setup.js \
--tenant-id <AZURE_TENANT_ID> \
--client-id <AZURE_CLIENT_ID> \
--client-secret <AZURE_CLIENT_SECRET>ค่าจะถูกบันทึกไว้ที่ ~/.openclaw/ms-graph-calendar.json (permission 600) และจะถูกโหลดอัตโนมัติทุกครั้งที่ใช้ skill
- ทดสอบด้วย:
node skills/ms-graph-calendar/scripts/get-token.jsถ้าได้ "✅ Token acquired" แปลว่าพร้อมใช้งานแล้ว
App Registration ต้องมี Application Permissions:
Calendars.Read— read all users' calendarsUser.Read.All— list employees- Admin ต้อง Grant consent ก่อน
Configuration
Authentication is cached after first login. No environment variables required for device code flow.
For headless/automated operation, set these environment variables:
- AZURE_CLIENT_ID - Azure AD app client ID
- AZURE_CLIENT_SECRET - Azure AD app secret
- AZURE_TENANT_ID - Tenant ID (use "consumers" for personal accounts)
Tools
This skill runs Node.js scripts via bash. Files:
scripts/— Node.js scriptsnicknames.md— ตาราง mapping ชื่อเล่น → email (แก้ไขได้เลย)
Instructions
Step 1 — Get Access Token
Before any Graph API call, get an app-only token:
node skills/ms-graph-calendar/scripts/get-token.jsStore the token in a temp variable for subsequent calls.
Step 2 — Parse the User's Request
Extract from the user's message:
- Who: names or emails of attendees (e.g. "Alice and Bob", "the marketing team")
- When: date range to search (e.g. "this week", "next Monday", "March 5–7")
- Duration: how long the meeting should be (default 60 minutes)
- Timezone: default to
Asia/Bangkokif not specified
If any info is missing, ask the user before proceeding.
Step 3 — Resolve Employee Emails
3a. ลองแปลงชื่อเล่นก่อน (เร็วกว่า ไม่ต้องเรียก API):
node skills/ms-graph-calendar/scripts/resolve-nicknames.js --names "แบงค์,มิ้ว,โบ้"อ่านจาก nicknames.md ในโฟลเดอร์ skill — แก้ไขได้ตรงนั้นเลย
3b. ถ้าหาไม่เจอใน nicknames.md ให้ fallback ไปค้น Graph API:
node skills/ms-graph-calendar/scripts/list-users.js --search "ชื่อ"Confirm กับ user ถ้ามีคนชื่อเดียวกันหลายคน
Step 4 — Find Free Slots (choose one method)
Method A — findMeetingTimes (best for small groups, ≤10 people):
node skills/ms-graph-calendar/scripts/find-meeting-times.js \
--attendees "alice@company.com,bob@company.com" \
--start "2025-03-01T08:00:00" \
--end "2025-03-01T18:00:00" \
--duration 60 \
--timezone "Asia/Bangkok" \
--max 5Method B — getSchedule (best for large groups or viewing free/busy blocks):
node skills/ms-graph-calendar/scripts/get-schedule.js \
--emails "alice@company.com,bob@company.com,carol@company.com" \
--start "2025-03-01T00:00:00" \
--end "2025-03-07T00:00:00" \
--timezone "Asia/Bangkok" \
--interval 30Step 5 — Present Results
Format the available slots clearly:
📅 Available slots where everyone is free:
1. Monday 3 Mar · 10:00–11:00
2. Tuesday 4 Mar · 14:00–15:00
3. Wednesday 5 Mar · 09:00–10:00
Which slot works best?If no slots are found, widen the search window and try again, or report that no common availability exists in that period.
Example Conversations
User: "Find a 1-hour slot this week where Alice, Bob, and Carol are all free" Agent:
- Resolves emails for Alice, Bob, Carol
- Runs
find-meeting-times.jswith date range = this Mon–Fri - Returns top 3 available slots
User: "Is John free tomorrow afternoon?" Agent:
- Resolves John's email
- Runs
get-schedule.jsfor tomorrow 12:00–18:00 - Reports free/busy blocks
User: "Show me everyone in the marketing team's availability next week" Agent:
- Lists users in the Marketing group via
list-users.js --group "Marketing" - Runs
get-schedule.jsfor all their emails - Presents a visual free/busy summary
Error Handling
| Error | Cause | Fix |
|---|---|---|
401 Unauthorized | Token expired or wrong credentials | Re-run get-token.js, check env vars |
403 Forbidden | Missing Admin Consent | Ask IT admin to grant consent in Azure Portal |
404 Not Found | User email doesn't exist | Verify email via list-users.js |
| No slots found | Everyone is busy | Widen time range or reduce attendees |
Security Notes
- Credentials are read from env vars only — never log or echo them
- This skill has read-only access to calendars (
Calendars.Read) - It cannot create, edit, or delete any events
- To restrict which mailboxes the app can read, ask your IT admin to set an App Access Policy in Exchange Online:
New-ApplicationAccessPolicy -AppId <ClientId> -PolicyScopeGroupId <GroupId> -AccessRight RestrictAccess