---
title: Zoom API integration (meetings + cloud-recording metadata)
---

# Zoom API integration (meetings + cloud-recording metadata)

## What it is

> **Status:** in development. Enable it in **Settings → Lab → "Zoom API"**
> (or set `AMC_SHOW_ZOOM_API=1`); the "Zoom" sidebar row appears once it is on.
> If you have not configured Zoom OAuth app credentials yet, the panel shows a
> **setup wizard** that walks you through creating a Zoom OAuth app and entering
> your Client ID and Client Secret. Once credentials are saved, the normal
> "Connect Zoom" OAuth flow is available.

A first-party Omniscio integration that connects to your **real Zoom account**
via OAuth so you can see your meetings and cloud-recording metadata without
leaving Omniscio. It surfaces as a **"Zoom"** row in the projects sidebar
(gated via the `zoom-api` unreleased-feature registry, default off). It is
**read-only**: Omniscio never creates, edits, cancels, or joins a meeting on
your behalf; it only mirrors what Zoom already has.

This is a **Foundation PR**: the connection, sync, and browsing UI are built,
but transcript content, in-app recording playback, and any write/scheduling
action are explicitly out of scope for this pass (see Limitations).

## Where to find it

Turning the feature on adds a **Zoom** row to the projects sidebar, and the panel behind that row is the whole surface. Because it is still in development, the row stays hidden until **Zoom API** is enabled in **Settings → Lab**. The **gear** icon in the panel header opens **Zoom Settings** — connection status, **Disconnect**, the sync interval and **Sync Now** — inside the panel itself rather than on a page in the main Settings menu.

## How it behaves

### How to connect

1. **Enable it:** Settings → Lab → toggle **Zoom API** on. A "Zoom" row
   appears in the sidebar.
2. **Set up credentials (first time only):** if no Zoom OAuth app credentials
   are configured, the panel shows a setup wizard. Follow the step-by-step
   guide to create a Zoom OAuth app at marketplace.zoom.us, then paste your
   **Client ID** and **Client Secret** into the wizard. Click **Save &
   Connect**. Credentials are encrypted at rest on your device.
3. **Connect:** the OAuth consent window opens to Zoom's own sign-in page;
   approve it and the window closes itself.
4. Omniscio immediately starts a first sync in the background. Your meetings
   show up in the panel as soon as it finishes (usually a few seconds).

Zoom's OAuth requires both a PKCE challenge and your app's client secret sent
as a Basic-auth header on every token exchange. That's a Zoom app-type
requirement, not an Omniscio choice. Your refresh token is **encrypted at
rest** on your device and never sent to the renderer/UI process. Zoom also
rotates your refresh token on every use (issues a new one each time); Omniscio
stores the newest one automatically so you never notice.

### What syncs

- **Meetings**: upcoming meetings, plus meetings from the last 30 days
  (topic, start time, duration, timezone, join link, host, and a
  waiting/started/finished status).
- **Cloud recording metadata**, for meetings that have one: file type, file
  size, a play link, and a download link. **Not** the recording's actual
  video/audio content, and **not** a transcript; see Limitations.

Sync is **one-way and read-only**: it pulls from Zoom into a local cache, and
nothing you do inside Omniscio's Zoom panel writes back to Zoom.

**Sync interval:** configurable, 5–120 minutes, default **15 minutes**. A
manual **Sync Now** button is always available for an on-demand refresh.

### Using the panel

- The **Zoom** sidebar row opens a filterable list (**All / Upcoming / Past**
  tabs) of your synced meetings, newest first, with a "Load more" button for
  pagination.
- Clicking a meeting opens its detail: date/time, duration, timezone, status,
  host, a **Join meeting** link (opens in your browser), and any recordings
  (file type, size, and duration, or "Processing…" if Zoom hasn't finished
  processing it yet).
- The gear icon in the panel header opens **Zoom Settings**: connection
  status, **Disconnect** (with a confirmation, since it stops syncing and
  clears your local Zoom data), the sync-interval picker, a **Sync Now**
  button, and a "last synced" timestamp. This settings screen lives inside
  the Zoom panel itself, not on a page in the main Settings menu.

### Limitations (Foundation PR scope)

- **No transcript content.** Only recording *metadata* (type, size, play/
  download links) syncs, not Zoom's AI-generated transcript text.
- **No in-app recording playback.** The play/download links open in your
  browser or Zoom's own app; nothing streams or embeds inside Omniscio.
- **No scheduling or write actions.** You can't create, edit, cancel, or join
  a meeting from Omniscio: this is a read-only mirror.

### Troubleshooting

- **"Zoom API credentials are not configured":** the setup wizard has not
  been completed yet. Open the Zoom sidebar row and follow the wizard to
  enter your Zoom OAuth app's Client ID and Client Secret.
- **Feature not visible:** ensure **Zoom API** is on in Settings → Lab, or
  set `AMC_SHOW_ZOOM_API=1`.
- **No meetings showing:** click **Sync Now**; only the last 30 days of past
  meetings sync, plus anything upcoming.
- **A recording shows "Processing…":** Zoom hasn't finished processing the
  cloud recording yet; it will appear as a normal recording on the next sync
  once Zoom finishes.

## For agents

### Where the data lives

Synced data is mirrored into two local SQLite tables, `zoom_api_meetings` and
`zoom_api_recordings` (both soft-deleted, never hard-deleted, on disconnect;
reconnecting starts a fresh sync). Nothing here is sent anywhere except back
and forth to Zoom's own API (`api.zoom.us`) for the sync itself.

### IPC channels

Twelve channels total, all under the `zoom-api:*` / `zoom-api/*` namespace:

- **Connection:** `zoom-api:auth-status` (read), `zoom-api:connect` (starts
  OAuth), `zoom-api:disconnect` (revokes + wipes local data)
- **Credential setup:** `zoom-api:set-credentials` (save Client ID + Secret),
  `zoom-api:clear-credentials` (remove stored credentials)
- **Browsing (read-only, DB mirror only, no live Zoom call):**
  `zoom-api:list-meetings`, `zoom-api:meeting-detail`,
  `zoom-api:list-recordings`
- **Sync:** `zoom-api:sync-now` (manual trigger), `zoom-api:sync-status`
  (read)
- **Push (fired after a successful sync, no payload; listeners refetch):**
  `zoom-api:meetings-updated`, `zoom-api:recordings-updated`

`connect` / `disconnect` / `set-credentials` / `clear-credentials` /
`sync-now` are desktop-only (blocked from the mobile/web bridge: connecting
opens a real OAuth popup window, credentials are security-sensitive, and
disconnect/sync are credential-bearing or resource-consuming). The five
read-only channels and the two push channels work on the phone client too.

There is no CLI route family for Zoom (unlike, say, Monday.com Cloud). It is
reachable only through the desktop app and, for reads, the mobile/web bridge.

## Related

- [dropbox-integration.md](dropbox-integration.md): another OAuth-connected
  first-party integration (different provider, similar connect/sync shape)
- Contract: `.claude/memory/contracts/zoom-api-contract.md`: the invariants,
  the architecture decisions, and the current wiring gaps in detail