Embed an IllyVoIP SDK phone in an authorized iframe

You can embed a phone application you control in an authorized iframe. The embedded page runs your IllyVoIP SDK integration; this does not promise that the hosted Portal or every third-party CRM permits framing. Start by agreeing which parent and phone origins are trusted.

Start with the official IllyVoIP Webphone SDK 1.4.2 bundle and one managed phone owner. Your backend must authorize the signed-in user’s SIP identity and issue the short-lived browser token. The examples extend your application; they do not change the hosted Portal phone.

1. Allow the intended frame and microphone

Both pages need a secure deployment. The parent’s framing policy must allow the phone origin, and the phone page’s frame-ancestors policy must permit the parent. Review any X-Frame-Options header too. Separately, delegate microphone use through the parent’s Permissions Policy and the iframe attribute.

Permissions-Policy: microphone=(self "https://phone.example.com")

<iframe
  src="https://phone.example.com/dialer"
  title="Customer calling phone"
  allow="microphone https://phone.example.com">
</iframe>

These are fictional origins to replace with your own controlled deployment. A restrictive ancestor policy cannot be relaxed by adding an iframe attribute below it. Delegation also does not grant the user’s microphone permission. If your host requires sandboxing, review its restrictions deliberately; do not copy permissive sandbox flags without understanding the trust boundary.

2. Authenticate inside the phone application

Bind the token endpoint to a verified application session and server-authorized SIP identity. Never put an API key, SIP password or browser token in the iframe URL. The official backend proxy example deliberately rejects browser-supplied SIP identity claims unless your authenticated server has established the principal.

Embedded storage and cookies behave differently across browsers and settings. Test the actual login design in the intended host. If it cannot establish a valid session, display a clear sign-in or open-in-own-window path instead of making the token endpoint public or weakening its authorization.

3. Keep the message bridge small

If the parent needs to focus a reviewed customer record, validate both the message origin and source window. Treat the record reference as untrusted input and resolve access on the phone application’s backend. Do not accept arbitrary “dial this number” messages from any origin.

const parentOrigin = 'https://crm.example.com';
window.addEventListener('message', event => {
  if (event.origin !== parentOrigin || event.source !== window.parent) return;
  const value = event.data;
  if (!value || value.type !== 'select-contact') return;
  if (typeof value.contactId !== 'string' || value.contactId.length > 100) return;
  // Resolve this reference through the authenticated backend.
  // Show the destination and require a deliberate Call action.
});

When sending a response, use the exact parent origin as the target, not a wildcard. Keep secrets and full customer records out of the message channel. A trusted origin check does not replace per-contact authorization.

4. Enable calling through the embedded UI

1. Create one SDK owner after the authenticated application is ready.
2. Offer an explicit Enable phone action and handle microphone denial.
3. Keep incoming-call, mute and end controls visible and keyboard reachable.
4. On logout or identity change, block new actions and await orderly cleanup.

Do not destroy and recreate the phone whenever the parent changes a customer tab. Conversely, removing the frame can interrupt the phone owner; coordinate that action with your active-call policy.

5. Test the real browser boundary

Test permitted and denied microphone policy, a rejected parent origin, malformed messages, expired login, blocked storage and removal of the frame. A local mocked phone can validate your bridge before any call. Then use an authorized call in each target browser to verify registration and two-way audio. Successful frame loading alone proves neither.

Related guides

• Add browser calling with the Webphone SDK
• Manage the IllyVoIP WebRTC Phone SDK lifecycle in React
• Troubleshoot the webphone

Reference

Current instructions and technical reference: MDN: Permissions Policy, MDN: cross-window messaging, MDN: microphone access.

Reviewed 13 October 2026 against the current IllyVoIP controls, implementation and applicable references. Available options depend on account permissions and service state.