Integrations/Embedding Voiger
Integrations

Embedding Voiger

Put the Voiger dialer inside your CRM as an iframe, complete the handshake, and start receiving call and conversation events.

Voiger embeds as an iframe and talks to the surrounding page over window.postMessage. Your CRM never handles Voiger credentials — the embedded app carries the agent's own session, and the bridge exposes only what you ask for.

There are three things to get right: the frame itself, the origin checks on both sides, and the handshake. Everything after that is the protocol.

The dialer is a frame you position wherever it suits your layout — a corner, a side panel, a drawer. Your application keeps the rest of the page.

Why embed rather than build direct#

The bridge is not the only way in. The Admin and Agent APIs are documented, and Voiger speaks standard SIP over WebRTC, so a softphone of your own is possible. The difference is how much telephony you have to know, and how much of it you have to build.

Embedding is a frame, an origin check, and a handful of JSON messages. Everything on the left of this table is work you do not do.

Concern
Building direct
Embedded
Skills needed
SIP, SDP, WebRTC, ICE, codecs, browser media APIs
JavaScript and postMessage
Media and signalling
registration over WebSocket, ICE and STUN, codec negotiation, device selection, recovery when a device disappears mid-call
handled
One registration per agent
your CRM open in three tabs must not register three times or contend for the microphone
leader elected across tabs
Call control
hold, blind transfer, attended transfer, consultation, DTMF, wrap-up — each a SIP flow with its own edge cases
four commands
Call correlation
correlation headers and masked-number resolution decide routing and reporting
handled
Live data
conversations, activities, agent and queue state, with cross-tab caching and resync
subscribe and receive
Credentials
your page holds a Voiger session, and any bug in your code can leak it
the agent signs in inside the frame; your page holds nothing
Dialer UI
you design and build it
shipped, and it stays current

A working embedded integration is a day's work for a web developer with no telephony background. A direct softphone is a project, and one where the hard part is not the first call but everything after it — a device unplugged mid-conversation, a transfer that half-completes, an agent who reloads the tab while on a call.

The errors also differ in kind. A wrong correlation header does not raise an exception; it produces a call with the wrong caller ID, or one that never appears in reporting. Those are the failures you find in a customer complaint rather than in a stack trace.

When building direct is the right call#

No audio involved. Reporting, bulk contact sync, provisioning — reach for

the REST APIs. The bridge exists for the live call surface, not for data at rest.

Not a browser. Native mobile or desktop clients cannot embed the frame.
A dialer UI you fully control. If the shipped dialer cannot be made to fit,

a direct build is the honest answer.

Call flows the bridge does not expose. Check

the protocol first — the surface grows.

These are not exclusive. Embedding for the call surface and using the REST APIs for reporting and bulk work is the common shape, and the two share the same session.

1 · Embed the frame#

The dialer needs microphone access to place calls, so the iframe must carry an allow attribute. Without it the agent can join a call but will have no audio path, and the failure is silent.

html
<iframe
  id="voiger-iframe"
  src="https://app.voiger.io/?dialerMode=true"
  allow="microphone"
  style="width: 420px; height: 620px; border: 0;"
></iframe>
allow="microphone" is required. Permissions-Policy blocks getUserMedia inside a cross-origin frame otherwise, and the dialer reports a device error rather than a permissions one.

dialerMode=true opens the dialer-only layout: the dialer fills the frame, an incoming call does not switch the frame to the inbox, and the after-call screen stays open for wrap-up. The frame keeps the setting for its session, so later navigation inside it does not need the parameter again.

The agent signs in inside the frame using their normal Voiger session. Your page does not pass tokens, and there is no separate integration credential.

2 · Validate both ends of every message#

Voiger accepts CRM Bridge messages only from configured parent origins. Register the exact origin of the page that directly embeds Voiger before deployment. On the host side, also check both the origin and source of every message you receive, and always name a target origin when you send.

js
const VOIGER_ORIGIN = "https://app.voiger.io";
const iframe = document.getElementById("voiger-iframe");

window.addEventListener("message", (messageEvent) => {
  if (messageEvent.origin !== VOIGER_ORIGIN) return;
  if (messageEvent.source !== iframe.contentWindow) return;

  handle(messageEvent.data);
});

function send(command) {
  iframe.contentWindow.postMessage(command, VOIGER_ORIGIN);
}
Never use '*' as the target origin, and never skip the source check. Origin alone is not enough — any frame on a matching origin would pass it.

In Zoho CRM the frame hierarchy commonly has an extra application frame:

text
crm.zoho.com
└── <dynamic-id>.zappsusercontent.com
    └── Voiger iframe

The dynamic zappsusercontent.com frame is Voiger's immediate parent. It sends the initialization command and receives Voiger's reply. The top-level CRM page cannot substitute for that immediate source window.

For hosts that assign a trusted dynamic subdomain, Voiger can register a scoped HTTPS wildcard. This matches subdomains only, not the bare domain or unrelated origins. If the immediate parent origin is not registered, Voiger silently ignores initialization and other bridge messages; it cannot safely reply to an untrusted sender.

3 · Initialize the handshake#

After installing the message listener and after the iframe fires load, send a versioned initialization command to its contentWindow.

js
let initializeId;

iframe.addEventListener("load", () => {
  initializeId = crypto.randomUUID();
  send({
    v: 1,
    type: "command",
    id: initializeId,
    module: "integrations",
    action: "initialize",
    data: {},
  });
});

The send helper uses iframe.contentWindow.postMessage(message, VOIGER_ORIGIN), where VOIGER_ORIGIN is the exact Voiger origin. Queue normal CRM Bridge commands until the correlated success reply arrives.

json
{
  "type": "reply",
  "id": "<the exact initialize command ID>",
  "status": "success",
  "data": null
}

Accept the reply only after checking both messageEvent.source === iframe.contentWindow and messageEvent.origin === VOIGER_ORIGIN, and correlate it using message.id === initializeId. Mark the bridge initialized only when status === "success" and data === null. Supported v1 commands and events are defined statically in the protocol reference.

If initialization times out, send a new initialization command with a new ID and correlate only that latest ID. Use capped exponential backoff—for example, at most three attempts—and report a configuration error after the cap. Ignore late or duplicate replies for older attempts. Do not send ordinary bridge commands while initialization is pending. Repeated timeouts should prompt a check that the immediate parent origin is registered with Voiger.

An iframe reload starts a new bridge session. Clear initialized state and queued events, reject commands awaiting replies from the previous session, and send a new initialization command with a new ID. Subscriptions do not survive a reload, so re-subscribe after the new initialization succeeds. Ignore late replies from the previous session.

4 · Subscribe to what you need#

No events reach you until you ask. Subscriptions are per address and independent, so send them together and correlate the replies by id.

js
const pending = new Map();
let seq = 0;

function command(module, action, data = {}, path) {
  const id = `crm-${action}-${++seq}`;
  return new Promise((resolve, reject) => {
    const timer = setTimeout(() => {
      pending.delete(id);
      reject(new Error(`timeout: ${module}/${action}`));
    }, 15000);
    pending.set(id, { resolve, reject, timer });
    send({
      v: 1,
      type: "command",
      id,
      module,
      action,
      ...(path && { path }),
      data,
    });
  });
}

function handle(msg) {
  if (msg.type === "reply") {
    const p = pending.get(msg.id);
    if (!p) return;
    clearTimeout(p.timer);
    pending.delete(msg.id);
    msg.status === "success" ? p.resolve(msg.data) : p.reject(msg.error);
    return;
  }
  if (msg.type === "event") onEvent(msg);
}

async function onInitialized() {
  await Promise.all([
    command("live_calls", "subscribe"),
    command("conversations", "subscribe"),
  ]);
}
Implement your own timeout, as above. Keep it longer than Voiger's 10-second internal command deadline so an error reply has time to cross the message boundary. Only a host timeout detects a frame that has crashed outright.

5 · Handle events#

Events are addressed by module plus an optional path; replies are not, and correlate by id alone. Match on the pair, never on the verb — read belongs to two addresses, and updated belongs to both conversation addresses.

js
function onEvent(msg) {
  const address = [msg.module, ...(msg.path ?? [])].join("/");

  if (address === "live_calls" && msg.event === "answered") {
    showCallScreen(msg.data.call_id, msg.data.contact);
  }

  // First assignment and later changes both arrive as `updated` — upsert, don't append.
  if (address === "conversations" && msg.event === "updated") {
    upsertInInbox(msg.data.conversation);
  }

  if (msg.event === "lossy") {
    refetch(address);
  }
}

Conversation and activity record-stream events carry the single changed record as data.conversation or data.activity, respectively. Read-command replies remain arrays because they can return multiple records.

6 · Place a call#

js
await command("live_calls", "dial", { phone: "+14155552671" });

The reply acknowledges that the dialer accepted the number, not that the call connected. Progress arrives as connecting, ringing, answered, and ended events on the live_calls address.

Next#

Full message reference — every command, reply, event, and error, with the record shapes they carry: CRM bridge protocol.