build-zoom-phone-integration

/build-zoom-phone-integration

Zoom Phone 集成的背景参考，涵盖 API、Webhook、Smart Embed 和 URI 启动工作流。

Zoom Phone 集成的实现指南，涵盖 API、Webhook/事件、Smart Embed 和 URI 启动工作流。

官方文档：

• https://developers.zoom.us/docs/phone/
• CRM 示例参考：https://github.com/zoom/CRM-Sample

路由准则

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

通用生命周期模式

1. 准备账户前提条件（Zoom Phone 许可证、管理员设置、短信就绪）。
2. 在 Marketplace 中创建 OAuth 应用并配置权限范围。
3. 选择集成方式：

• Smart Embed（iframe + postMessage）
• REST + Webhook
• URI 启动（callto、tel、zoomphonecall、zoomphonesms）

4. 捕获实时事件（Smart Embed 事件和/或 Webhook）。
5. 持久化通话标识符并关联记录（call_id、call_history_uuid、call_element_id）。
6. 应用迁移安全的数据映射（v1 -> v2 -> v3），并处理重命名的字段。
7. 加强安全性（来源验证、Webhook 签名验证、最小权限原则的权限范围）。

高级场景

• 使用 Smart Embed 和联系人搜索/匹配回调的 CRM 软电话面板。
• 通过 zp-make-call 从客户或联系人表格中点击拨打电话。
• 使用 zp-save-log-event 和自定义备注页面的通话处置工作流。
• 使用 zoomphonesms:// 和 zp-sms-log-event 的短信互动工作流。
• 由 phone.* Webhook 事件驱动的实时运营看板。
• 从旧版通话日志迁移到通话历史/通话元素的通话分析。
• 用户/自动接待员/呼叫队列通话处理设置的管理员自动化。

详情请参阅 scenarios/high-level-scenarios.md。

串联

• OAuth 设置与令牌生命周期：../oauth/SKILL.md
• 通过 REST 访问电话和账户资源：../rest-api/SKILL.md
• 事件投递与签名验证：../webhooks/SKILL.md
• Contact Center 融合旅程：../contact-center/SKILL.md

环境变量

• 标准化 .env 键及各值的获取位置，请参阅 references/environment-variables.md。