Create a new Google Calendar OAuth Application
You’ll need to create a Google OAuth Application that users integrate with so that Attendee can access their calendar events. You can skip this step if your application won’t support Google Calendar. We recommend creating separate apps for development and production.Create OAuth project
Follow the directions here to create a new Google Cloud project that uses OAuth.
Configure scopes
Use the scopes
https://www.googleapis.com/auth/calendar.readonly and https://www.googleapis.com/auth/userinfo.email when creating the OAuth client.Get approved
Google will need to approve your application before external users can authorize it. See here for more information. Until your app is approved, only users that are on an allow-list can authorize it. To edit the allow-list navigate to APIs & Services → OAuth Consent Screen → Audience and go to the ‘Test Users’ section.
Create a new Microsoft Calendar OAuth Application
You’ll need to create a Microsoft Calendar OAuth Application that users integrate with so that Attendee can access their calendar events. You can skip this step if your application won’t support Microsoft Calendar. We recommend creating separate apps for development and production.Register application
Follow the directions here to create a new Microsoft Azure Active Directory application. When it asks you to choose ‘Supported account types’ select ‘Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)’.
Get verified
Microsoft will need to verify your application before external users can authorize it. See here for more information. This process is entirely automated and should take less than an hour. The steps to get verified are:
Add calendar webhooks to your Attendee project
If you haven’t done so already, we recommend using separate Attendee projects for development and production. These projects will correspond to your development and production OAuth applications.Add OAuth flow logic to your application
You’ll need to add code to handle the OAuth flow for users to authorize your Calendar OAuth Applications. The flow is essentially the same for both Google and Microsoft. Follow these steps for each application:Add auth endpoint
Add an
auth endpoint that your application will use to redirect users to the OAuth flow.Add callback endpoint
Add a
callback endpoint that your application will use to handle the OAuth callback.Exchange access code
In your callback endpoint, you’ll exchange the access code for a refresh token.
Create calendar in Attendee
In your callback endpoint, after you’ve retrieved the refresh token, make a POST /calendars request to the Attendee API to create a new calendar for the user who just authorized your application. In the request, you’ll pass the client id and secret of your application as well as the refresh token. We recommend you pass a deduplication key to prevent duplicate calendars from being created. This could be be the user’s email address or internal id.
Add Webhook processing logic to your application for the calendar.events_update trigger
When you receive a webhook with trigger typecalendar.events_update, it means that events for this calendar have been created or updated. The webhook payload itself does not contain the calendar events. Instead after you receive the webhook, you’ll need to make a GET request to the Attendee API to retrieve the newly created or updated calendar events. Here are the steps for doing that:
Track sync time
Ensure that your database has a column for each calendar to keep track of the last time you’ve synced it with Attendee.
Fetch updated events
In your GET request to the /calendar_events endpoint, pass the
calendar_id parameter to filter for events belonging to that calendar. Also pass the updated_after parameter to filter for events that have been updated since the last time you synced the calendar with Attendee.Add code to schedule bots for the calendar events to your application
Now that you’re syncing the calendar events from Attendee, you’ll need to add code to schedule bots for them. To schedule a bot for a calendar event, just use the normal POST /bots endpoint, but include thecalendar_event_id parameter to associate the bot with the calendar event. The resulting bot will be a scheduled bot with a join_at time, but unlike normal scheduled bots, the join_at will be a read-only property determined by the event’s start time. Also, if the calendar event is cancelled, the bot will be deleted.
If you want to unschedule a bot for a calendar event, make a request to the DELETE /bots/ endpoint.
The question of which calendar events get bots scheduled for them will depend on your application’s business logic. It is possible to schedule multiple bots for a single event. To add an additional safeguard to prevent scheduling duplicate bots for the same event, you can pass the deduplication_key parameter in the bot creation request. You can set this value equal to the event’s id.
We recommend you add a column to your database to keep track of which calendar events have bots scheduled for them.
Add Webhook processing logic to your application for the calendar.state_change trigger
When you receive a webhook with trigger typecalendar.state_change, it means that the calendar has moved to the disconnected state. This can happen if the user revokes access to the calendar or their calendar’s account is deleted.
On Attendee’s side, if a calendar is disconnected, all the scheduled bots associated with the calendar’s events will be deleted.
In your application, you should update the calendar in your database to reflect the disconnected state.
FAQ
How often does Attendee sync calendar events?
Attendee uses webhooks to sync calendar events from Google and Microsoft nearly instantly. We apply debouncing to webhook updates to reduce server load, so changes can take up to a minute to sync to Attendee.Which events does Attendee sync?
Attendee syncs all events in the calendar that are between 1 day in the past and 28 days in the future. If this window is too small for your application, please reach out.Which of a user’s calendars does Attendee sync?
This is determined by theplatform_uuid parameter you pass when creating the calendar via the POST /calendars request. By default, this parameter is null, which means we sync the user’s primary calendar. You can set the parameter to a non-null value to sync a non-primary calendar.