build-zoom-phone-integration

anthropics/knowledge-work-plugins

Reference skill for building Zoom Phone integrations via OAuth, APIs, webhooks, Smart Embed, and URI schemes.

What is build-zoom-phone-integration?

Guidance for integrating Zoom Phone into web apps and workflows. Use this when implementing embedded softphone UIs, call automation, CRM dialers, webhooks, or click-to-call/SMS features. Covers OAuth setup, Smart Embed iframe patterns, REST API call handling, and real-time event processing.

Route integration requests to Smart Embed (embedded softphone), REST API (call records/automation), or URI schemes (click-to-dial/SMS)
Implement OAuth and token lifecycle for Zoom Phone authentication
Build Smart Embed postMessage bridges for iframe communication and event capture
Handle phone webhooks and real-time call/SMS events with signature validation
Map call identifiers and correlate records across API versions (v1→v2→v3)
Support CRM/CTI dialer workflows and call disposition logging

How to install build-zoom-phone-integration

npx skills add https://github.com/anthropics/knowledge-work-plugins --skill build-zoom-phone-integration

Prerequisites

Zoom Phone license and admin account setup
OAuth app created in Zoom Marketplace with appropriate scopes
Webhook endpoint or Smart Embed iframe ready to receive events
Understanding of postMessage for iframe communication (if using Smart Embed)

Claude Code

Cursor

Windsurf

Cline

How to use build-zoom-phone-integration

1.Review architecture and lifecycle in concepts/architecture-and-lifecycle.md
2.Choose your integration surface: Smart Embed, REST API, or URI schemes based on use case
3.Set up OAuth and configure scopes in Zoom Marketplace
4.Implement the chosen pattern: Smart Embed postMessage bridge, REST API service, or URI launch handler
5.Capture and validate real-time events (Smart Embed events or webhook signatures)
6.Map call identifiers and persist records with migration-safe field mapping
7.Test security: origin validation, webhook signature validation, least-privilege scopes
8.Deploy and monitor using the RUNBOOK and troubleshooting guides

Use cases

Good for

Embed a softphone pane in a CRM contact record with click-to-call and call history
Automate call disposition and SMS logging via webhooks in a contact center workflow
Launch click-to-dial from an external UI using zoomphonecall:// URI scheme
Build a real-time operational dashboard driven by phone.* webhook events
Migrate legacy call logs to Zoom Phone call history and call elements API

Who it's for

Backend engineers building Zoom Phone integrations
Frontend developers embedding Zoom Phone softphone in web apps
CRM/contact-center platform teams
Integration architects designing phone workflow automation

build-zoom-phone-integration FAQ

When should I use Smart Embed vs. REST API vs. URI schemes?

Use Smart Embed for embedded softphone UI in a web app (iframe + postMessage). Use REST API and webhooks for call records, analytics, and automation. Use URI schemes (zoomphonecall://, zoomphonesms://) for click-to-dial/SMS launch from external UI.

How do I handle OAuth token refresh and scope management?

Follow the OAuth skill chain reference for token lifecycle. Ensure your Marketplace app has the required scopes (e.g., phone:read, phone:write, phone_sms:read). Store and refresh tokens securely.

What is the difference between call_id, call_history_uuid, and call_element_id?

call_id is used in real-time Smart Embed events, call_history_uuid in call history API responses, and call_element_id in call elements API. Map these identifiers carefully when correlating records across API versions.

How do I validate webhook signatures and ensure security?

Validate webhook signatures using the shared secret from your Marketplace app. Check origin headers for Smart Embed postMessage. Use least-privilege OAuth scopes and validate all inputs.

What migration steps are needed when upgrading from v1 to v3 APIs?

Review references/deprecations-and-migrations.md for field renames and API changes. Test data mapping with the CRM sample reference. Validate call records and event contracts before production deployment.

Full instructions (SKILL.md)

Source of truth, from anthropics/knowledge-work-plugins.

name: build-zoom-phone-integration description: "Reference skill for Zoom Phone. Use after routing to a phone workflow when implementing OAuth, Phone APIs, webhooks, Smart Embed events, URI schemes, CRM or CTI dialers, or call handling automation." triggers:

"zoom phone"
"phone smart embed"
"zoom phone api"
"zoom phone webhook"
"call history"
"call handling"
"zoomphonecall"
"zoomphonesms"
"phone crm integration"
"call element"

/build-zoom-phone-integration

Background reference for Zoom Phone integrations across API, webhook, Smart Embed, and URI-launch workflows.

Implementation guidance for Zoom Phone integrations across API, webhook/event, Smart Embed, and URI-launch workflows.

Official docs:

https://developers.zoom.us/docs/phone/
CRM sample reference: https://github.com/zoom/CRM-Sample

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:

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).