/build-zoom-phone-integration

Documentation de référence pour les intégrations Zoom Phone sur les workflows API, webhook, Smart Embed et URI-launch.

Guidance d'implémentation pour les intégrations Zoom Phone sur les workflows API, webhook/event, Smart Embed et URI-launch.

Documentation officielle :

• https://developers.zoom.us/docs/phone/
• Référence d'exemple CRM : https://github.com/zoom/CRM-Sample

Routing Guardrail

• Si l'utilisateur a besoin d'un comportement softphone embarqué dans une web app, utilisez Smart Embed (examples/smart-embed-postmessage-bridge.md).
• Si l'utilisateur a besoin de dossiers d'appels, d'analytics ou d'automatisation, utilisez Phone REST API et webhooks (references/deprecations-and-migrations.md).
• Si l'utilisateur a besoin de click-to-dial/SMS launch depuis une UI externe, utilisez les schémas URI (zoomphonecall://, zoomphonesms://).
• Si l'utilisateur mélange Zoom Phone et Contact Center, chaînez avec ../contact-center/SKILL.md.

Quick Links

Commencez ici :

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. Provisionner les prérequis du compte (licence Zoom Phone, setup admin, préparation SMS).
2. Créer une OAuth app et les scopes dans Marketplace.
3. Choisir la surface d'intégration :

• Smart Embed (iframe + postMessage)
• REST + webhooks
• URI launch (callto, tel, zoomphonecall, zoomphonesms)

4. Capturer les événements en temps réel (événements Smart Embed et/ou webhooks).
5. Persister les identifiants d'appel et corréler les dossiers (call_id, call_history_uuid, call_element_id).
6. Appliquer un data mapping sûr pour la migration (v1 -> v2 -> v3) et gérer les champs renommés.
7. Renforcer la sécurité (validation de l'origine, validation de la signature webhook, scopes au minimum des privilèges).

High-Level Scenarios

• Pane softphone CRM utilisant Smart Embed + callbacks de recherche/match de contacts.
• Click-to-call depuis un tableau de comptes/contacts via zp-make-call.
• Workflow de disposition d'appel utilisant zp-save-log-event et une page de notes personnalisées.
• Workflow d'engagement SMS avec zoomphonesms:// et zp-sms-log-event.
• Tableau opérationnel en temps réel piloté par les événements webhook phone.*.
• Migration d'analytics d'appel des anciens journaux d'appels vers l'historique d'appels/éléments d'appel.
• Automatisation admin pour les paramètres de gestion des appels utilisateur/réceptionniste automatique/file d'attente d'appels.

Voir scenarios/high-level-scenarios.md pour plus de détails.

Chaining

• Setup OAuth/cycle de vie du token : ../oauth/SKILL.md
• Ressources Phone et account via REST : ../rest-api/SKILL.md
• Livraison d'événements et validation de signature : ../webhooks/SKILL.md
• Parcours blended Contact Center : ../contact-center/SKILL.md

Environment Variables

• Voir references/environment-variables.md pour les clés .env standardisées et où trouver chaque valeur.