Google Calendar Integration

Iris integrates with Google Calendar to give you conversational control over your schedule. Ask about upcoming events, create meetings, reschedule appointments, and manage your calendar through natural conversation.

Features

• View Events: See upcoming events and ask about your schedule
• Create Events: Schedule meetings with natural language
• Update Events: Modify times, titles, locations, and descriptions
• Delete Events: Cancel events when plans change
• Multi-Calendar Support: Work with multiple calendars

Setup

1. Create Google Cloud Credentials

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Calendar API
4. Go to Credentials and create an OAuth 2.0 Client ID
5. Set the application type to Web application
6. Add your callback URL: http://localhost:8000/settings/google/callback

2. Configure Environment

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

3. Connect Your Account

1. Open Iris and go to Settings
2. Find the Google Calendar integration
3. Click Connect and authorize access
4. Select which calendars Iris should have access to

Context Injection

When connected, Iris automatically receives your calendar events in every conversation — both upcoming events and recent past events. This gives Iris awareness of what you've had going on, not only what's ahead.

By default, Iris includes 3 days of past events and 7 days of future events. Both windows are configurable (see Configuration).

You: "Can we meet tomorrow?"

Iris: "I see you have a dentist appointment at 10am and a team standup at 2pm tomorrow. Would 11:30am or 4pm work better?"

You: "What did I have yesterday?"

Iris: "Yesterday you had a 1:1 with Alex at 10am and a sprint review at 3pm."

Available Tools

Tool	Purpose
list_calendar_events	Fetch upcoming events (1-30 days ahead)
create_calendar_event	Create new events with title, time, location
update_calendar_event	Modify existing events
delete_calendar_event	Remove events

Example Conversations

You: "What do I have this week?"

Iris: "Here's your week: Monday 10am Team standup, Tuesday 2pm Client call, Wednesday 9am Dentist..."

You: "Schedule a meeting with Sarah Tuesday at 3pm about the roadmap"

Iris: "Created: Project Roadmap Discussion with Sarah, Tuesday at 3:00 PM."

You: "Move my dentist appointment to Thursday"

Iris: "Done - moved from Wednesday 9am to Thursday 9am."

Configuration

Setting	Default	Description
calendar.cache_ttl	15	Cache duration (minutes)
calendar.event_horizon	7	Days ahead to include in context
calendar.event_lookback	3	Days in the past to include in context. Set to 0 to disable.

Security Considerations

Token Storage

Google OAuth tokens are stored encrypted in the database (google_token and google_refresh_token fields on the User model). Laravel's encryption uses your APP_KEY, so keep that secure.

Permissions Scope

Iris requests the https://www.googleapis.com/auth/calendar scope, which provides full read/write access to calendars the user selects. Users choose which calendars to share during the connection flow.

Token Refresh

Access tokens expire after 1 hour. Iris automatically refreshes them using the refresh token before making API calls. If the refresh token becomes invalid (user revokes access, token expires after 6 months of inactivity), the user needs to reconnect.

Troubleshooting

Calendar not connected: Disconnect and reconnect in Settings, ensure all permissions are granted.

Events not showing: Check that the calendar is selected in Settings and events fall within the configured look-back (3 days past) or event horizon (7 days ahead).

Can't create events: Verify you have write access to the target calendar.

"Token has been expired or revoked": The refresh token is invalid. Disconnect and reconnect in Settings.

Events appearing in wrong timezone: Iris uses ISO 8601 timestamps with timezone info. Check that your timezone is set correctly in Settings > Profile. The system default can also be configured in config/iris.php under temporal.timezone.