Integrations/CRM bridge protocol
Integrations

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#

json
// 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:

Replies carry no addressing. You sent module, path, and action; you

correlate by id. This is the JSON-RPC response shape.

`data` and `error` are mutually exclusive. data always holds the success

payload, so you never inspect it to find out whether the command worked.

Only commands carry `v`. Replies inherit the version from the command they

answer; events inherit it from the subscribe that opened the stream.

Because a subscription pins its version, a stream opened at v1 keeps delivering v1 shapes for its whole life, even after the app starts accepting v2 commands. The subscription — not the message — is the unit of version negotiation.

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.

Address
Covers
live_calls
the dialer: placing calls and live call state
conversations
conversation list and change events
conversations + ["<id>", "activities"]
activities within one conversation
calls + ["<call-id>", "recording"]
signed URL for one call recording
calls + ["<call-id>", "notes"]
create the current agent's note for one call
calls + ["<call-id>", "notes", "self"]
update or delete the current agent's note
calls + ["<call-id>", "tags"]
assign known workspace tags to one call
integrations
the bridge itself — session initialization

live_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#

Kind
Values
action
initialize, dial, read, count, resolve, create, update, delete, subscribe, unsubscribe
app → host event
connecting, ringing, answered, ended, created, updated, lossy
Verbs repeat across addresses. read 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:

json
{
  "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:

js
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:

json
{ "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:

js
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:

Mark the iframe session initialized.
Notify initialization listeners.
Deliver the queued commands.

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#

json
{
  "v": 1,
  "type": "command",
  "id": "crm-init-1",
  "module": "integrations",
  "action": "initialize",
  "data": {}
}

The reply preserves the command ID and carries data: null:

json
{ "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#

json
{
  "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#

json
{
  "v": 1,
  "type": "command",
  "id": "crm-8815",
  "module": "conversations",
  "action": "read",
  "data": {
    "query": {
      "_limit": 20,
      "_skip": 0,
      "_search": "",
      "_sort": "updated_at__dsc"
    }
  }
}
Field
Rule
Default
_limit
integer, 1–30
30
_skip
integer, 0 or more
0
_search
string
""
_sort
updated_at, updated_at__dsc, created_at, or created_at__dsc
updated_at__dsc

Any 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:

json
{
  "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.

json
{
  "v": 1,
  "type": "command",
  "id": "crm-8816",
  "module": "conversations",
  "path": ["6f1c2a90-4d3b-11ee-be56-0242ac120002", "activities"],
  "action": "read",
  "data": { "query": { "_limit": 20, "_skip": 0 } }
}
json
{
  "type": "reply",
  "id": "crm-8816",
  "status": "success",
  "data": {
    "activities": [
      /* … */
    ]
  }
}

conversations / count#

json
{
  "v": 1,
  "type": "command",
  "id": "crm-8817",
  "module": "conversations",
  "action": "count",
  "data": { "query": { "_search": "acme" } }
}
json
{
  "type": "reply",
  "id": "crm-8817",
  "status": "success",
  "data": { "count": 128 }
}

Filters only — _limit, _skip, and _sort are rejected.

calls / resolve — recording#

json
{
  "v": 1,
  "type": "command",
  "id": "crm-8818",
  "module": "calls",
  "path": ["e88b4a71-0f45-11ef-9262-0242ac120002", "recording"],
  "action": "resolve",
  "data": {
    "expires_in": 86400
  }
}
json
{
  "type": "reply",
  "id": "crm-8818",
  "status": "success",
  "data": { "url": "https://…", "expires_at": "2026-08-22T09:14:02Z" }
}
The call ID is the first 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.
Call note and tag writes are available only while the call is ongoing and the signed-in agent remains eligible, including eligible wrap-up. Finished or historical calls cannot be modified. These lifecycle failures currently return backend_error.

calls / create — note#

Create the current agent's note for a backend call UUID:

json
{
  "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:

json
{
  "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.

json
{
  "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#

json
{
  "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:

json
{ "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.

json
{
  "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:

json
{
  "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.

json
{
  "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:

json
{
  "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#

json
{
  "type": "event",
  "ts": "2026-08-21T14:31:52Z",
  "module": "conversations",
  "event": "updated",
  "data": {
    "conversation": {
      /* … */
    }
  }
}
json
{
  "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.

json
{
  "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.

json
{
  "type": "reply",
  "id": "crm-8815",
  "status": "error",
  "error": { "code": "backend_error", "message": "Conversation read failed." }
}
Field
Meaning
code
machine-readable class, listed below
message
human-readable English, safe to log, not to show a customer
details
optional, free-form; field-level specifics when a payload was rejected
code
Cause
invalid_request
invalid payload, missing call/note resource, or activity subscription limit reached
unsupported_version
v missing or unsupported
unsupported_module
module not exposed by this deployment
unsupported_path
module known, path segment is not
unsupported_action
address known, action not offered there
unauthorized
session rejected
forbidden
session valid, access denied
not_ready
subsystem not up, workspace loading, or bridge session restarted
socket_unavailable
the app cannot reach the backend right now
backend_error
the request ran and the backend failed, or ran longer than 10 seconds

Validation order#

The first check that fails decides the outcome; nothing after it runs.

#
Check
On failure
1
well-formed object with a valid id
ignored — no reply
2
v present and supported
unsupported_version
3
type is command
invalid_request
4
module is a string and is exposed
unsupported_module
5
path valid for that module
unsupported_path
6
action supported at that address
unsupported_action
7
payload valid
invalid_request
8
execution
not_ready, socket_unavailable, backend_error, unauthorized, forbidden

Steps 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#

json
{
  "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:

js
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#

json
{
  "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:

js
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:

json
{
  "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#

js
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#

json
{
  "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#

json
{
  "id": "<uuid>",
  "first_name": "<string>",
  "last_name": "<string>",
  "phone": "<string or null>",
  "email": "<string>",
  "status": "active | blocked"
}

agent#

json
{
  "id": "<uuid>",
  "first_name": "<string>",
  "last_name": "<string>"
}

queue#

json
{
  "id": "<uuid>",
  "name": "<string>"
}

tag#

json
{
  "id": "<uuid>",
  "name": "<string>",
  "color": "<string>"
}