> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Calendar Auto-join

> Connect Google Calendar and control automatic meeting joins.

Connect Google Calendar once and the bot attends your meetings automatically: Meeting schedules a bot for eligible calendar events that have a supported join link. Each auto-joined meeting becomes a normal session with the same [live transcript](/docs/meeting/live-transcript), [recordings and results](/docs/meeting/collect-results), and [webhooks](/docs/meeting/webhooks). Outlook is reserved for a future release.

## Calendar API

The Calendar API includes eight routes:

| Method   | Route                                                 | Purpose                                                                                                                  |
| -------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `POST`   | `/v2/calendar_connections`                            | Start Google OAuth and return `pending_oauth` plus `oauth_url`; no connection row exists until the callback succeeds.    |
| `GET`    | `/v2/calendar_connections`                            | List connections owned by the authenticated connecting user.                                                             |
| `GET`    | `/v2/calendar_connections/{id}`                       | Retrieve one connection owned by that user.                                                                              |
| `PATCH`  | `/v2/calendar_connections/{id}`                       | Update policy, bot name, or future-session defaults.                                                                     |
| `DELETE` | `/v2/calendar_connections/{id}`                       | Disconnect and stop future joins for that connection.                                                                    |
| `GET`    | `/v2/calendar_connections/{id}/meetings`              | List tracked meetings; defaults to the next seven days and accepts an ISO-8601 `from`/`to` window up to 31 days.         |
| `PATCH`  | `/v2/calendar_connections/{id}/meetings/{meeting_id}` | Set `bot_will_join` to `true`, `false`, or `null` (follow policy).                                                       |
| `GET`    | `/v2/meeting_bot/calendar/oauth_callback`             | Browser OAuth callback. Identity comes from verified, short-lived signed state; clients do not call it with bearer auth. |

## Connect Your Calendar

```bash theme={null}
curl -X POST https://api.telnyx.com/v2/calendar_connections \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "platform": "google_calendar" }'
```

```json theme={null}
{
  "data": {
    "platform": "google_calendar",
    "status": "pending_oauth",
    "oauth_url": "https://accounts.google.com/o/oauth2/v2/auth?..."
  }
}
```

Open `oauth_url` in a browser and grant read-only calendar access. After the callback succeeds, list the connection to obtain its `id` and connected status.

## Configure Auto-join

```bash theme={null}
curl -X PATCH https://api.telnyx.com/v2/calendar_connections/calconn_... \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_join_policy": "external_organizer_excluded",
    "bot_name": "Calendar Notetaker",
    "default_barge_in": false,
    "default_summarize_on_end": true,
    "default_voice": null
  }'
```

| Policy                        | Behavior                                                                                                                                                                                                       |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `all_meetings`                | Join eligible events that have a supported meeting link.                                                                                                                                                       |
| `external_organizer_excluded` | Skip Google events where `organizer.self` is not `true`. This means the connected calendar user did not organize the event; it is not a domain comparison, so a coworker's same-domain event is also excluded. |
| `per_meeting`                 | Join only meetings explicitly opted in with the per-meeting PATCH route.                                                                                                                                       |

Connection defaults apply to sessions adopted after the change; they do not rewrite already-created sessions. `bot_will_join` in a meeting response is the effective decision under policy, while `bot_will_join_override` is the explicit nullable override.

## Timing, Ownership, and Identity Retention

Calendar scheduling applies the configured join lead time. If `event.start_time - lead_time` is still in the future, the bot starts joining then; if that lead window has elapsed, it starts at the event start time rather than using a past `join_at`.

Calendar connections, settings, and tracked-meeting controls are owned by the user who connected the calendar. Sessions generated from those meetings, and their transcripts, recordings, events, artifacts, and usage data, are organization-level Meeting resources visible to other authenticated users or API keys in the same Telnyx organization.

Organizer and attendee identities are retained only for a configured post-event window (currently 24 hours by default) and are then scrubbed from Calendar meeting records. Disconnecting also erases those Calendar identity fields. This identity-retention boundary does not delete the separately retained organization-level Meeting session resources.

## Related

* [Join with a meeting URL](/docs/meeting/join-meeting/meeting-url) -- create sessions through the API
* [Live Transcript](/docs/meeting/live-transcript) -- follow the transcript stream in real time
* [Collect Results](/docs/meeting/collect-results) -- read the finalized transcript and summary