Zoom Meeting ExecModule

Overview

ZoomMeetingModule creates, reads, lists, updates, and deletes Zoom meetings through the Zoom API v2. Version 2.0 replaces the duplicate simulated connector with one discoverable implementation that uses a READY IntegrationAccount, bounded HTTP transport, safe-read retries, single-attempt writes, explicit delete confirmation, complete Workflow Studio metadata, and secret-safe failures.

The canonical module identifier is:

com.valkyrlabs.workflow.modules.social.ZoomMeetingModule

The former ZoomExecModule remains loadable only for saved-workflow compatibility. It is hidden from discovery and returns MODULE_RETIRED without contacting Zoom or fabricating meeting identifiers.

Usage

1. Create a least-privilege Zoom OAuth application with only the meeting scopes required by the workflow.
2. Store its current OAuth access token in the apiKey SecureField of a READY Zoom IntegrationAccount. Set accountId to the intended Zoom user ID, or omit it to use me.
3. Bind that account as zoomAccount; do not place tokens or provider URLs in workflow input.
4. Choose one operation and provide only the fields that operation needs.
5. Treat a write as successful only when status is success. Reconcile Zoom before retrying any AMBIGUOUS_WRITE result.

Inputs

Input	Required	Description
operation	Yes	create_meeting, get_meeting, list_meetings, update_meeting, or delete_meeting.
userId	Create/list	Zoom user identifier; defaults to me. If accountId is set, the two must match.
meetingId	Get/update/delete	Numeric Zoom meeting identifier with 9–13 digits.
topic	Create	Topic from 1 through 200 characters; optional for update.
meetingType	No	Zoom type 1, 2, 3, or 8; default 2.
startTime	No	RFC3339 timestamp.
duration	No	1–1,440 minutes; default 60.
timezone	No	Valid IANA timezone; default UTC.
agenda	No	Agenda capped at 2,000 characters.
password	No	Meeting passcode sent to Zoom but never returned.
settings	No	Allowlisted settings: host/participant video, join-before-host, waiting room, mute-on-entry, authentication, and automatic recording.
pageSize	List	1–100 meetings per request; default 30.
maxPages	List	1–10 pages followed in one execution; default 1.
nextPageToken	List	Opaque continuation token returned by Zoom.
confirmDelete	Delete	Must be exactly true before a delete request is sent.

Raw access tokens, API keys, secrets, provider URLs, mock switches, and test switches are rejected before transport.

Outputs

Output	Description
status	success or error.
operation	Normalized operation name.
data	Allowlisted meeting fields for a single-resource success.
items	Bounded allowlisted meeting collection for list operations.
meetingId	Created, read, updated, or deleted meeting ID.
joinUrl	Participant join URL when Zoom returns one.
count	Number of meetings returned by a list operation.
nextPageToken	Opaque token when another page remains.
attempts	Provider attempts consumed.
error	Safe code, message, optional httpStatus, retryable, and reconciliation guidance.

Host start_url values, meeting passcodes, OAuth tokens, raw authorization headers, and raw provider error bodies are never emitted.

IntegrationAccount Requirements

Bind a Zoom IntegrationAccount with:

• status exactly READY;
• a current OAuth access token in apiKey;
• accountId set to the intended Zoom user ID, or blank to use me;
• the minimum Zoom meeting scopes required for the selected operations.

OAuth refresh is intentionally outside this module. Refresh an expired token through the account lifecycle before executing the workflow. The module rejects caller-supplied credentials and cannot redirect the token away from https://api.zoom.us/v2.

Configuration

Configuration	Default	Constraint
zoomAccount	None	Required READY IntegrationAccount.
operation	None	Required allowlisted operation.
listType	scheduled	scheduled, live, or upcoming.
pageSize	30	1–100.
maxPages	1	1–10.
safeReadRetries	1	0–2 retries for GET requests only.
timeoutMs	30000	Per-request timeout from 1,000–60,000 ms.
maxRetryDelayMs	250	Maximum safe-read delay from 0–5,000 ms.
confirmDelete	false	Must be true for deletion.

Request JSON is capped at 100 KB, response JSON at 2 MB, redirects are disabled, and list execution follows at most ten pages.

Operations

Operation	Zoom API v2 request	Side effect
create_meeting	POST /users/{userId}/meetings	Creates one meeting.
get_meeting	GET /meetings/{meetingId}	Read only.
list_meetings	GET /users/{userId}/meetings	Read only; bounded pagination.
update_meeting	PATCH /meetings/{meetingId}	Updates one meeting.
delete_meeting	DELETE /meetings/{meetingId}	Deletes one meeting after confirmation.

GET requests can retry transient network errors, HTTP 429, and HTTP 5xx within configured bounds. POST, PATCH, and DELETE requests are sent once and are never retried automatically.

Errors and Failure Modes

Code	Meaning	Recovery
VALIDATION_ERROR	An identifier, timestamp, timezone, payload, page limit, raw credential, or safety guard is invalid.	Correct the named input; no provider request was sent.
INTEGRATION_ACCOUNT_REQUIRED	No Zoom account is bound.	Bind the intended Zoom account.
INTEGRATION_ACCOUNT_NOT_READY	The bound account is not READY.	Repair or refresh the account before execution.
CREDENTIAL_MISSING	The account has no OAuth access token.	Store a current token in apiKey.
ZOOM_API_<status>	A bounded provider response rejected a safe read or a known non-transient write.	Correct permissions, token state, identifier, or input before retrying.
NETWORK_ERROR	A read exhausted its bounded retry policy.	Check Zoom and network health, then retry if appropriate.
AMBIGUOUS_WRITE	A write encountered a transient response or network failure after it may have reached Zoom.	Reconcile Zoom state first; do not retry blindly.
INVALID_PROVIDER_RESPONSE	Zoom returned a successful but structurally unusable response.	Preserve the safe receipt and investigate provider/schema drift.

Example

Create a scheduled meeting for the OAuth token user:

{
  "operation": "create_meeting",
  "userId": "me",
  "topic": "Customer onboarding",
  "startTime": "2030-08-12T17:00:00Z",
  "duration": 45,
  "timezone": "America/Los_Angeles",
  "settings": {
    "waiting_room": true,
    "mute_upon_entry": true
  }
}

Expected safe shape:

{
  "status": "success",
  "operation": "create_meeting",
  "meetingId": "12345678901",
  "joinUrl": "https://example.zoom.us/j/12345678901",
  "attempts": 1
}

Notes

• Zoom supports me for the create/list meeting routes when the access token represents the intended user.
• Access-token issuance and refresh remain account-management responsibilities; the module only consumes a current token.
• Participant join URLs may be shared according to workflow policy. Host start URLs are privileged and deliberately excluded.
• Create, update, and delete are not idempotent at the workflow boundary. A timed-out or disconnected write can be ambiguous even when no success body was received.
• The deterministic suite uses MockWebServer, not live Zoom credentials. It verifies exact routes, bearer authentication, payload allowlists, pagination, read-only retries, single-attempt writes, delete confirmation, redaction, account state, duplicate retirement, discovery, and metadata. Live OAuth scopes and Zoom tenant policy remain deployment-time boundaries.
• Zoom API references: authentication, API overview, OAuth, and meeting APIs.