SDK API Reference - Quarterzip Docs

`Quarterzip.open()`

Opens the Quarterzip agent panel. The call does not begin until the user clicks Join.

  Quarterzip.open(args: OpenArgs, options?: OpenOptions): void

interface OpenArgs {
  /** ID of the agent to call. */
  agentId: string;
  /** Your workspace's public token — safe to ship in client code, not a secret. */
  workspaceToken: string;
  /** Who is on the call. */
  user: {
    /** Required. Opaque or hashed identifier from your own system. */
    id: string;
    /** Optional. Only sent if you want it on the Quarterzip call record. */
    email?: string;
    /** Optional. Only sent if you want it on the Quarterzip call record. */
    displayName?: string;
  };
  /** Optional free text handed to the agent as context for this call. */
  context?: string;

  /** Called once when the call finishes, whatever the reason. */
  onEnd?: (event: { reason: string }) => void;
  /** Called when the call fails. When `fatal` is true, `onEnd` follows. */
  onError?: (event: { code: string; fatal: boolean }) => void;
}

 interface OpenOptions {
  /** Default console verbosity for every call. */
  logLevel?: LogLevel;
  /** Allow the floating Picture-in-Picture window. Defaults to true. */
  pip?: boolean
}

// Must be called from a user gesture (e.g. a click handler).
callButton.addEventListener('click', () => {
  window.Quarterzip.open(
    {
      agentId: 'YOUR_AGENT_ID',
      workspaceToken: 'YOUR_WORKSPACE_TOKEN',
      user: {
        id: 'your_internal_user_id',
        email: 'jane@example.com',
        displayName: 'Jane Doe'
      },
      context: 'Viewing invoice INV-4471, plan: enterprise',
      onEnd: ({ reason }) => analytics.track('call_ended', { reason }),
      onError: ({ code, fatal }) => console.warn('Quarterzip call failed', code, fatal)
    },
  );
});

`onEnd()`

/** Called once when the call finishes, whatever the reason. */
onEnd?: (event: { reason: string }) => void;  

`reason`	description
`user`	The user closed the Quarterzip panel themselves, using its own close control. The standard way a call ends.
`integrator`	Your code ended it — you called `Quarterzip.close()`, or called `open()` again with a different agentId, which closes the running session before starting the new one.
`detached`	The panel was removed from the page, or the page navigated away, without anyone ending the call. Typically occurs when a single-page app unmounts the container, or due to a full page navigation.
`error`	A failure ended the session. See `onError()`.

`onError()`

/** Called when the call fails. When `fatal` is true, `onEnd` follows. */
onError?: (event: { code: string; fatal: boolean }) => void;

Currently, all events are fatal: true.

`code`	description
`frame-unreachable`	The Quarterzip iframe panel failed to fetch its contents. Typically due to your page’s configuration; see granting security permissions.
`frame-not-ready`	The iframe panel loaded but failed to signal as healthy. Retry with `open()`. If it persists, contact Quarterzip support with the `agentId` and approximate time.
`open-args-not-transferable`	Your `open()` arguments could not be sent to the panel. Review the expected arguments & their types.
`authentication-failed`	The session failed to authentication checks. Usually transient & safe to retry.
`agent-does-not-exist`	The `agentId` is unknown, or the `workspaceToken` is not valid for that agent.
`agent-not-accepting-calls`	The agent is configured not to take calls until the agent is re-enabled in the Quarterzip dashboard. Hide or disable your call entry point if you surface this.
`call-limit-reached`	A usage limit on the workspace has been reached. Contact Quarterzip to discuss billing.
`no-agents-available`	No agent could be assigned to the call as capacity was momentarily exhausted. Retry shortly thereafter.
`call-start-failed`	The call could not be started for a reason that isn’t one of the more specific codes above. Generally transient; let the user retry.
`device-error`	The user’s microphone could not be used: the permission prompt was denied or dismissed by the user, no input device is available, or the device is held by another application. The user has to fix this in their browser or OS.
`connection-failed`	The network or media transport dropped.
`call-failed`	The call failed for a reason other than connectivity.

`Quarterzip.close()`

Quarterzip.close(): void

// Ends the active call and removes the iframe and any PiP window.
// Safe to call when nothing is open — it's a no-op.
window.Quarterzip.close();

⌘I