Back to Details

build-zoom-phone-integration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

/build-zoom-phone-integration

/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:
适用于跨API、webhook、Smart Embed和URI启动工作流的Zoom Phone集成的背景参考。
为跨API、webhook/事件、Smart Embed和URI启动工作流的Zoom Phone集成提供实现指南。
官方文档：

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.
  • 如果用户需要在Web应用中实现嵌入式软电话功能，使用Smart Embed（examples/smart-embed-postmessage-bridge.md）。
  • 如果用户需要通话记录、分析或自动化能力，使用Phone REST API和webhooks（references/deprecations-and-migrations.md）。
  • 如果用户需要从外部UI点击拨号/发送短信，使用URI方案（
    zoomphonecall://
    、
    zoomphonesms://
    ）。
  • 如果用户同时使用Zoom Phone和联络中心，可关联参考../contact-center/SKILL.md。

Quick Links

快速链接

Start here:
  1. concepts/architecture-and-lifecycle.md
  2. scenarios/high-level-scenarios.md
  3. references/deprecations-and-migrations.md
  4. references/forum-top-questions.md
  5. references/smart-embed-event-contract.md
  6. references/call-handling-patterns.md
  7. references/environment-variables.md
  8. references/crm-sample-validation.md
  9. troubleshooting/common-issues.md
  10. RUNBOOK.md
  11. examples/smart-embed-postmessage-bridge.md
  12. examples/phone-api-service-pattern.md
  13. references/source-map.md
从这里开始：
  1. concepts/architecture-and-lifecycle.md
  2. scenarios/high-level-scenarios.md
  3. references/deprecations-and-migrations.md
  4. references/forum-top-questions.md
  5. references/smart-embed-event-contract.md
  6. references/call-handling-patterns.md
  7. references/environment-variables.md
  8. references/crm-sample-validation.md
  9. troubleshooting/common-issues.md
  10. RUNBOOK.md
  11. examples/smart-embed-postmessage-bridge.md
  12. examples/phone-api-service-pattern.md
  13. references/source-map.md

Common Lifecycle Pattern

通用生命周期模式

  1. Provision account prerequisites (Zoom Phone license, admin setup, SMS readiness).
  2. Create OAuth app and scopes in Marketplace.
  3. Choose integration surface:
  • Smart Embed (iframe + postMessage)
  • REST + webhooks
  • URI launch (
    callto
    , 
    tel
    , 
    zoomphonecall
    , 
    zoomphonesms
    )
  1. Capture real-time events (Smart Embed events and/or webhooks).
  2. Persist call identifiers and correlate records (
    call_id
    , 
    call_history_uuid
    , 
    call_element_id
    ).
  3. Apply migration-safe data mapping (v1 -> v2 -> v3) and handle renamed fields.
  4. Harden security (origin validation, webhook signature validation, least-privilege scopes).
  1. 准备账户前置条件（Zoom Phone许可证、管理员设置、短信可用配置）。
  2. 在市场中创建OAuth应用并配置权限范围。
  3. 选择集成载体：
  • Smart Embed（iframe + postMessage）
  • REST + webhooks
  • URI启动（
    callto
    、
    tel
    、
    zoomphonecall
    、
    zoomphonesms
    ）
  1. 捕获实时事件（Smart Embed事件和/或webhooks）。
  2. 持久化通话标识符并关联记录（
    call_id
    、
    call_history_uuid
    、
    call_element_id
    ）。
  3. 应用兼容迁移的数据映射（v1 -> v2 -> v3）并处理重命名字段。
  4. 强化安全性（来源验证、webhook签名验证、最小权限范围）。

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.
  • 使用Smart Embed + 联系人搜索/匹配回调实现CRM软电话面板。
  • 通过
    zp-make-call
    从账户/联系人表实现点击拨号。
  • 使用
    zp-save-log-event
    和自定义备注页面实现通话处理结果工作流。
  • 结合
    zoomphonesms://
    和
    zp-sms-log-event
    实现短信互动工作流。
  • 由
    phone.*
    webhook事件驱动的实时运营看板。
  • 从旧版通话日志到通话历史/通话元素的通话分析迁移。
  • 用户/自动前台/呼叫队列通话处理设置的管理员自动化。
详见scenarios/high-level-scenarios.md了解详情。

Chaining

关联参考

  • OAuth setup/token lifecycle: ../oauth/SKILL.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
  • OAuth设置/令牌生命周期：../oauth/SKILL.md
  • 基于REST的电话和账户资源：../rest-api/SKILL.md
  • 事件投递和签名验证：../webhooks/SKILL.md
  • 联络中心混合流程：../contact-center/SKILL.md

Environment Variables

环境变量

  • See references/environment-variables.md for standardized 
    .env
    keys and where to find each value.
  • 查看references/environment-variables.md了解标准
    .env
    键名以及各个值的获取位置。