Zoom Phone
Implementation guidance for Zoom Phone integrations across API, webhook/event, Smart Embed, and URI-launch workflows.
Official docs:
The current API Hub inventory contains 391 Phone operations (verified 2026-07-10), including
expanded call-handling/settings coverage and call-element recording/voicemail resources. Use
the generated Phone API reference for exact paths rather than
relying on an older endpoint list in examples.
Routing Guardrail
- If the user needs embedded softphone behavior in a web app, use Smart Embed (examples/smart-embed-postmessage-bridge.md).
- If the user needs call records, analytics, or automation, use Phone REST API and webhooks (references/deprecations-and-migrations.md).
- If the user needs click-to-dial/SMS launch from external UI, use URI schemes (
zoomphonecall://, zoomphonesms://).
- If the user mixes Zoom Phone and Contact Center, chain with ../contact-center/SKILL.md.
Quick Links
Start here:
- concepts/architecture-and-lifecycle.md
- scenarios/high-level-scenarios.md
- references/deprecations-and-migrations.md
- references/forum-top-questions.md
- references/smart-embed-event-contract.md
- references/call-handling-patterns.md
- references/environment-variables.md
- references/crm-sample-validation.md
- troubleshooting/common-issues.md
- RUNBOOK.md
- examples/smart-embed-postmessage-bridge.md
- examples/phone-api-service-pattern.md
- references/source-map.md
Common Lifecycle Pattern
- Provision account prerequisites (Zoom Phone license, admin setup, SMS readiness).
- Create OAuth app and scopes in Marketplace.
- Choose integration surface:
- Smart Embed (iframe + postMessage)
- REST + webhooks
- URI launch (
callto, tel, zoomphonecall, zoomphonesms)
- Capture real-time events (Smart Embed events and/or webhooks).
- Persist call identifiers and correlate records (
call_id, call_history_uuid, call_element_id).
- Apply migration-safe data mapping (v1 -> v2 -> v3) and handle renamed fields.
- Harden security (origin validation, webhook signature validation, least-privilege scopes).
Need to create/configure the Marketplace app first? Use
Marketplace app management for General App or
S2S app setup, admin/user scope selection, event subscription behavior, and credential
response shapes before implementing Phone APIs or Smart Embed workflows. Start from the
General App Phone template or
S2S Phone template.
High-Level Scenarios
- CRM softphone pane using Smart Embed + contact search/match callbacks.
- Click-to-call from account/contact table via
zp-make-call.
- Call disposition workflow using
zp-save-log-event and custom notes page.
- SMS engagement workflow with
zoomphonesms:// and zp-sms-log-event.
- Real-time operational board driven by
phone.* webhook events.
- Call analytics migration from legacy call logs to call history/call elements.
- Admin automation for user/auto-receptionist/call-queue call-handling settings.
See scenarios/high-level-scenarios.md for details.
Chaining
- OAuth setup/token lifecycle: ../oauth/SKILL.md
- Marketplace app creation and manifest validation: ../rest-api/references/marketplace-apps.md
- Phone and account resources via REST: ../rest-api/SKILL.md
- Event delivery and signature validation: ../webhooks/SKILL.md
- Contact Center blended journey: ../contact-center/SKILL.md
Environment Variables
- See references/environment-variables.md for standardized
.env keys and where to find each value.