CRM bridge protocol
Every message the embedded dialer exchanges with its host page — commands, replies, events, and errors.
The bridge carries three kinds of message. type says which, and it is always present.
Practical iframe setup and host-side origin checks are covered in Embedding Voiger. This page is the protocol reference, including the normative initialization command and session behavior.
Envelope#
// command (host → app) // reply (app → host) // event (app → host) { "v": 1, { "type": "reply", { "type": "event", "type": "command", "id": "<string>", "ts": "<ISO 8601>", "id": "<string>", "status": "success|error", "module": "<string>", "module": "<string>", "data": { }, "path?": [ ], "path?": [ ], "error": { } } "event": "<string>", "action": "<string>", "data": { } } "data": { } }
Dispatch on type, then on id for replies and on (module, path, event) for events.
Three rules follow from that shape, and each removes a class of bug:
module, path, and action; youcorrelate by id. This is the JSON-RPC response shape.
data always holds the successpayload, so you never inspect it to find out whether the command worked.
answer; events inherit it from the subscribe that opened the stream.
Addressing#
An address is a module plus an optional path identifying a public bridge resource. An address may be backed by an app socket topic or a REST API. path may be omitted when empty.
live_callsconversationsconversations + ["<id>", "activities"]calls + ["<call-id>", "recording"]calls + ["<call-id>", "notes"]calls + ["<call-id>", "notes", "self"]calls + ["<call-id>", "tags"]integrationslive_calls exposes in-progress call state and cannot be queried for call history. Completed call activities are available through their conversations, and a signed recording can be resolved for a known call ID. The bridge does not provide a standalone completed-calls list or read command.
Notes and tags are read as part of conversation activities at conversations/[conversationId]/activities, but written through calls using the backend call UUID. The calls addresses do not offer a read action. The self path segment means the note owned by the authenticated agent.
Vocabulary#
actioninitialize, dial, read, count, resolve, create, update, delete, subscribe, unsubscribeeventconnecting, ringing, answered, ended, created, updated, lossyread belongs to both conversation addresses, update belongs to the own-note and call-tags addresses, and the updated event belongs to both conversation addresses. Always match on the address and verb together.Initialization handshake#
The host starts each bridge session by sending an integrations.initialize command to the Voiger iframe:
{ "v": 1, "type": "command", "id": "crm-init-1", "module": "integrations", "action": "initialize", "data": {} }
Install the message listener first, then send the command after the iframe's load event using the iframe window and exact Voiger origin:
iframe.contentWindow.postMessage( { v: 1, type: "command", id: "crm-init-1", module: "integrations", action: "initialize", data: {}, }, exactVoigerOrigin, );
The success reply carries the exact command ID:
{ "type": "reply", "id": "crm-init-1", "status": "success", "data": null }
Accept it only when both window checks pass and its ID matches the pending initialization command:
event.source === iframe.contentWindow && event.origin === exactVoigerOrigin;Before initialization succeeds, queue normal CRM Bridge commands rather than posting them. After the correlated success reply arrives:
If initialization times out, retry with a new command ID and treat only the latest ID as pending. Use capped exponential backoff — for example, at most three attempts — and surface a configuration error after the cap. Ignore a late or duplicate reply for an older ID. A valid repeat initialization receives another correlated reply but does not reset the active session.
While the agent's workspace is still loading, initialize is answered with not_ready; retry it the same way. A command other than initialize sent before the session is initialized is answered with not_ready and is not run.
The immediate parent origin must be registered in Voiger's deployment allowlist. A trusted dynamic host can use a scoped HTTPS wildcard. The only exemption is an immediate parent with the exact same origin as the Voiger app; Voiger includes its own application origin automatically for same-origin embedding and its integration tester. An otherwise unregistered origin receives no reply, so repeated initialization timeouts should prompt an allowlist check.
An iframe reload begins a new bridge session. Clear the previous initialized state and queued events, reject commands still awaiting replies from the previous session, and send a new initialization command with a new ID. Ignore late or duplicate replies from the previous session.
Commands#
Every command carries a non-empty id. A message without one is ignored — not answered, not errored — which is what keeps browser extensions and dev tooling from drawing error replies.
Failures for attributable commands are returned as replies with status: "error". The bridge does not emit error events. Malformed messages that cannot be attributed to a command, including messages without a valid id, are ignored.
Command payloads are strict: unknown fields are rejected. initialize, subscribe, and unsubscribe require data to be present and to be exactly an empty object ({}). Omitting data or adding host metadata inside it returns invalid_request. Deleting the authenticated agent's call note also requires data to be exactly {}.
integrations / initialize#
{ "v": 1, "type": "command", "id": "crm-init-1", "module": "integrations", "action": "initialize", "data": {} }
The reply preserves the command ID and carries data: null:
{ "type": "reply", "id": "crm-init-1", "status": "success", "data": null }
This command establishes the trusted iframe source and origin for the session. See Initialization handshake for loading, retry, queueing, and reload behavior.
live_calls / dial#
{ "v": 1, "type": "command", "id": "crm-8814", "module": "live_calls", "action": "dial", "data": { "phone": "+14155552671" } }
phone must be a possible E.164 number. The reply carries data: null and means the dialer accepted the number — not that the call connected.
conversations / read#
{ "v": 1, "type": "command", "id": "crm-8815", "module": "conversations", "action": "read", "data": { "query": { "_limit": 20, "_skip": 0, "_search": "", "_sort": "updated_at__dsc" } } }
_limit30_skip0_search""_sortupdated_at, updated_at__dsc, created_at, or created_at__dscupdated_at__dscAny other key or sort value is rejected. Note the descending suffix is __dsc; there is no __asc form in v1. The query object itself is optional; when it is omitted, it is treated as {} and all defaults apply. The same optional query rule applies to conversation count and activity read commands.
The reply carries the page and nothing else:
{ "type": "reply", "id": "crm-8815", "status": "success", "data": { "conversations": [ /* … */ ] } }
You are on the last page when the array is shorter than the _limit you sent. For a total, use count.
conversations / read — activities#
Activities live under a conversation, so they are addressed by path rather than by a filter.
{ "v": 1, "type": "command", "id": "crm-8816", "module": "conversations", "path": ["6f1c2a90-4d3b-11ee-be56-0242ac120002", "activities"], "action": "read", "data": { "query": { "_limit": 20, "_skip": 0 } } }
{ "type": "reply", "id": "crm-8816", "status": "success", "data": { "activities": [ /* … */ ] } }
conversations / count#
{ "v": 1, "type": "command", "id": "crm-8817", "module": "conversations", "action": "count", "data": { "query": { "_search": "acme" } } }
{ "type": "reply", "id": "crm-8817", "status": "success", "data": { "count": 128 } }
Filters only — _limit, _skip, and _sort are rejected.
calls / resolve — recording#
{ "v": 1, "type": "command", "id": "crm-8818", "module": "calls", "path": ["e88b4a71-0f45-11ef-9262-0242ac120002", "recording"], "action": "resolve", "data": { "expires_in": 86400 } }
{ "type": "reply", "id": "crm-8818", "status": "success", "data": { "url": "https://…", "expires_at": "2026-08-22T09:14:02Z" } }
path segment and must be a UUID. Optional expires_in is an integer duration in seconds from 1 through 7776000 (90 days). When omitted, it defaults to 3600 seconds. Voiger passes this duration to the recording backend as its ttl parameter. The reply reports the generated URL's absolute expiration in expires_at.backend_error.calls / create — note#
Create the current agent's note for a backend call UUID:
{ "v": 1, "type": "command", "id": "crm-8819", "module": "calls", "path": ["e88b4a71-0f45-11ef-9262-0242ac120002", "notes"], "action": "create", "data": { "note": { "message": "Customer requested a follow-up tomorrow." } } }
data must contain only a note object, and note must contain only a non-empty string message. The success reply preserves the command ID and contains the note returned by the call-note API:
{ "type": "reply", "id": "crm-8819", "status": "success", "data": { "note": { "message": "Customer requested a follow-up tomorrow.", "created_at": "2026-09-14T12:00:00Z", "updated_at": "2026-09-14T12:00:00Z" } } }
This write reply contains the call-note API's smaller note representation: message, created_at, and updated_at. Unlike a note read through a conversation activity, it does not contain the note ID or an enriched author record and cannot be matched by ID to the later activity representation.
calls / update — own note#
Update the current agent's existing note. The self segment identifies the authenticated agent; the host does not send a note or user ID.
{ "v": 1, "type": "command", "id": "crm-8820", "module": "calls", "path": ["e88b4a71-0f45-11ef-9262-0242ac120002", "notes", "self"], "action": "update", "data": { "note": { "message": "Customer requested a follow-up next week." } } }
The success reply uses the same data.note shape as note creation.
calls / delete — own note#
{ "v": 1, "type": "command", "id": "crm-8821", "module": "calls", "path": ["e88b4a71-0f45-11ef-9262-0242ac120002", "notes", "self"], "action": "delete", "data": {} }
data must be exactly {}. A successful deletion returns:
{ "type": "reply", "id": "crm-8821", "status": "success", "data": null }
calls / update — tags#
The host identifies tags by name; it does not send Voiger tag IDs or colors.
{ "v": 1, "type": "command", "id": "crm-8822", "module": "calls", "path": ["e88b4a71-0f45-11ef-9262-0242ac120002", "tags"], "action": "update", "data": { "tags": [{ "name": "Follow up" }, { "name": "Qualified" }] } }
data must contain only tags. Every entry must contain only a non-empty string name. Voiger trims and compares names case-insensitively against the enabled tag replica for the active workspace. Unknown and disabled names are ignored, and duplicate matches are applied once.
When at least one tag matches, Voiger sends the matched tag IDs to the call tags API. That matched set replaces all user-source tags currently assigned to the call. System-source and AI-source tags remain unchanged.
When none match, including an empty input array, Voiger does not call the backend, does not clear or otherwise modify existing tags, and returns an empty successful result. The reply always contains only the canonical matched Voiger tags:
{ "type": "reply", "id": "crm-8822", "status": "success", "data": { "tags": [ { "id": "<voiger-tag-id>", "name": "Follow up", "color": "#3366ff" } ] } }
subscribe and unsubscribe#
Available only at live_calls, conversations, and conversations/[conversationId, "activities"]. The integrations address and all calls addresses, including calls/[callId, "recording"], do not support subscriptions. Nothing is pushed until you subscribe to the corresponding supported address.
{ "v": 1, "type": "command", "id": "crm-9100", "module": "conversations", "path": ["6f1c2a90-4d3b-11ee-be56-0242ac120002", "activities"], "action": "subscribe", "data": {} }
Both replies carry data: null. unsubscribe is idempotent. subscribe returns no records — call read if you want a snapshot. live_calls has no read: a call already in progress when you subscribe produces only the events for the states it reaches afterwards.
Activity subscriptions are capped at 25 distinct conversation paths per session, since each one may open a channel. Active and pending subscriptions both count toward the cap; subscribing to the same path again does not consume another slot. Over the cap, subscribe fails with invalid_request and a message naming the limit. Unsubscribe from conversations you are no longer showing.
Events#
Events are unsolicited, so unlike replies they carry their full address.
live_calls#
connecting, ringing, answered, ended — one payload shape:
{ "type": "event", "ts": "2026-08-21T09:14:02Z", "module": "live_calls", "event": "answered", "data": { "call_id": "<string> or null", "contact": { "id": "<uuid>", "first_name": "John", "last_name": "Dao", "phones": [{ "phone": "+14155552671", "is_primary": true }], "emails": [{ "email": "lin@example.com", "is_primary": false }], "outbound_calls_blocked": false, "inbound_calls_blocked": false }, "caller": { "number": "<string>", "name": "<string> or null" }, "callee": { "number": "<string>", "name": "<string> or null" } } }
contact is the full contact record when Voiger can resolve the number, otherwise null. caller is populated for inbound calls and callee for outbound. Internal and eavesdrop calls are never exposed.
call_id is the backend call UUID, the one the calls addresses take. An inbound call carries it from its first event. An outbound call carries null until the call is answered, so its connecting and ringing events have no call_id.
answered waits until Voiger has finished looking up the contact, so that contact is complete. If the call ends before the lookup finishes, answered is sent immediately before ended. ended is sent once for every call, including one that was already in progress when you subscribed.
Each event fires at most once per call, so a call re-entering a state does not re-emit.
conversations and activities#
{ "type": "event", "ts": "2026-08-21T14:31:52Z", "module": "conversations", "event": "updated", "data": { "conversation": { /* … */ } } }
{ "type": "event", "ts": "2026-08-21T14:31:52Z", "module": "conversations", "path": ["6f1c2a90-…", "activities"], "event": "updated", "data": { "activity": { /* … */ } } }
The conversations address emits updated events carrying one record in data.conversation. A conversation is first assigned to an agent through this update flow, so the bridge does not emit a separate conversation created event. Conversations cannot be deleted through this event stream, so it does not emit conversation deleted events.
Activity created and updated events carry one record in data.activity. Activity deleted events are not emitted. Read-command replies remain arrays.
Only inbound and outbound call activities cross the bridge. Internal calls, eavesdrop calls, WhatsApp messages, and SMS messages are excluded from activity reads and push events. They are also excluded from a conversation's latest_activity, which is null when the underlying latest activity is not eligible.
lossy#
The bridge bounds its outbound queue. If you cannot drain fast enough it stops sending on that address and tells you so.
{ "type": "event", "ts": "2026-08-21T14:32:10Z", "module": "conversations", "path": ["6f1c2a90-…", "activities"], "event": "lossy", "data": { "dropped": 412 } }
For a conversation or activity address, re-read it before continuing to use locally stored state; a successful read also resumes event delivery for that address. live_calls has no read action, so subscribe again to resume that stream.
Errors#
A command that fails produces a status: "error" reply, not an event. The bridge does not emit error events. A malformed message without enough information to correlate a reply is ignored.
{ "type": "reply", "id": "crm-8815", "status": "error", "error": { "code": "backend_error", "message": "Conversation read failed." } }
codemessagedetailsinvalid_requestunsupported_versionv missing or unsupportedunsupported_moduleunsupported_pathunsupported_actionunauthorizedforbiddennot_readysocket_unavailablebackend_errorValidation order#
The first check that fails decides the outcome; nothing after it runs.
idv present and supportedunsupported_versiontype is commandinvalid_requestmodule is a string and is exposedunsupported_modulepath valid for that moduleunsupported_pathaction supported at that addressunsupported_actioninvalid_requestnot_ready, socket_unavailable, backend_error, unauthorized, forbiddenSteps 1 to 7 are decided without touching the network. Step 8 is runtime.
id is checked before v deliberately, so a command with an unsupported version still gets an error reply rather than silence. Only genuinely unattributable traffic is ignored.Record shapes#
The following are the complete record shapes exposed by the public wire contract. Where a nested record is nullable, null means the record is unavailable; clients must support both the populated record and null.
conversation#
{ "id": "<uuid>", "created_at": "<ISO 8601>", "updated_at": "<ISO 8601>", "latest_activity": {}, "participants": [] }
latest_activity is either an eligible call activity or null. In conversation list replies, its data projection intentionally omits tags, notes, and call intelligence fields for performance. Read the conversation's activities when the full enriched activity data is required. participants is always an array.
participant#
One of three shapes, discriminated by type:
type Participant = | { id: string; type: "admin"; admin: Admin | null; } | { id: string; type: "agent"; agent: Agent | null; } | { id: string; type: "customer"; contact: Contact | null; };
The matching admin, agent, or contact field contains the complete public record or null.
activity#
{ "id": "<uuid>", "type": "call", "created_at": "<ISO 8601>", "data": { "id": "<uuid>", "direction": "inbound | outbound", "started_at": "<ISO 8601 or null>", "ended_at": "<ISO 8601 or null>", "status": "connecting | ringing | active | held | hungup | wrap_up | finished", "talk_time": 42, "hold_time": null, "duration": 57, "result": "answered", "hangup_by": "customer", "latest_intelligence_status": "completed", "latest_call_intelligence": { "id": "<uuid>", "status": "completed", "summary": { "overview": "The customer asked about the annual plan.", "outcome": "Follow-up scheduled.", "sentiment": "positive", "action_items": [ { "text": "Send the annual-plan proposal.", "owner": "agent" } ], "tag_ids": ["<uuid>"] } }, "caller": { "type": "agent", "agent": { "id": "<uuid>", "first_name": "Grace", "last_name": "Hopper" } }, "callee": { "type": "customer", "contact": { "id": "<uuid>", "first_name": "Lin", "last_name": "Chen", "phones": [], "emails": [], "outbound_calls_blocked": false, "inbound_calls_blocked": false } }, "contact": { "id": "<uuid>", "first_name": "Lin", "last_name": "Chen", "phones": [], "emails": [], "outbound_calls_blocked": false, "inbound_calls_blocked": false }, "assignee": { "id": "<uuid>", "first_name": "Grace", "last_name": "Hopper" }, "queue": { "id": "<uuid>", "name": "Sales" }, "tags": [ { "id": "<uuid>", "name": "Qualified", "color": "#22c55e" } ], "notes": [ { "id": "<uuid>", "message": "Asked for a follow-up.", "created_at": "<ISO 8601>", "updated_at": "<ISO 8601>", "user_type": "agent", "agent": { "id": "<uuid>", "first_name": "Grace", "last_name": "Hopper" } } ] } }
data itself may be null. When present, id, direction, started_at, ended_at, status, caller, callee, contact, assignee, queue, and tags are always present. started_at and ended_at may be null.
talk_time, hold_time, duration, result, hangup_by, latest_intelligence_status, latest_call_intelligence, and notes are optional; when emitted, the three duration fields, result, and hangup_by may also be null. result is answered, busy, no_answer, cancelled, failed, or transferred. hangup_by is agent, admin, customer, or system.
caller and callee are discriminated subjects: an admin, agent, or customer subject carries its matching nullable record, while a system subject is { "type": "system" } or { "type": null }. contact, assignee, and queue contain their public records or null; tags is always an array. In an agent session the bridge cannot resolve admin records, so admin subjects, admin participants, and admin note authors are always null. Treat them as unavailable rather than absent, and do not build on them. queue is resolved from the agent's queue cache and is null only when that queue is unavailable.
Each optional note contains id, message, created_at, updated_at, and user_type. user_type is admin or agent, and the note also carries the matching nullable author record.
When present, latest_intelligence_status is pending, processing, completed, or failed. latest_call_intelligence contains id, its own status, and a nullable summary. Its status is transcribing, summarizing, completed, or failed. When the summary is present, its five fields have the concrete shapes documented below.
activity subject#
caller and callee use one of these four shapes:
type ActivitySubject = | { type: "admin"; admin: Admin | null; } | { type: "agent"; agent: Agent | null; } | { type: "customer"; contact: Contact | null; } | { type: "system" | null; };
Admin, agent, and customer subjects contain the corresponding public record or null. An activity subject has no top-level id.
activity note#
Notes are discriminated by user_type:
{ "id": "<uuid>", "message": "<string>", "created_at": "<ISO 8601>", "updated_at": "<ISO 8601>", "user_type": "admin", "admin": { "id": "<uuid>", "first_name": "Ada", "last_name": "Lovelace", "phone": null, "email": "ada@example.com", "status": "active" } }
For user_type: "agent", the last field is agent and contains the corresponding record or null. Notes are always authored by a user, so user_type is only ever admin or agent.
call intelligence#
type CallIntelligence = { id: string; status: "transcribing" | "summarizing" | "completed" | "failed"; summary: { overview: string; outcome: string; sentiment: "positive" | "neutral" | "negative"; action_items: readonly { text: string; owner: "agent" | "customer" | "unknown"; }[]; tag_ids: readonly string[]; } | null; };
summary may be null. When present, all five summary fields are required. overview and outcome are strings. sentiment is positive, neutral, or negative. Each action item contains a string text and an owner of agent, customer, or unknown. tag_ids is always an array of strings.
contact#
{ "id": "<uuid>", "first_name": "<string> or null", "last_name": "<string> or null", "phones": [{ "phone": "<string>", "is_primary": true }], "emails": [{ "email": "<string>", "is_primary": true }], "outbound_calls_blocked": false, "inbound_calls_blocked": false }
When the workspace enables hide_phone_numbers, customer phone values may be masked, for example +91XXXXXXXXX0. A masked value is display-only and must not be treated as a dialable E.164 number.
admin#
{ "id": "<uuid>", "first_name": "<string>", "last_name": "<string>", "phone": "<string or null>", "email": "<string>", "status": "active | blocked" }
agent#
{ "id": "<uuid>", "first_name": "<string>", "last_name": "<string>" }
queue#
{ "id": "<uuid>", "name": "<string>" }
tag#
{ "id": "<uuid>", "name": "<string>", "color": "<string>" }