@opencx/voice

OpenCX app voice calling for JavaScript and TypeScript. Opt-in preview; organization access and the matching backend deployment are required.

The npm installation/build tooling requires Node.js 22.22 or later. The script-tag bundle below runs directly in a modern browser and requires no Node.js installation or build step in your application.

import { OpenCXVoice } from '@opencx/voice';
const voice = new OpenCXVoice({
  getToken: async ({ requestId, signal }) => {
    const response = await fetch('/api/support/voice-token', {
      method: 'POST', headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ requestId }), signal,
    });
    if (!response.ok) throw new Error('Unable to start a support call');
    return response.json();
  },
});
voice.on('stateChanged', state => console.log(state));
voice.on('error', error => console.error(error.message));
await voice.start();
await voice.setMuted(true);
await voice.end();
await voice.dispose();

Your authenticated server calls POST /phone/web-calls with a phone:write API key, a verified contactId, an authorized destination ({ type: 'agent' | 'team', id }), and the requestId. Return the response (callId, sessionId, controlToken, expiresAt) to that customer only, and pass it unchanged to the SDK. Audio connection setup is handled internally; applications should use only OpenCX methods, states, and VoiceError values. Never embed the permanent API key in client code. Do not log or persist call credentials.

The SDK also exposes setMicrophone, setAudioOutput, setSpeakerEnabled, and resumeAudio. Audio output selection depends on browser support. Connect from a user gesture over HTTPS; offer a Resume audio button if playback is blocked. End or dispose when the owning screen is removed.

See the Voice SDK integration guide in the accompanying release documentation for native packages, routing, and limitations. This package starts customer-initiated calls; it does not implement incoming-call notifications.

Update preview SDK and backend versions together. Earlier preview audio connection fields are no longer returned by call creation; remove any direct audio connection setup in the application.

Plain HTML and server-rendered apps

Starting with version 0.2.0, the package includes dist/opencx-voice.min.js. Copy it and dist/opencx-voice.min.js.LEGAL.txt to your site's /scripts/ directory. Load the SDK before your integration code:

<script defer src="/scripts/opencx-voice.min.js"></script>
<script defer src="/scripts/support-calling.js"></script>

In support-calling.js, use new OpenCXVoice.OpenCXVoice({ getToken }) with the same getToken callback shown above. OpenCXVoice.VoiceError is also available. Call start() from a button click; handle rejected calls and the error event. This provides calling methods, not a prebuilt interface. The script-tag example in the source distribution demonstrates call, mute, resume-audio and hangup controls. Your authenticated server can use any language. It must validate the customer, apply your app's CSRF protection, choose the contact and destination, and return only that call's credentials with Cache-Control: no-store.

You can also load the exact released version from https://cdn.jsdelivr.net/npm/@opencx/[email protected]/dist/opencx-voice.min.js. This URL works only after that version is published. Avoid floating latest URLs. For a CDN script, copy the SHA-384 value from that same version's dist/browser-integrity.json into the script's integrity attribute and add crossorigin="anonymous". Self-hosting avoids an external script dependency. Retain the accompanying legal notices when redistributing the bundle.

Use HTTPS (localhost is allowed for development) and a modern browser with microphone and real-time audio support. This does not add support for obsolete browsers. The script needs neither module loading nor unsafe-eval. With a Content Security Policy, allow the script source, your server's credential route, the OpenCX API, and the audio connection endpoints supplied for your integration. Do not loosen your policy globally. Embedded frames also require microphone permission from their parent page. Playback may require a Resume audio button.

Maintainers: pnpm build produces both module and browser builds. Run browser checks against a packed tarball using VOICE_PACKAGE_TARBALL=/absolute/path/to/package.tgz pnpm test:package and the same variable with pnpm test:browser. Install the test browsers first with pnpm exec playwright install chromium firefox webkit.