{"skill":{"slug":"ms-graph-calendar","displayName":"Ms Graph Calendar","summary":"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,...","description":"---\nname: ms-graph-calendar\ndescription: 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.\nversion: 1.0.0\nmetadata: {\"openclaw\": {\"emoji\": \"📅\", \"requires\": {\"env\": [\"AZURE_TENANT_ID\", \"AZURE_CLIENT_ID\", \"AZURE_CLIENT_SECRET\"], \"bins\": [\"node\", \"curl\"]}, \"primaryEnv\": \"AZURE_CLIENT_SECRET\"}}\n---\n\n# Microsoft Graph Calendar — Find Free Slots\n\nUse this skill when the user wants to:\n- Find a time when multiple employees are all free\n- Check if a specific person is available at a given time\n- List upcoming meetings / busy blocks for one or more people\n- Suggest meeting slots across the company\n\n## Setup (ทำครั้งแรกครั้งเดียว)\n\nถ้าผู้ใช้ยังไม่เคย setup หรือระบบแจ้งว่าขาด credentials ให้ทำดังนี้:\n\n1. ถามผู้ใช้ 3 ค่านี้ทีละค่า:\n   - AZURE_TENANT_ID (Azure Portal → Azure Active Directory → Overview)\n   - AZURE_CLIENT_ID (App registrations → your app → Application (client) ID)\n   - AZURE_CLIENT_SECRET (App registrations → your app → Certificates & secrets)\n\n2. เมื่อได้ครบแล้ว รันคำสั่ง:\n```bash\nnode skills/ms-graph-calendar/scripts/setup.js \\\n  --tenant-id <AZURE_TENANT_ID> \\\n  --client-id <AZURE_CLIENT_ID> \\\n  --client-secret <AZURE_CLIENT_SECRET>\n```\n\nค่าจะถูกบันทึกไว้ที่ `~/.openclaw/ms-graph-calendar.json` (permission 600) และจะถูกโหลดอัตโนมัติทุกครั้งที่ใช้ skill\n\n3. ทดสอบด้วย:\n```bash\nnode skills/ms-graph-calendar/scripts/get-token.js\n```\nถ้าได้ \"✅ Token acquired\" แปลว่าพร้อมใช้งานแล้ว\n\n**App Registration ต้องมี Application Permissions:**\n- `Calendars.Read` — read all users' calendars\n- `User.Read.All` — list employees\n- Admin ต้อง Grant consent ก่อน\n\n---\n\n## Configuration\n\nAuthentication is cached after first login. No environment variables required for device code flow.\n\nFor headless/automated operation, set these environment variables:\n- AZURE_CLIENT_ID - Azure AD app client ID\n- AZURE_CLIENT_SECRET - Azure AD app secret\n- AZURE_TENANT_ID - Tenant ID (use \"consumers\" for personal accounts)\n\n\n---\n\n## Tools\n\nThis skill runs Node.js scripts via bash. Files:\n- `scripts/` — Node.js scripts\n- `nicknames.md` — ตาราง mapping ชื่อเล่น → email (แก้ไขได้เลย)\n\n---\n\n## Instructions\n\n### Step 1 — Get Access Token\nBefore any Graph API call, get an app-only token:\n```bash\nnode skills/ms-graph-calendar/scripts/get-token.js\n```\nStore the token in a temp variable for subsequent calls.\n\n### Step 2 — Parse the User's Request\nExtract from the user's message:\n- **Who**: names or emails of attendees (e.g. \"Alice and Bob\", \"the marketing team\")\n- **When**: date range to search (e.g. \"this week\", \"next Monday\", \"March 5–7\")\n- **Duration**: how long the meeting should be (default 60 minutes)\n- **Timezone**: default to `Asia/Bangkok` if not specified\n\nIf any info is missing, ask the user before proceeding.\n\n### Step 3 — Resolve Employee Emails\n\n**3a. ลองแปลงชื่อเล่นก่อน** (เร็วกว่า ไม่ต้องเรียก API):\n```bash\nnode skills/ms-graph-calendar/scripts/resolve-nicknames.js --names \"แบงค์,มิ้ว,โบ้\"\n```\nอ่านจาก `nicknames.md` ในโฟลเดอร์ skill — แก้ไขได้ตรงนั้นเลย\n\n**3b. ถ้าหาไม่เจอใน nicknames.md** ให้ fallback ไปค้น Graph API:\n```bash\nnode skills/ms-graph-calendar/scripts/list-users.js --search \"ชื่อ\"\n```\nConfirm กับ user ถ้ามีคนชื่อเดียวกันหลายคน\n\n### Step 4 — Find Free Slots (choose one method)\n\n**Method A — findMeetingTimes** (best for small groups, ≤10 people):\n```bash\nnode skills/ms-graph-calendar/scripts/find-meeting-times.js \\\n  --attendees \"alice@company.com,bob@company.com\" \\\n  --start \"2025-03-01T08:00:00\" \\\n  --end \"2025-03-01T18:00:00\" \\\n  --duration 60 \\\n  --timezone \"Asia/Bangkok\" \\\n  --max 5\n```\n\n**Method B — getSchedule** (best for large groups or viewing free/busy blocks):\n```bash\nnode skills/ms-graph-calendar/scripts/get-schedule.js \\\n  --emails \"alice@company.com,bob@company.com,carol@company.com\" \\\n  --start \"2025-03-01T00:00:00\" \\\n  --end \"2025-03-07T00:00:00\" \\\n  --timezone \"Asia/Bangkok\" \\\n  --interval 30\n```\n\n### Step 5 — Present Results\n\nFormat the available slots clearly:\n```\n📅 Available slots where everyone is free:\n\n1. Monday 3 Mar · 10:00–11:00\n2. Tuesday 4 Mar · 14:00–15:00\n3. Wednesday 5 Mar · 09:00–10:00\n\nWhich slot works best?\n```\n\nIf no slots are found, widen the search window and try again, or report that no common availability exists in that period.\n\n---\n\n## Example Conversations\n\n**User:** \"Find a 1-hour slot this week where Alice, Bob, and Carol are all free\"\n**Agent:**\n1. Resolves emails for Alice, Bob, Carol\n2. Runs `find-meeting-times.js` with date range = this Mon–Fri\n3. Returns top 3 available slots\n\n**User:** \"Is John free tomorrow afternoon?\"\n**Agent:**\n1. Resolves John's email\n2. Runs `get-schedule.js` for tomorrow 12:00–18:00\n3. Reports free/busy blocks\n\n**User:** \"Show me everyone in the marketing team's availability next week\"\n**Agent:**\n1. Lists users in the Marketing group via `list-users.js --group \"Marketing\"`\n2. Runs `get-schedule.js` for all their emails\n3. Presents a visual free/busy summary\n\n---\n\n## Error Handling\n\n| Error | Cause | Fix |\n|---|---|---|\n| `401 Unauthorized` | Token expired or wrong credentials | Re-run `get-token.js`, check env vars |\n| `403 Forbidden` | Missing Admin Consent | Ask IT admin to grant consent in Azure Portal |\n| `404 Not Found` | User email doesn't exist | Verify email via `list-users.js` |\n| No slots found | Everyone is busy | Widen time range or reduce attendees |\n\n---\n\n## Security Notes\n\n- Credentials are read from env vars only — never log or echo them\n- This skill has **read-only** access to calendars (`Calendars.Read`)\n- It cannot create, edit, or delete any events\n- To restrict which mailboxes the app can read, ask your IT admin to set an **App Access Policy** in Exchange Online:\n  ```powershell\n  New-ApplicationAccessPolicy -AppId <ClientId> -PolicyScopeGroupId <GroupId> -AccessRight RestrictAccess\n  ```\n","tags":{"latest":"1.0.2"},"stats":{"comments":0,"downloads":754,"installsAllTime":1,"installsCurrent":1,"stars":0,"versions":3},"createdAt":1772295782400,"updatedAt":1779077437045},"latestVersion":{"version":"1.0.2","createdAt":1772337721873,"changelog":"- Added scripts/setup.js for initial configuration of Azure credentials.\n- Updated documentation with a new \"Setup\" section describing how to prompt users for credentials and run the setup script.\n- Credentials are now stored securely in ~/.openclaw/ms-graph-calendar.json instead of requiring environment variables every time.\n- First-time and missing-credential onboarding flow improved for easier setup.","license":null},"metadata":{"setup":[{"key":"AZURE_TENANT_ID","required":true},{"key":"AZURE_CLIENT_ID","required":true},{"key":"AZURE_CLIENT_SECRET","required":true}],"os":null,"systems":null},"owner":{"handle":"artisong","userId":"s177dg8fc7b65e03fmtqebt6vs86nsg1","displayName":"ARTISONG","image":"https://avatars.githubusercontent.com/u/101783293?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1779967907973}}