--- availability: INSTALLABLE installation_asset_uuid: 680cef50-7e2e-4b7b-8e65-12ac0fd530e7 name: Find Availability purple_chat_link: https://marketplace.moveworks.com/purple-chat?conversation=%7B%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Find+a+45-minute+slot+for+a+meeting+with+Jordan+Smith+and+Sarah+Jenkins+tomorrow+between+1+PM+and+5+PM.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ESearching+for+Jordan+Smith+and+Sarah+Jenkins%3C%2Fp%3E%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI+found+two+people+matching+%3Cstrong%3ESarah+Jenkins%3C%2Fstrong%3E+in+your+directory.+Which+one+would+you+like+to+check%3F%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22moveworks%22%2C%22citationTitle%22%3A%22Sarah+Jenkins+%28Marketing%29%22%7D%2C%7B%22connectorName%22%3A%22moveworks%22%2C%22citationTitle%22%3A%22Sarah+Jenkins+%28Sales%29%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22The+one+in+Marketing.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ERetrieving+calendar+schedules+for+Jordan+Smith+and+Sarah+Jenkins+from+%3Cb%3EOutlook%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22outlook%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI%27ve+checked+the+calendars+for+%3Cstrong%3EJordan+Smith%3C%2Fstrong%3E+and+%3Cstrong%3ESarah+Jenkins%3C%2Fstrong%3E.+Here+are+the+suggested+45-minute+windows+for+tomorrow%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E1%3A00+PM+-+1%3A45+PM%3C%2Fli%3E%3Cli%3E3%3A30+PM+-+4%3A15+PM%3C%2Fli%3E%3Cli%3E4%3A15+PM+-+5%3A00+PM%3C%2Fli%3E%3C%2Ful%3E%3Cp%3EYou+can+use+these+times+to+coordinate+your+meeting+invite+in+%3Cstrong%3EOutlook%3C%2Fstrong%3E.%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22outlook%22%2C%22citationTitle%22%3A%22Jordan+Smith%22%7D%2C%7B%22connectorName%22%3A%22outlook%22%2C%22citationTitle%22%3A%22Sarah+Jenkins+%28Marketing%29%22%7D%5D%7D%5D%7D%5D%7D solution_tags: - Finance - Other - HR - Other - IT - Productivity - Sales systems: - outlook description: Find a time that works for everyone before scheduling a meeting. --- ## Description Find available times across multiple attendees so you can skip the back-and-forth and get on each other's calendars faster. Simply specify who needs to attend, when, and for how long — and the assistant will suggest the best available slots based on everyone's calendars. ## User Experience Preview Please refer to the following [**Purple Chat**](https://marketplace.moveworks.com/purple-chat?conversation=%7B%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Find+a+45-minute+slot+for+a+meeting+with+Jordan+Smith+and+Sarah+Jenkins+tomorrow+between+1+PM+and+5+PM.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ESearching+for+Jordan+Smith+and+Sarah+Jenkins%3C%2Fp%3E%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI+found+two+people+matching+%3Cstrong%3ESarah+Jenkins%3C%2Fstrong%3E+in+your+directory.+Which+one+would+you+like+to+check%3F%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22moveworks%22%2C%22citationTitle%22%3A%22Sarah+Jenkins+%28Marketing%29%22%7D%2C%7B%22connectorName%22%3A%22moveworks%22%2C%22citationTitle%22%3A%22Sarah+Jenkins+%28Sales%29%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22The+one+in+Marketing.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ERetrieving+calendar+schedules+for+Jordan+Smith+and+Sarah+Jenkins+from+%3Cb%3EOutlook%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22outlook%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI%27ve+checked+the+calendars+for+%3Cstrong%3EJordan+Smith%3C%2Fstrong%3E+and+%3Cstrong%3ESarah+Jenkins%3C%2Fstrong%3E.+Here+are+the+suggested+45-minute+windows+for+tomorrow%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E1%3A00+PM+-+1%3A45+PM%3C%2Fli%3E%3Cli%3E3%3A30+PM+-+4%3A15+PM%3C%2Fli%3E%3Cli%3E4%3A15+PM+-+5%3A00+PM%3C%2Fli%3E%3C%2Ful%3E%3Cp%3EYou+can+use+these+times+to+coordinate+your+meeting+invite+in+%3Cstrong%3EOutlook%3C%2Fstrong%3E.%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22outlook%22%2C%22citationTitle%22%3A%22Jordan+Smith%22%7D%2C%7B%22connectorName%22%3A%22outlook%22%2C%22citationTitle%22%3A%22Sarah+Jenkins+%28Marketing%29%22%7D%5D%7D%5D%7D%5D%7D) for a sample conversational experience between a user and the AI Assistant for this plugin. ## Prerequisites Before installing and using the **Find Availability** plugin, ensure the following requirements are met. ### 1. Microsoft Graph Connector This plugin requires an active **Microsoft Graph connector** configured with the OAuth 2.0 Authorization Code (User Consent Auth) flow. - If you have not already set up the connector, follow the [**Microsoft Graph Connector Guide**](https://marketplace.moveworks.com/connectors/microsoft-graph#how-to-implement) before proceeding. Please follow the 'OAuth 2.0 with Authorization Code (User Consent Auth) Setup' section. - The connector must be fully configured and tested before installing this plugin. ### 2. Plugin Installation Once the connector is ready, follow the [**plugin installation documentation**](https://help.moveworks.com/docs/ai-agent-marketplace-installation) for steps on how to install and activate the plugin in Agent Studio. ### 3. Microsoft 365 System Requirements ### a. End User Permissions To find availability through this plugin, users must already have access to view calendar data in Microsoft 365 — the same access required to view free/busy information in Outlook. At a minimum, end users must have: - A licensed Microsoft 365 account with an active Exchange Online mailbox - Permission to view their own calendar - Free/busy visibility for other attendees must be enabled in their organization's Exchange Online settings. If an attendee's free/busy information is not accessible, they will be treated as unavailable ### b. Timezone and Working Hours Configuration for End User For availability to be calculated correctly, each user must have their timezone and working hours configured in Outlook. The plugin only searches for availability within each attendee's configured working hours. To configure timezone and working hours in Outlook: 1. Open **Outlook** and go to **Settings → View all Outlook settings → Calendar → View**. 2. Under **Time zone**, select your local timezone from the dropdown. 3. Under **Working hours**, set your working days and start/end times. ![image.png](Find%20Availability/image.png) ### c. API Permissions The Microsoft Graph connector uses **delegated permissions** to retrieve availability data on behalf of the authenticated user. The following permissions are required for this plugin: | Permission | Purpose | | --- | --- | | `Calendars.ReadWrite` | Read calendar free/busy data to find available slots | | `Place.Read.All` | Read room and location data for meeting suggestions | | `User.Read` | Read user profiles for resolving attendees | | `offline_access` | Maintain access via refresh tokens | **Note:** This plugin does not grant new permissions. It operates within the calendar access already granted to the authenticated user in Microsoft 365. ## Implementation Details ### Visual Representation of How the Plugin Works ![image.png](Find%20Availability/image%201.png) ### API Details This plugin uses two Microsoft Graph API calls. ### API #1: Get User Timezone Retrieves the authenticated user's timezone as configured in their Outlook mailbox settings. This is used to ensure availability suggestions are returned in the correct local timezone. ```bash curl --request GET \ --url 'https://graph.microsoft.com/v1.0/me/mailboxSettings' \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Content-Type: application/json' ``` **Key fields returned:** - `timeZone` *(string)* — The user's configured timezone (e.g., `Pacific Standard Time`). This value is passed as an input to API #2. ### API #2: Find Meeting Times Checks the free/busy status of all attendees and returns a ranked list of suggested meeting times based on availability, working hours, and the specified time window. ```bash curl --request POST \ --url 'https://graph.microsoft.com/v1.0/me/findMeetingTimes' \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Content-Type: application/json' \ --header 'Prefer: outlook.timezone="{{timezone}}"' \ --data '{ "attendees": [ { "type": "required", "emailAddress": { "address": "{{required_attendee_email}}" } }, { "type": "optional", "emailAddress": { "address": "{{optional_attendee_email}}" } } ], "timeConstraint": { "activityDomain": "work", "timeSlots": [ { "start": { "dateTime": "{{start_datetime}}", "timeZone": "{{timezone}}" }, "end": { "dateTime": "{{end_datetime}}", "timeZone": "{{timezone}}" } } ] }, "meetingDuration": "PT{{duration_in_minutes}}M", "isOrganizerOptional": false, "locationConstraint": { "isRequired": false, "suggestLocation": true }, "returnSuggestionReasons": true }' ``` **Request Body Parameters:** | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `required_attendees` | list of strings | Yes | Email addresses of required attendees. Availability is prioritized for this group. | | `optional_attendees` | list of strings | No | Email addresses of optional attendees. Their availability is considered but weighted lower. Defaults to an empty list. | | `start_datetime` | string | Yes | Start of the search window in ISO 8601 format, without timezone component. Example: `2026-01-26T00:00:00`. Defaults to now if not provided. | | `end_datetime` | string | Yes | End of the search window in ISO 8601 format, without timezone component. Example: `2026-02-02T00:00:00`. Defaults to one week from now if not provided. | | `duration_in_minutes` | integer | Yes | Duration of the meeting in minutes. Defaults to 30 minutes if not specified. | **Key nuances:** - The `activityDomain` is set to `work`, meaning the API only suggests times within each attendee's configured working hours. Times outside working hours will not be returned. This can be changed to `unrestricted` to include all hours if needed. - Suggestions are ranked by confidence — the likelihood that all required attendees are available. Suggestions with the same confidence are ordered chronologically. - The `isOrganizerOptional` flag is set to `false`, meaning the authenticated user's availability is always factored into suggestions. - The `returnSuggestionReasons` flag is set to `true`, so each suggestion includes a reason explaining why that time was recommended. - By default, the API returns **5 meeting time suggestions** via the `maxCandidates` parameter. This can be increased up to a maximum of 50. - If no suggestions are returned, the API will include an `emptySuggestionsReason` in the response explaining why — for example, no overlapping free time within the specified window. ## What Is In Scope for This Plugin? This plugin supports the following capabilities: - Find available meeting times for one or more **required attendees** within a specified time window - Factor in **optional attendees** whose availability is considered but weighted less in suggestions - Respect each attendee's configured **working hours** when suggesting times - Return **ranked suggestions** based on the likelihood of all required attendees being available - Support custom **meeting durations** specified by the user ## What Is Out of Scope for This Plugin? This plugin does **not** support the following: - Creating or scheduling the meeting — this plugin suggests times only. Booking the event is handled by a separate plugin - Finding availability outside of attendees' configured working hours - Accessing free/busy information for attendees whose calendar visibility has been restricted by their organization's Exchange Online policies - If no overlapping availability exists within the requested window, the API will return no suggestions. The user will need to adjust the time window or attendee list.