Google Calendar Integration

Connect a Google Calendar once and MeetStream schedules a bot for your upcoming Google Meet, Zoom and Microsoft Teams meetings, then keeps those bots in sync as events move or get cancelled.

Before you start

• A MeetStream API key that is active. Every calendar feature runs under your API key. Without one, the dashboard’s Calendar page shows “No active API key found. Create one on the API Keys page.” See Dashboard Setup.
• Access to a Google Cloud project where you can enable APIs and create OAuth clients.
• Pick how you will connect:
  • Dashboard (recommended). MeetStream runs the Google consent screen for you and stores the resulting refresh token. You only paste a Client ID and Client Secret.
  • API. You run the consent flow yourself, obtain a refresh token, and send all three values to POST /api/v1/calendar/create_calendar. See Connect with the API instead.

Step 1: Create the Google OAuth app

These steps use the Google Cloud console. Menu names below match Google’s current documentation for the Google Auth platform and OAuth client creation.

Step 2: Connect Google Calendar in the dashboard

1

Open Calendar and start a connection

In the dashboard sidebar, under Configure, click Calendar (1). With no calendars connected yet, the page shows Connect a calendar. Click + Connect calendar (2).

Already have a calendar connected? Use + Connect another account on the Calendars page instead.

2

Copy the redirect URI

Step 1 on the page, Add this redirect URI first, shows the exact value to register in Google Cloud (1). Click Copy (2) and make sure the same value is in your OAuth client’s Authorized redirect URIs.

3

Paste your Client ID and Client Secret

On the Google Calendar card (“Connect with Google OAuth (BYOK).”), paste the Client ID (2) and Client Secret (3) from Google Cloud. Setup guide (1) links back to this page. Click Connect Google (4).

4

Approve access on Google's consent screen

You are redirected to Google. Sign in with the account whose calendar you want to connect and approve the requested read-only access. Google sends you back to MeetStream, which shows “Connecting your Google Calendar…” and then Google Calendar connected with a View calendars button.

Step 3: Turn on auto-join

On the Calendars page, the Auto-schedule bots card has a switch. When it is on, “MeetStream automatically schedules a bot for new meetings that have a join link.”

• Click Default bot settings to set the bot name, image URL, join message, audio and video, and automatic leave timeouts used for calendar bots.
• These defaults are saved in your browser and sent to MeetStream when you switch Auto-schedule bots on. After you change them, switch auto-join off and on again so the new defaults apply.
• Click a connected account to see its events. Sync events pulls the latest from Google, and Schedule bots lets you schedule individual events by hand.

Prefer the API? Turn auto-join on with POST /api/v1/calendar/auto-schedule/enable (see Enable auto-join with the API).

How auto-join works

Which links count as meeting links

MeetStream looks for a link in this order: the event’s Google Meet link (hangoutLink), a video entry in the conference data, URLs in the location, then meeting-platform URLs in the description.

Platform guides: Zoom, Google Meet, Microsoft Teams. To follow each bot’s progress, subscribe to webhooks; for every status and error, see the status and error code reference.

Connect with the API instead

Use this path when you want to run the Google consent flow in your own product, for example to connect your end users’ calendars.

Get a refresh token with the local helper

This small Node.js helper runs the Google consent flow on your machine and prints the refresh token. Register http://localhost:3000/api/google/oauth-callback as an Authorized redirect URI on your OAuth client first.

1. Create a .env file:

GOOGLE_CLIENT_ID=<YOUR_CLIENT_ID>
GOOGLE_CLIENT_SECRET=<YOUR_CLIENT_SECRET>

2. Install dependencies:

npm install express googleapis dotenv

3. Save this as server.js:

const express = require('express');
const { google } = require('googleapis');
require('dotenv').config();
const app = express();
const PORT = 3000;
const REDIRECT_URI = `http://localhost:${PORT}/api/google/oauth-callback`;
const oauth2Client = new google.auth.OAuth2(
  process.env.GOOGLE_CLIENT_ID,
  process.env.GOOGLE_CLIENT_SECRET,
  REDIRECT_URI
);
const scopes = [
  'https://www.googleapis.com/auth/calendar.events.readonly',
  'https://www.googleapis.com/auth/calendar.readonly',
  'https://www.googleapis.com/auth/userinfo.email',
  'https://www.googleapis.com/auth/userinfo.profile',
];
app.get('/', (_req, res) => {
  const authUrl = oauth2Client.generateAuthUrl({
    access_type: 'offline', // required to receive a refresh token
    scope: scopes,
    prompt: 'consent',      // forces Google to issue a new refresh token
    include_granted_scopes: true,
  });
  res.redirect(authUrl);
});
app.get('/api/google/oauth-callback', async (req, res) => {
  const { code, error } = req.query;
  if (error) return res.status(400).send(`<h1>OAuth error</h1><p>${error}</p>`);
  if (!code) return res.status(400).send('<h1>Missing authorization code</h1>');
  try {
    const { tokens } = await oauth2Client.getToken(code);
    res.send(`
      <h1>Success</h1>
      <h3>Refresh token</h3>
      <pre style="word-break:break-all">${tokens.refresh_token || 'Not returned: revoke access at https://myaccount.google.com/permissions and try again'}</pre>
      <p>Copy the refresh token, then stop this server.</p>
    `);
    console.log('Refresh token:', tokens.refresh_token);
  } catch (err) {
    res.status(500).send(`<h1>Token exchange failed</h1><pre>${err.message}</pre>`);
  }
});
app.listen(PORT, () => {
  console.log(`Open http://localhost:${PORT} to start the OAuth flow`);
  console.log(`Redirect URI: ${REDIRECT_URI}`);
});

4. Run node server.js, open http://localhost:3000, sign in with the Google account to connect, and approve access. Copy the refresh token from the page.

Connect the account

curl -X POST "https://api.meetstream.ai/api/v1/calendar/create_calendar" \
  -H "Authorization: Token <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "google_client_id": "<YOUR_GOOGLE_CLIENT_ID>",
    "google_client_secret": "<YOUR_GOOGLE_CLIENT_SECRET>",
    "google_refresh_token": "<YOUR_GOOGLE_REFRESH_TOKEN>"
  }'

MeetStream validates the credentials with Google, reads the account’s email (this becomes the connection’s account_id), fetches its calendars, stores the credentials encrypted, and subscribes to change notifications for the calendars the account owns or can edit. Each call connects one Google account; call it again with another account’s refresh token to add more.

Example response (trimmed):

{
  "calendar_id": "google_calendar_<user_id>_user@example.com",
  "platform": "google_calendar",
  "provider": "google",
  "account_id": "user@example.com",
  "is_replacement": false,
  "user_email": "user@example.com",
  "user_name": "Jane Smith",
  "calendars": [
    { "id": "user@example.com", "summary": "My Calendar", "accessRole": "owner", "selected": true }
  ],
  "primary_calendar_id": "user@example.com",
  "watch_setup": { "success": true, "failed_calendars": [] },
  "message": "Calendar connected successfully. Use /calendar/events and /calendar/schedule endpoints to manage events and bots."
}

Reconnecting the same account without replace returns 409:

{ "error": "Google account 'user@example.com' is already connected for this user. Pass {\"replace\": true} in the request body to reconnect." }

Calendar API reference

All endpoints use Authorization: Token <YOUR_API_KEY> and the base URL https://api.meetstream.ai. The same endpoints serve Google and Outlook connections; add ?provider=google&account_id=<email> to scope a call to one connected account.

List calendars

curl "https://api.meetstream.ai/api/v1/calendar/calendars" \
  -H "Authorization: Token <YOUR_API_KEY>"

Returns the calendars of every connected account, read live from the provider. Each entry carries provider and account_id.

Sync and list events

curl "https://api.meetstream.ai/api/v1/calendar/events?limit=20" \
  -H "Authorization: Token <YOUR_API_KEY>"

Each result includes meeting_url, meeting_platform (GMeet, Zoom or Teams) and a bots array with any bots scheduled for the event:

{
  "next": null,
  "results": [
    {
      "id": "evt_abc123",
      "start_time": "2026-10-08T15:00:00Z",
      "end_time": "2026-10-08T16:00:00Z",
      "calendar_id": "user@example.com",
      "provider": "google",
      "account_id": "user@example.com",
      "meeting_platform": "GMeet",
      "meeting_url": "https://meet.google.com/abc-defg-hij",
      "is_deleted": false,
      "bots": [
        {
          "id": "<bot_id>",
          "status": "Scheduled",
          "scheduled_join_time": "2026-10-08T15:00:00+00:00",
          "platform": "GMeet",
          "is_scheduled": true
        }
      ]
    }
  ],
  "has_more": false
}

GET /api/v1/calendar/get_events returns events already synced to MeetStream without calling the provider, which is faster when you do not need the latest changes.

Schedule a bot for one event

curl -X POST "https://api.meetstream.ai/api/v1/calendar/schedule/evt_abc123" \
  -H "Authorization: Token <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_config": {
      "bot_name": "Notetaker",
      "audio_required": true,
      "video_required": false,
      "bot_message": "Hi, I am recording this meeting for notes.",
      "callback_url": "https://your-domain.com/webhooks/meetstream",
      "automatic_leave": { "waiting_room_timeout": 300, "everyone_left_timeout": 60 }
    }
  }'

bot_config takes the same bot fields as create_bot (the meeting link comes from the event). Calendar bots default to audio on and video off.

Response (trimmed):

{
  "scheduled": true,
  "bot_id": "<bot_id>",
  "schedule_group": "gmeet",
  "event_id": "evt_abc123",
  "scheduled_time": "2026-10-08T14:58:00+00:00",
  "is_recurring_occurrence": false
}

scheduled_time is when the bot is dispatched (about 2 minutes before the start). Scheduling the same event twice returns 409 with "error": "A bot is already scheduled for this event", the existing bot_id, and a hint to use PATCH instead. If your account has no active API key, the call returns 400 with “No API key found. Please ensure your account has an active API key.”

Unschedule an event

curl -X DELETE "https://api.meetstream.ai/api/v1/calendar/schedule/evt_abc123" \
  -H "Authorization: Token <YOUR_API_KEY>"

For recurring events, pass {"cancel_all_occurrences": true} to cancel the whole series, optionally with "from_date" to cancel only occurrences from that date forward.

Manage scheduled bots

Enable auto-join with the API

curl -X POST "https://api.meetstream.ai/api/v1/calendar/auto-schedule/enable" \
  -H "Authorization: Token <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "default_bot_config": {
      "bot_name": "Notetaker",
      "audio_required": true,
      "video_required": false,
      "callback_url": "https://your-domain.com/webhooks/meetstream"
    }
  }'

If you omit default_bot_config, calendar bots use the name “MeetStream Calendar Bot” with audio on and video off. POST /api/v1/calendar/auto-schedule/disable turns auto-join off, and GET /api/v1/calendar/auto-schedule/settings returns auto_schedule_enabled and the stored default_bot_config. The rules in How auto-join works apply.

Disconnect an account

curl -X DELETE "https://api.meetstream.ai/api/v1/calendar/connections/google/user%40example.com" \
  -H "Authorization: Token <YOUR_API_KEY>"

This removes the connection, stops change notifications for it and cancels its scheduled bots. Synced events are deleted too; add ?purge_events=false to keep them. GET /api/v1/calendar/connections lists every connected account. The older DELETE /api/v1/calendar/disconnect works when only one account is connected; with several, it returns 400 (“Multiple calendar connections present; refusing to disconnect all without explicit account_id”) unless you pass provider and account_id.

FAQ

Which calendar providers are supported?

Google Calendar and Microsoft Outlook (Microsoft 365 and Outlook.com). See Outlook Calendar Setup. You can connect several accounts, from either provider, to the same MeetStream account.

Do I need a Google Workspace account?

No. Personal Google accounts and Google Workspace accounts both work. An Internal OAuth app only works for accounts in your own Workspace organization; use External to connect other accounts.

Why did a bot join a meeting I declined?

Auto-join does not look at RSVP status today. Every event with a meeting link in the next 24 hours gets a bot. Use per-event scheduling if you need to skip declined or external meetings.

How early does the bot join?

The bot is dispatched about 2 minutes before the event’s start time. scheduled_join_time on the bot is the start time itself.

What happens if I reschedule or cancel a meeting in Google Calendar?

Google notifies MeetStream. A moved event moves its bot’s join time; a deleted or cancelled event cancels its bot (Cancelled).

Can I schedule bots for events without a meeting link?

No. Events need a recognized Google Meet, Zoom or Microsoft Teams link. Events without one are shown in the dashboard but cannot be scheduled.

Can different meetings use different bot settings?

Yes. Auto-join uses your default bot settings for every meeting. To use different settings for one event, schedule it yourself with POST /api/v1/calendar/schedule/{event_id} and its own bot_config before auto-join picks it up, or update the scheduled bot with PATCH.

How is my calendar data protected?

OAuth credentials are stored encrypted and are never returned by the API. MeetStream requests read-only calendar scopes and never stores your Google password. You can revoke access at any time from your Google account or by disconnecting in MeetStream.

For webhook handling, see Webhooks and Events. To create a bot without a calendar, see Create your first bot.