Build Zoom Phone Integration

# Zoom Phone Architecture and Lifecycle

## Architecture

```text
User/Agent UI
  |
  | (A) Smart Embed postMessage events
  v
Smart Embed Iframe (applications.zoom.us)
  |
  | event stream + call controls
  v
CRM Web App (event bridge + UI state)
  |
  | OAuth token on server only
  v
Backend API Layer
  |\
  | \-- Zoom Phone REST APIs (call history, call handling, contacts)
  |
  \---- Webhook endpoint (phone.* events)
```

## Lifecycle Workflow

1. Provision:
- Account has Zoom Phone and optional SMS enablement.

2. Authorize:
- OAuth app installed and scoped for required Phone operations.

3. Initialize UI:
- Load Smart Embed iframe/script.
- Wait for `onZoomPhoneIframeApiReady`.
- Send `zp-init-config` and register event handlers.

4. Engage:
- Start calls/SMS via `zp-make-call` or `zp-input-sms`.
- Receive events (`zp-call-*`, `zp-sms-log-event`, optional AI/contact/notes events).

5. Persist:
- Save event snapshots keyed by `callId`.
- Reconcile to call history/call element records after completion.

6. Post-call:
- Save call notes/disposition and optional recording/voicemail links.

7. Operate:
- Track deprecations and apply endpoint/event mapping updates.

## Version Drift Strategy

- Normalize inbound payloads in one adapter layer.
- Keep endpoint constants centralized by version target.
- Feature-flag optional payload fields.
- Keep webhook + Smart Embed event handlers tolerant to added fields and enum expansion.


# Phone API Service Pattern (Migration-Safe)

## Pattern goals

- Isolate OAuth token usage to server code.
- Support current call history/call element model.
- Keep compatibility with old payload fields while migrating.

## Service example

```javascript
export async function getCallHistory(accessToken, from, to) {
  const qs = new URLSearchParams({ from, to }).toString();
  const res = await fetch(`https://api.zoom.us/v2/phone/call_history?${qs}`, {
    headers: { Authorization: `Bearer ${accessToken}` },
  });
  if (!res.ok) throw new Error(`call_history failed: ${res.status}`);

  const data = await res.json();

  // Normalize v2/v3 style for downstream code.
  return (data.call_history || data.call_logs || []).map((row) => ({
    callHistoryUuid: row.call_history_uuid || row.id,
    callId: row.call_id,
    raw: row,
  }));
}

export async function getCallElement(accessToken, callElementId) {
  const res = await fetch(`https://api.zoom.us/v2/phone/call_element/${callElementId}`, {
    headers: { Authorization: `Bearer ${accessToken}` },
  });
  if (!res.ok) throw new Error(`call_element failed: ${res.status}`);
  return res.json();
}
```

## Operational notes

- Add explicit logging when fallback fields (`call_logs`, `call_path`) are encountered.
- Remove fallback path once migration is complete.


# Smart Embed postMessage Bridge Pattern

## Why this pattern

Smart Embed event/control flow is `window.postMessage` based. Reliability depends on strict initialization order and origin validation.

## Pattern

```javascript
const ZOOM_ORIGIN = 'https://applications.zoom.us';
const iframe = document.querySelector('#zoom-embeddable-phone-iframe');

function initSmartEmbed(config) {
  iframe?.contentWindow?.postMessage({
    type: 'zp-init-config',
    data: config,
  }, ZOOM_ORIGIN);
}

function makeCall(number, callerId) {
  iframe?.contentWindow?.postMessage({
    type: 'zp-make-call',
    data: { number, callerId, autoDial: true },
  }, ZOOM_ORIGIN);
}

window.addEventListener('message', (event) => {
  if (event.origin !== ZOOM_ORIGIN) return;
  const payload = event.data;
  if (!payload?.type) return;

  switch (payload.type) {
    case 'zp-call-ringing-event':
    case 'zp-call-connected-event':
    case 'zp-call-ended-event':
    case 'zp-call-log-completed-event':
      handlePhoneEvent(payload);
      break;
    default:
      break;
  }
});
```

## Operational notes

- Call APIs only after iframe readiness callback.
- Persist `event.id` (if present) for idempotency.
- Keep event dispatcher toleran