Integrating Microsoft Calendar with SmythOS

This page shows you how to connect Microsoft Calendar to SmythOS and pick the right component for every calendar and scheduling task.

Want your Calendar to work smarter, not harder? Connect SmythOS to Microsoft Calendar to empower your agents to create calendars, manage events, and automate scheduling, bringing powerful organizational capabilities directly into your operational workflows.

TL;DR

Link your Microsoft Account to SmythOS by setting up OAuth 2.0 credentials in the Microsoft Entra (Azure AD) portal. Then, use our Microsoft Calendar components to enable your agents to automate various calendar tasks, reducing manual scheduling and event management.

Quick Links:

• Why Integrate Microsoft Calendar?
• Getting Started: Prerequisites & Connection
• Components Overview
• Understanding Common Fields
• Detailed Component Guides
• Best Practices & Advanced Tips
• Troubleshooting
• What's Next?

Why Integrate Microsoft Calendar

Microsoft Calendar is a critical tool within the Microsoft 365 suite, offering robust features for managing schedules, appointments, and events. By integrating it with SmythOS, you empower your agents to interact with your calendar programmatically, unlocking significant automation potential.

• Automated Calendar & Event Management: Agents can create new calendars for specific projects or teams, schedule meetings, block out time, or create reminders in Calendar based on triggers from other systems or agent logic.
• Dynamic Scheduling & Resource Allocation: Agents can read calendar availability (if list/get event components support this) to make intelligent scheduling decisions, preventing conflicts and finding optimal times for events or team activities.
• Centralized Scheduling Operations: Manage all your Calendar scheduling needs from within SmythOS, reducing the need to switch between multiple applications and streamlining workflows.
• Real-time Updates & Synchronization: Enable agents to update event details (like attendees, time, or location – if update event components are available) as circumstances change within your automated workflows.
• Enhanced Team Collaboration: Facilitate team collaboration by allowing agents to manage shared calendars and schedule meetings directly through automated processes.

Essentially, this integration transforms your Microsoft Calendar from a manual scheduling tool into an intelligent, interactive part of your SmythOS ecosystem. The result? Less manual effort, fewer scheduling errors, timely information, and more capacity for your team to focus on strategic tasks.

INFO

Why Integrate Microsoft Calendar with Your Agent?

Integrating Microsoft Calendar with SmythOS allows your agents to become active participants in your organization's scheduling and time management processes. Each component is designed for a specific calendar operation:

• Automated Calendar Setup: For new projects or teams, agents can automatically create dedicated shared calendars, ensuring everyone has access to relevant schedules from the start.
• Automated Event Creation: Let agents automatically schedule project kick-offs, client follow-ups, or internal reminders directly in team members' calendars when certain conditions are met in your workflows.
• Streamlined Meeting Coordination (Future Potential): While current components focus on calendar and event creation/listing, future enhancements could allow agents to check for free/busy times, propose meeting slots, and manage invitations more dynamically.
• Centralized Logging of Time-Sensitive Tasks: If your agent manages tasks with deadlines, it can create corresponding events in Calendar to ensure visibility and timely reminders for the team.

By connecting Microsoft Calendar, you reduce manual data entry for scheduling, minimize conflicts (with smarter future components), and ensure that team calendars accurately reflect activities and commitments managed by your automated SmythOS agents.

Prerequisites: What You'll Need to Get Started

Before you begin the integration, please ensure you have the following:

• An active SmythOS account. (If you're new to SmythOS, you can sign up here.)
• A Microsoft Account (Work or School account, or a personal Microsoft account, depending on your setup and API permissions) with access to Microsoft Calendar and permissions to grant access to applications.
• You will need to generate OAuth 2.0 credentials (Client ID and Client Secret) from the Microsoft Entra admin center (formerly Azure Active Directory portal). This process also involves configuring an OAuth consent screen and granting API permissions for Microsoft Graph (which includes Calendar). Detailed steps are provided below.
• The Authorized redirect URI for SmythOS, which is: https://app.smythos.com/oauth/oauth2/callback (You'll need this when creating credentials in Microsoft Entra).

Step-by-Step: Connecting Your Microsoft Account (for Calendar Access)

Let's establish the connection between SmythOS and your Microsoft Calendar. This involves obtaining OAuth 2.0 credentials from Microsoft Entra and then using them to authenticate within SmythOS. This is typically a one-time setup per Microsoft account you wish to integrate.

Part A: Obtaining Your Client ID and Client Secret from Microsoft Entra

1. Navigate to Microsoft Entra Portal:

• Go to the Microsoft Entra admin center.
• Sign in with an account that has permissions to register applications (usually an administrator account for your Microsoft 365 tenant or a developer account).

2. Register Your Application:

• In the left navigation pane, go to Identity > Applications > App registrations.
• Click on + New registration.

3. Provide Application Details:

• Name: Enter a descriptive name for your application (e.g., "SmythOS Calendar Integration").
• Supported account types: Choose the appropriate option based on who will be using this integration. For broad access, you might choose "Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)". If it's just for your organization, select "Accounts in this organizational directory only ([Your Tenant Name] only - Single tenant)".
• Redirect URI (optional but recommended for web apps):
  • Select Web from the platform dropdown.
  • Enter the SmythOS callback URL: https://app.smythos.com/oauth/oauth2/callback
  • This URI must be an exact match for the OAuth flow to complete successfully.
• Click on Register. Your application is now registered.

4. Obtain Client ID:

• Once registered, you'll be taken to the application's Overview page.
• Your Application (client) ID is displayed here. Copy this value and store it securely. This is your Client ID.

5. Generate a Client Secret:

• In the application's menu (left navigation), go to Certificates & secrets.
• Under the Client secrets tab, click on + New client secret.
• Description: Provide a description for the secret (e.g., "SmythOS Integration Secret").
• Expires: Choose an expiration period for the secret. Note that you'll need to renew it before it expires.
• Click on Add.
• Important: The client secret Value will be displayed once immediately after creation. Copy this value and store it securely (e.g., in SmythOS Vault or a password manager). You will not be able to retrieve it again after leaving this page. This is your Client Secret.

6. Configure API Permissions (Microsoft Graph):

• In the application's menu, go to API permissions.
• Click on + Add a permission.
• Select Microsoft Graph from the list of commonly used Microsoft APIs.
• Choose the type of permissions your application requires:
  • Delegated permissions: If your SmythOS agent will act on behalf of a signed-in user.
  • Application permissions: If your agent will run as a background service or daemon without a signed-in user (requires admin consent and is often used for broader organizational access). For most user-centric calendar operations, Delegated permissions are common.
• Search for and add the necessary permissions for calendar access. Common permissions include:
  • Calendars.ReadWrite (Allows the app to create, read, update, and delete events in all calendars the user can access, including delegate and shared calendars).
  • Calendars.Read (Allows the app to read events in all calendars the user can access).
  • offline_access (Maintains access to data you have authorized it to access, even when you are not currently using the application). This is crucial for refresh tokens.
• Select the permissions and click Add permissions.
• Grant Admin Consent: For some permissions, especially Application permissions or higher-privilege delegated permissions, an administrator may need to grant admin consent for your organization. If you see a button like "Grant admin consent for [Your Organization]," click it if you have the necessary admin rights. Otherwise, an admin will need to do this.

Secure Your Credentials!

Your Client ID and especially your Client Secret are highly sensitive. Treat them like passwords.

• Do NOT share them publicly.
• Do NOT commit them to repositories.
• Store them securely. SmythOS offers a Vault feature for managing sensitive credentials. Learn more about SmythOS Vault here.

Part B: Authenticating in SmythOS

1. Navigate to SmythOS Integrations: In your SmythOS dashboard, find and click on the "Integrations" section.
2. Add or Configure Microsoft (Calendar) Integration:

• Look for "Microsoft ," "Microsoft 365," or a specific "Microsoft Calendar" integration in the list and click to add or configure it.

3. Enter Your OAuth Credentials:

• You will see fields to input the Client ID (Application (client) ID) and Client Secret that you obtained from the Microsoft Entra admin center in Part A.
• You might also need to specify the Tenant ID (Directory (tenant) ID), which can also be found on the Overview page of your app registration in Azure.
• Carefully paste these values into the respective fields.

4. Initiate Authentication (OAuth Flow):

• Click the Authenticate, Connect, or Sign In button within the SmythOS integration settings.
• This will typically redirect you to a Microsoft sign-in page.

5. Microsoft Authorization Flow:

• Sign in using the Microsoft account whose calendar you want SmythOS to access.
• Microsoft will then display a consent screen, showing the name of your registered application (e.g., "SmythOS Calendar Integration") and the permissions it's requesting (based on the scopes you configured in Azure). Review these permissions.
• Click Accept or Allow to authorize SmythOS to access your Microsoft Calendar data.

6. Redirection to SmythOS:

• After successful authorization, you'll be redirected back to SmythOS.
• The Microsoft (Calendar) integration should now indicate that it's connected and authenticated. Connection Confirmed!

The Authenticate/Sign Out Button

The component settings may provide a versatile button designed to toggle between Authenticate and Sign Out based on the current authentication state.

• Authenticate Button: This serves as an additional method to initiate or re-initiate the authentication process.
• Sign Out Button: Allows users to disconnect the current Microsoft account from the SmythOS integration. This button is critical if the component cannot retrieve a valid token due to issues like invalidity, expiration, or other token-related problems. Using sign-out and then re-authenticating can resolve these.

Image: Example of Authentication/Sign Out button in component settings.

Microsoft Calendar Components: An Overview

With your Microsoft Account successfully linked via OAuth 2.0, you gain access to a suite of Microsoft Calendar components within SmythOS. These components are designed to automate various calendar and event management tasks.

Click any component name to jump directly to its detailed guide. Here’s what's available based on your provided text:

Component	Action Type	Summary
Create Calendar	Write	Creates a new calendar in the user's account. required userId, name
Update Calendar	Write	Modifies the properties of an existing calendar. required userId, calendarId, Body (calendar properties)
Delete Calendar	Write	Deletes an existing calendar. required userId, calendarId
Create Event	Write	Adds a new event to a specified calendar. required userId, Body (event properties)
List Events	Read	Retrieves a list of events from a user's primary or specified calendar. required userId

Authentication & Scopes

The OAuth 2.0 setup you completed (Client ID, Client Secret, and granted API permissions like Calendars.ReadWrite) handles the authentication for all these components. Ensure the granted scopes are sufficient for the actions each component performs.

Understanding Common Calendar Component I/O Fields

Many Microsoft Calendar components in SmythOS share common input parameters for identifying users or specific calendar entities, as well as common output structures for API responses from Microsoft Graph. This section defines these common elements to avoid repetition in the detailed component guides.

Required input fields used across multiple components:

Field	Type	Description
userId	string	Required. User ID (GUID), UPN, or me.
calendarId	string	Calendar ID for targeting specific calendars.
eventId	string	Used to retrieve or manipulate a specific event.
Body	object	JSON body payload for event/calendar data.
name	string	Name for a new calendar.

Footnotes

1. userId: Using me is standard for operations on the authenticated user's own data. For operations on other users' calendars (with appropriate permissions), their User Principal Name or ID would be used.
   
2. The structure of the Body input for creating/updating calendars and events is defined by the Microsoft Graph API. Refer to official Microsoft Graph documentation for precise schemas.

Deep Dive into Calendar I/O Fields

Switch between Inputs and Outputs below to see more detailed explanations and examples for parameters frequently used across multiple Microsoft Calendar components.

userId (string)

Required for all listed components. Identifies the user whose calendar data is being accessed.

• Use the special value me to refer to the currently signed-in user.
• Alternatively, use the user's ID (GUID) or User Principal Name (UPN, e.g., [email protected]).

Permissions

Accessing another user's data (not me) requires delegated or application permissions and admin consent.

INFO

Component guides will primarily list outputs specific to the action. Always refer to the Response output for the complete data structure returned by the Microsoft Graph API.

Quick Reference: Microsoft Calendar Components

Use this table to quickly compare inputs, outputs, and typical use cases for each Microsoft Calendar component.

Component	Key Input Fields (Type, Required, Description)	Key Output Fields (Type, Description)	Use Case & Details
Create Calendar	userId (string, Yes): User ID/UPN. name (string, Yes): Name for the new calendar (in Body).	id (string): ID of the created calendar. name (string): Name of the created calendar. (Full Calendar object in Response).	Creates a new calendar for the specified user.
Update Calendar	userId (string, Yes): User ID/UPN. calendarId (string, Yes): ID of calendar to update. Body (object, Yes): Calendar properties to update (e.g., name).	id (string): ID of the updated calendar. name (string): Updated name. (Full Calendar object in Response).	Modifies properties of an existing calendar.
Delete Calendar	userId (string, Yes): User ID/UPN. calendarId (string, Yes): ID of calendar to delete.	Response (object, often empty on success). Headers (object).	Permanently deletes a calendar. Use with caution.
Create Event	userId (string, Yes): User ID/UPN. calendarId (string, No): Target calendar ID (defaults to primary). Body (object, Yes): Event details (subject, start, end, attendees, etc.).	id (string): ID of the created event. iCalUId (string). webLink (string). (Full Event object in Response).	Adds a new event to a user's calendar.
List Events	userId (string, Yes): User ID/UPN. calendarId (string, No): Target calendar ID. $filter (string, No): OData filter query. $top (int, No): Max events to return.	value (array): List of event objects. @odata.nextLink (string, if paginated). Response (object).	Retrieves events from a calendar, with optional filtering and pagination.

Which Microsoft Calendar Component Should I Use With My Agent?

If you need to…	Typical Target / Key Inputs	Use this Component	Why this one?
Create a new shared calendar for a team or project	userId (of an owner/admin), Body with name	Create Calendar	Directly adds a new, empty calendar.
Rename an existing calendar	userId, calendarId, Body with new name	Update Calendar	Modifies properties of a known calendar.
Remove an old or unused calendar	userId, calendarId	Delete Calendar	Permanently deletes a calendar and its events.
Schedule a new meeting or appointment	userId, Body with event details (subject, start, end, attendees)	Create Event	Adds a new event to the user's default or specified calendar.
Get a list of upcoming appointments for a user	userId, (optional $filter for date range, $top)	List Events	Fetches events, often filtered by date (e.g., today, next 7 days).
Log a significant company milestone as an all-day event	userId, Body with event details, isAllDay: true	Create Event	Creates an all-day event in the calendar.

INFO

Still unsure? For creating new calendars or events, use the Create Calendar or Create Event components. To find existing events, List Events is your primary tool. For managing the calendars themselves, use Update Calendar or Delete Calendar.

Detailed Component Guides

This section provides detailed information for each Microsoft Calendar component. Remember to refer to the Understanding Common Calendar Component I/O Fields and Deep Dive Into Calendar I/O Fields for explanations of common inputs (like userId, calendarId, Body) and outputs (like Calendar resources, Event resources, Response, Headers). Each component guide below will highlight specific inputs and outputs for that action.

Create Calendar

Create a new calendar in the default calendar group or a specified calendar group for a user in Microsoft Calendar.

Use Case Example

An agent automatically creates a new shared "Q4 Marketing Campaigns" calendar when a new Q4 planning cycle is initiated in a project management tool, making it accessible to the marketing team.

Settings

Client ID & Client Secret

To kickstart this component, refer to Part 1, Step 1: Setting Up the Microsoft Integration (OAuth) in SmythOS for detailed instructions on obtaining your Client ID and Client Secret using Microsoft Entra and configuring API permissions. Essential permissions typically include Calendars.ReadWrite.

Note: Treat the Client ID & Client Secret as sensitive data. In SmythOS, you can securely manage it using the Vault feature. For more details, please refer to this section in the documentation.

🔑 Authenticate/Sign Out Button

The component provides a versatile button designed to toggle between Authenticate and Sign Out based on the current authentication state within the OAuth setup.

• Authenticate Button: This button serves as an additional method to authenticate, complementing the main Authenticate button already present in the component.
• Sign Out Button: Allows users to sign out when they are currently authenticated. This button is critical for resolving token-related issues.

Image: Example of Authentication/Sign Out button in component settings.

Inputs

Field	Type	Required?	Description
userId	string	Yes	The ID (GUID) or User Principal Name (UPN) of the user for whom the calendar is being created (e.g., me for the authenticated user).
name	string	Yes	The name of the new calendar. This is typically provided within the Body input.
Body	object	Yes	A JSON object containing the properties for the new calendar. At a minimum, this should include {"name": "Your Calendar Name"}. Other properties like color can also be set.

Image: Inputs for the Create Calendar component, highlighting userId. The name is part of the Body.

Note: With the flexibility and customization in mind, SmythOS allows you to expand the default input list by adding new inputs using the + button situated in the Inputs section. The Body input is where you'd structure the calendar resource.

Outputs

Field	Type	Description
Response	object	The raw JSON response received from the Microsoft Graph API, containing the full details of the newly created calendar object.
Headers	object	HTTP headers from the API response, useful for debugging and understanding request status.
id	string	The unique ID of the newly created calendar. Extracted from Response.id.
name	string	The name of the newly created calendar. Extracted from Response.name.
color	string	The color assigned to the calendar. Extracted from Response.color.
owner_email	string	The email address of the calendar owner. Extracted from Response.owner.address.

Image: Outputs from the Create Calendar component.

{{
 "component": "microsoft.createCalendar",
 "userId": "me",
 "Body": {`{{
  "name": "New Project Team Calendar"
 }}`}
}}

Troubleshooting

• Ensure the userId is correct and the authenticated account has Calendars.ReadWrite permissions for that user (or for me).
• The Body must be a valid JSON object representing a Microsoft Graph calendar resource.

Update Calendar

Update the properties of an existing calendar object in Microsoft Calendar, such as its name or color.

Use Case Example

After a project is completed, an agent renames the project's shared calendar to "Project Phoenix (Archived)" and changes its color to grey.

Settings

(Refer to the "Settings" section under Create Calendar for details on Client ID/Secret and authentication.)

Body (Input)

This is the field where the JSON data to update the calendar properties goes. You only need to include the properties you want to change.

Image: Example of the Body input field in the component settings, showing a sample JSON schema for updating calendar properties.

Inputs

Field	Type	Required?	Description
userId	string	Yes	The ID (GUID) or User Principal Name (UPN) of the user whose calendar is being updated (e.g., me).
calendarId	string	Yes	The unique ID of the calendar that you want to update.
Body	object	Yes	A JSON object containing the calendar properties to update (e.g., {"name": "Updated Calendar Name", "color": "lightRed"}).

Image: Inputs for the Update Calendar component.

Note: With the flexibility and customization in mind, SmythOS allows you to expand the default input list by adding new inputs using the + button situated in the Inputs section.

Outputs

Field	Type	Description
Response	object	The raw JSON response from the Microsoft Graph API, detailing the updated calendar object.
Headers	object	HTTP headers from the API response.
id	string	The ID of the updated calendar. Extracted from Response.id.
name	string	The updated name of the calendar. Extracted from Response.name.
color	string	The updated color of the calendar. Extracted from Response.color.

Image: Outputs from the Update Calendar component.

{`{{
 "component": "microsoft.updateCalendar",
 "userId": "me",
 "calendarId": "AQMkAGUzYjVlZmQ0LTNiZTItNGIwMi04RIGUzYjVlZmQ0LTNiZTItNGIwMi04NjRkLTQ4YjU0MjExN2YyZgBGAAADnhyYqXJ_S0aH8YQAAA==",
 "Body": {{
  "name": "Team Holidays (2025)",
  "color": "lightOrange"
 }}
}}`}

Permissions & ChangeKey

• Ensure Calendars.ReadWrite permission.
• Some updates might require providing the latest changeKey of the calendar to avoid conflicts, though this is less common for simple property updates via Graph API directly. The API usually handles optimistic concurrency.

Delete Calendar

This component is used to delete a calendar object in Microsoft Calendar. This action is permanent.

Use Case Example

When a temporary project concludes, an agent automatically deletes the associated project calendar to keep the user's clean and organized.

Settings

(Refer to the "Settings" section under Create Calendar for details on Client ID/Secret and authentication.)

Image: Authentication settings, similar for all components.

Inputs

Field	Type	Required?	Description
userId	string	Yes	The ID (GUID) or User Principal Name (UPN) of the user whose calendar is being deleted (e.g., me).
calendarId	string	Yes	The unique ID of the calendar that you want to delete.

Image: Inputs for the Delete Calendar component.

Note: With the flexibility and customization in mind, SmythOS allows you to expand the default input list by adding new inputs using the + button situated in the Inputs section.

Outputs

Field	Type	Description
Response	object	The raw response received from the Microsoft Graph API. A successful deletion typically returns an HTTP 204 No Content status, so the response body might be empty.
Headers	object	HTTP headers from the API response.
status	string	A status message indicating success or failure (e.g., "Successfully deleted" or an error message if parsed by SmythOS).

Image: Outputs from the Delete Calendar component.

{`{{
 "component": "microsoft.deleteCalendar",
 "userId": "me",
 "calendarId": "AQMkAGUzYjVlZmQ0LTNiZTItNGIwMi04NjRkLTQ4YjU0MjExN2YyZgBGAAADnhyYqXJ_S0aH8YQAAA=="
}}`}

Irreversible Action

Deleting a calendar is permanent and will also delete all events within that calendar. This action cannot be undone. Ensure you have the correct calendarId.

Create Event

Create a new event by posting to the events collection of a user's primary calendar or a specified calendar in Microsoft .

Use Case Example

An agent processes a new employee onboarding form and automatically schedules a "Welcome Meeting" in the new employee's calendar, inviting their manager and HR representative.

Settings

(Refer to the "Settings" section under Create Calendar for details on Client ID/Secret and authentication.)

Body (Input)

This is the field where the JSON payload to create an event goes. The schema includes properties like subject, body, start, end, attendees, location, etc.

Image: Example of the Body input field in the component settings, showing a sample JSON schema for creating an event.

Inputs

Field	Type	Required?	Description
userId	string	Yes	The ID (GUID) or User Principal Name (UPN) of the user for whom the event is being created (e.g., me).
calendarId	string	No	Optional. The ID of the specific calendar to create the event in. If omitted, the event is created in the user's default calendar.
Body	object	Yes	A JSON object representing the event to be created. Must include subject, start (with dateTime and timeZone), and end (with dateTime and timeZone). Other fields like body, attendees, location are optional.

Image: Inputs for the Create Event component.

Note: With the flexibility and customization in mind, SmythOS allows you to expand the default input list by adding new inputs using the + button situated in the Inputs section.

Outputs

Field	Type	Description
Response	object	The raw JSON response from the Microsoft Graph API, containing the full details of the newly created event object.
Headers	object	HTTP headers from the API response.
id	string	The unique ID of the newly created event. Extracted from Response.id.
iCalUId	string	The unique iCalendar identifier for the event. Extracted from Response.iCalUId.
webLink	string	A direct link to view the event in on the web. Extracted from Response.webLink.
subject	string	The subject of the created event. Extracted from Response.subject.
start_dateTime	string	The start date and time of the event. Extracted from Response.start.dateTime.
end_dateTime	string	The end date and time of the event. Extracted from Response.end.dateTime.

Image: Outputs from the Create Event component.

{{
 "component": "microsoft.createEvent",
 "userId": "me",
 "Body": {{
  "subject": "Quarterly Business Review",
  "body": {{
   "contentType": "HTML",
   "content": "Agenda: Review Q3 performance and plan for Q4."
  }},
  "start": {{
   "dateTime": "2025-11-05T10:00:00",
   "timeZone": "Pacific Standard Time"
  }},
  "end": {{
   "dateTime": "2025-11-05T11:30:00",
   "timeZone": "Pacific Standard Time"
  }},
  "attendees": [
   {{
    "emailAddress": {{ "address":"[email protected]", "name": "Alex Wilber" }},
    "type": "required"
   }},
   {{
    "emailAddress": {{ "address":"[email protected]", "name": "Megan Bowen" }},
    "type": "optional"
   }}
  ],
  "location": {{ "displayName":"Boardroom A" }}
 }}
}}

Time Zones & Event Body

• Ensure start.timeZone and end.timeZone are correctly specified using IANA time zone names (e.g., "Pacific Standard Time", "UTC", "FLE Standard Time"). Microsoft Graph API is sensitive to these.
• The Body for the event must be a valid JSON object representing a Microsoft Graph event resource.

List Events

Retrieve a list of events from a user's primary calendar or a specified calendar in Microsoft . Supports filtering and pagination.

Use Case Example

An agent fetches all events scheduled for "today" for a specific user to provide them with a daily agenda summary via a chat interface or email.

Settings

(Refer to the "Settings" section under Create Calendar for details on Client ID/Secret and authentication.)

Image: Authentication settings, similar for all components.

Inputs

Field	Type	Required?	Description
userId	string	Yes	The ID (GUID) or User Principal Name (UPN) of the user whose calendar events are being listed (e.g., me).
calendarId	string	No	Optional. The ID of a specific calendar to list events from. If omitted, events are listed from the user's default calendar.
$filter	string	No	Optional. An OData v4 filter query string to filter events (e.g., startswith(subject,'Important'), start/dateTime ge '2025-10-01T00:00:00Z' and end/dateTime le '2025-10-07T00:00:00Z').
$select	string	No	Optional. A comma-separated list of properties to include in the response for each event (e.g., subject,start,end,location).
$orderby	string	No	Optional. A comma-separated list of properties to sort the results by (e.g., start/dateTime asc or subject desc).
$top	integer	No	Optional. The maximum number of events to return in a single response (for pagination). Default is often 10. Max varies.
$skip	integer	No	Optional. The number of events to skip from the beginning of the result set (for pagination).

Image: Inputs for the List Events component.

Note: With the flexibility and customization in mind, SmythOS allows you to expand the default input list by adding new inputs using the + button situated in the Inputs section.

Outputs

Field	Type	Description
Response	object	The raw JSON response from the Microsoft Graph API. This object contains a value array of event objects and potentially an @odata.nextLink for pagination.
Headers	object	HTTP headers from the API response.
value	array	An array of event objects retrieved from the calendar, matching the filter criteria. Each object is a full Microsoft Graph Event resource. Extracted from Response.value.
@odata.nextLink	string	If present in the Response, this URL can be used to fetch the next page of results.

Image: Outputs from the List Events component.

{{
 "component": "microsoft.listEvents",
 "userId": "me",
 "$filter": "start/dateTime ge '2025-12-24T00:00:00Z' and end/dateTime le '2025-12-26T00:00:00Z'",
 "$select": "subject,start,end,location,webLink",
 "$orderby": "start/dateTime asc",
 "$top": 5
}}

Filtering & Pagination

• Construct OData $filter queries carefully. Refer to Microsoft Graph documentation for supported filter expressions on event properties.
• For large result sets, implement pagination logic using the @odata.nextLink from the Response object to fetch all events.
• Date/time values in $filter should generally be in ISO 8601 UTC format (ending with Z).

Best Practices & Advanced Tips

• Minimal Scopes & Permissions: During Microsoft Entra app registration, request only the minimum necessary API permissions (scopes) for Microsoft Graph that your agents require (e.g., Calendars.Read if only reading, Calendars.ReadWrite for modifications). Adhere to the principle of least privilege.
• Secure Credential Management: Store your Client ID and Client Secret securely using SmythOS Vault. Never embed them directly in agent scripts.
• Understanding userId: Use me for operations on the authenticated user's own calendar. When accessing other users' calendars (e.g., shared calendars or as an administrator), use their User Principal Name (UPN) or GUID, and ensure appropriate delegated (Calendars.Read.Shared, Calendars.ReadWrite.Shared) or application permissions have been granted and consented to.
• Time Zone Handling: Microsoft Graph API is particular about time zones for events. Always specify the timeZone property within the start and end objects for events. Use valid IANA time zone names (e.g., "Pacific Standard Time", "UTC", "FLE Standard Time"). When filtering events by date/time using OData ($filter), it's often best to use ISO 8601 UTC format (e.g., YYYY-MM-DDTHH:mm:ssZ).
• OData Query Parameters for Listing Events: Leverage OData system query options like $filter, $select, $top, $skip, and $orderby with the "List Events" component to efficiently retrieve only the data you need.
  • $select: Reduces payload size by only returning specified properties.
  • $filter: Crucial for fetching events within specific date ranges or matching other criteria.
  • $top & $skip (or @odata.nextLink): Essential for pagination.
• Error Handling: Check the Response object from components for errors. Microsoft Graph API provides detailed error codes and messages. Implement robust error handling and retry logic (with exponential backoff for throttling) in your agents.
• Idempotency for Event Creation: If an agent might retry creating an event, consider strategies to avoid duplicates. Microsoft Graph event creation is not idempotent by default. You might need to list existing events to check for similar ones before creating, or store IDs of created events. The iCalUId can be useful for identifying unique events across systems.
• Pagination for "List Events": If "List Events" might return many results, always check for an @odata.nextLink property in the Response. Use this URL to fetch subsequent pages of data until no @odata.nextLink is returned.
• changeKey for Updates (Advanced): For updating or deleting some Microsoft Graph resources (less common for basic calendar/event properties but good to be aware of), you might need to provide the latest changeKey of the item to ensure you're modifying the most recent version and to handle concurrency. The API usually handles this for common calendar/event updates.
• Rate Limiting & Throttling: Be aware of Microsoft Graph API rate limits and throttling. If agents make too many requests in a short period, you might receive 429 Too Many Requests or 503 Service Unavailable errors. Check for a Retry-After header in the Headers output and pause requests accordingly.

Troubleshooting Common Issues

Encountering an issue with your Microsoft Calendar integration? Here are solutions to some common problems:

• Authentication Errors (e.g., invalid_client, AADSTS... errors, token acquisition failure):
  • Cause: Incorrect Client ID or Client Secret; misconfigured Redirect URI in Microsoft Entra (must be https://app.smythos.com/oauth/oauth2/callback); app registration issues; user not consenting to required permissions; token expired or revoked.
  • Solution: Verify Client ID, Client Secret, and Tenant ID (if applicable) in SmythOS settings against your Microsoft Entra app registration. Ensure the Redirect URI is exact. Confirm the user has granted consent to all required API permissions during the OAuth flow. Try re-authenticating the integration in SmythOS.
• 403 Forbidden / Permission Denied Errors (e.g., "Access is denied. Check credentials and try again.", "Caller does not have permission"):
  • Cause: The authenticated user or the application itself (if using application permissions) lacks the necessary Microsoft Graph API permissions (scopes) for the requested operation (e.g., trying to write to a calendar with only Calendars.Read).
  • Solution: In Microsoft Entra, go to your app registration > API permissions. Ensure the required scopes (like Calendars.ReadWrite, Calendars.Read) are added and have been granted admin consent if necessary. If using delegated permissions, ensure the signed-in user has permissions on the specific calendar.
• 404 Not Found Errors (for Update/Delete Calendar, or specific Event operations):
  • Cause: The provided calendarId or eventId is incorrect, does not exist, or the authenticated user lacks permission to access it.
  • Solution: Double-check the ID for typos. Confirm the calendar or event exists in the user's . Verify permissions.
• 400 Bad Request (often with Body for Create/Update operations):
  • Cause: The JSON Body provided for creating/updating a calendar or event is malformed, missing required fields (like subject, start, end for events, or name for calendars), or contains invalid values/formats for properties.
  • Solution: Carefully validate the JSON structure of your Body against the Microsoft Graph API documentation for the Calendar or Event resource type. Ensure all required fields are present and data types/formats are correct (especially for date/time strings and time zones).
• Date/Time and Time Zone Issues with Events:
  • Cause: Incorrectly formatted dateTime strings (must be ISO 8601); missing or invalid timeZone property within start and end objects; confusion between UTC and local times.
  • Solution: Ensure dateTime is in a format like "YYYY-MM-DDTHH:mm:ss" (e.g., "2025-12-01T14:30:00"). Always provide a valid timeZone (e.g., "Pacific Standard Time", "UTC", "FLE Standard Time") within the start and end objects. For OData filters on dates, typically use UTC format (Z suffix).
• Events Not Appearing in "List Events" as Expected:
  • Cause: Incorrect $filter syntax; start/dateTime and end/dateTime in filter not matching event times due to time zone differences; pagination not handled (only first page shown); $top too small.
  • Solution: Test $filter queries using Microsoft Graph Explorer first. Ensure date/time values in filters are correctly formatted (usually UTC for comparisons). Implement pagination using @odata.nextLink. Increase $top if expecting more results per page.
• Throttling / 429 Too Many Requests or 503 Service Unavailable:
  • Cause: Making too many API requests to Microsoft Graph in a short period, exceeding service protection limits.
  • Solution: Reduce request frequency. Implement delays or exponential backoff strategies in agent logic. Check the Retry-After header in the Headers output and wait for the specified duration before retrying. Optimize queries using $select to fetch only necessary data.

INFO

For persistent issues, the Response object from the component is invaluable. It contains the raw JSON error message from the Microsoft Graph API, which usually provides specific error codes (e.g., ErrorAccessDenied, ErrorItemNotFound) and messages to help diagnose the problem. The SmythOS support team is also available to assist. [Link to SmythOS Support Page]

What's Next?

With SmythOS now integrated with your Microsoft Calendar, your agents are empowered to automate and streamline your scheduling, event management, and time-based workflows.

Here are some ideas to inspire your next automation:

• Build an Agent That...
  • Monitors a project management tool for new task assignments with deadlines and automatically creates corresponding events in the assignee's Calendar using "Create Event".
  • Allows users to request meetings via a SmythOS chatbot. The agent could then (with future "Get Free/Busy" components or by listing events) check availability and schedule the meeting using "Create Event", inviting all required attendees.
  • Sends a daily or weekly agenda summary to users via Microsoft Teams or email, by fetching upcoming events ("List Events") from their Calendar.
  • When a new team member is onboarded (triggered by an HR system), automatically creates a "New Team Onboarding" calendar ("Create Calendar") and schedules introductory meetings ("Create Event") with key colleagues.
• Enhance Your Workflows by Combining Data & Actions:
  • Use Google Gmail Integration to send customized email notifications or meeting invitations with additional context beyond the standard invites.
  • Trigger calendar events based on data received from SmythOS database connectors or other third-party API integrations (e.g., creating a calendar event when a new sales lead reaches a certain stage in a CRM).
  • Update a central dashboard or log file (e.g., using Google Sheets or SharePoint via SmythOS) with details of important meetings or calendar events managed by your agents for reporting or team visibility.
  • If an event is created for a customer meeting, an agent could also create a reminder task in Microsoft To Do or Planner (via other potential Microsoft Graph integrations).