Build a compact panel in your CRM so agents can handle engagements and control voice calls without switching windows. You host and maintain the CRM panel and the messaging code that connects it to Smart Embed. The full softphone stays in a separate Smart Embed window.
Warning
This implementation supports one CRM or web application tab paired with one Smart Embed window. Don't use multiple CRM tabs to control the same Smart Embed instance.
Your application must enforce this restriction.
Prerequisites
You must have the following before you can implement the CRM panel.
- A Contact Center license and administrator access to configure the Smart Embed integration.
- A CRM or web application that supports this integration.
- HTTPS hosting for your CRM and popup page. Both pages must share an origin, meaning the same scheme, hostname, and port.
- The Smart Embed iframe code from Getting Started with Smart Embed, with its
sandboxandallowattributes, placed on your popup page. If your company uses SSO, apply the vanity URL change described there.
Design for the agent workflow
Design the CRM panel so agents can work from the CRM for common actions, and open the Smart Embed window only when they need the rest.
Warning
Keep the Smart Embed window open. Closing or reloading it removes or reloads the embedded softphone and can interrupt service.
- Add an Open Contact Center button to the CRM. Agents sign in to Smart Embed through the window it opens.
- Put engagement alerts, accept and reject, voice dialing, and the other controls you implement in the CRM panel.
- Expect agents to open the Smart Embed window directly for video interactions, AI Expert Assist where available, and other features the CRM panel doesn't provide.
- A minimized Smart Embed window must keep running, so test background behavior before you deploy.
Controls the CRM panel can send
Your CRM panel can send these controls to Smart Embed. Available controls depend on what's happening in the engagement and on your Contact Center configuration. Completing a warm transfer or merging a conference also requires the appropriate consult state. For each event's payload, see the Event Reference.
| CRM control | Applies to | Smart Embed event |
|---|---|---|
| Accept, reject, or end | Voice, video, chat, SMS | zcc-accept-engagement / zcc-reject-engagement / zcc-terminate-engagement |
| Dial | Voice | onclicktoact |
| In-call keypad | Voice | zcc-send-dtmf |
| Mute or hold | Voice | zcc-set-mute / zcc-set-hold |
| Start or complete transfer | Voice | zcc-transfer-engagement / zcc-complete-transfer |
| Add call or merge conference | Voice | zcc-add-call / zcc-merge-consult |
| Pause, resume, or stop recording | Voice | zcc-set-recording |
| Change agent status | Agent | zcc-agent-status-set-request |
| Set disposition or finish wrap-up | Voice, video, chat, SMS | zcc-set-engagement-disposition / zcc-close-engagement-wrapup |
Set up the integration
To connect the CRM panel to Smart Embed, complete these steps in order.
- Create the popup page. Host a page such as
zcc-popup.htmlon the same origin as your CRM. Add Smart Embed to the page, and set the iframe URL'soriginparameter to the popup's origin. For the iframe code, see Add Smart Embed to your web app. - Open or reuse the window. Call
window.open()from the agent's button click, and handle popup blocking. If the existing window is available, focus it without navigating or reloading it. - Connect the CRM and popup pages. Create a session-specific
BroadcastChannelin both the CRM and the popup page. Both must share an origin and storage partition. Add checks that prevent a second CRM tab, including a duplicated tab, from taking control. A channel name alone doesn't enforce this restriction. - Relay messages securely. The popup page forwards CRM commands to the Zoom iframe with
iframe.contentWindow.postMessage(), then relays Zoom events back throughBroadcastChannel. Validate message structure, session IDs, and allowed commands. For messages from Zoom, check bothevent.originand the iframe'sevent.source. Send commands to the exact expected Zoom origin, not"*". - Build the CRM panel. Display connection status, agent status, incoming engagements, and controls for the selected engagement. Track each engagement by ID and channel. Enable each button only when its action is valid.
- Initialize and confirm results. Respond to
zcc-init-config-requestwithzcc-init-config-response. Follow the required payload for each command. Thezcc-accept-engagement,zcc-reject-engagement, andzcc-terminate-engagementevents requireengagementId,channelType, and a unique 128-bit UUIDrequestId. Use Zoom responses, notifications, and errors to confirm outcomes. A sent command doesn't prove that it succeeded. - Recover after a refresh. Disable controls when the relay is unavailable. After the CRM refreshes, reconnect to the existing Smart Embed window, and request the current agent status and each engagement's status.
Test the integration
Test these scenarios before you deploy the CRM panel.
- Close the Smart Embed window.
- Block popups in the browser.
- Keep the CRM in the background while Smart Embed runs.
- Test microphone and camera access.
- Handle multiple engagements at once.
- Open a duplicate CRM tab.