SDK API Reference

`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;
  /** Optional BCP-47 language tag. A hint for the default displayed language option */
  locale?: string;

  /** Optional event handler callbacks */
  on?: {
    /** Called when the user begins a call with the Quarterzip agent */
    callStarted?: () => void;
    /** Called when the call ends, for any reason */
    callEnded?: () => void;
    /** Called when the QZ player is closed post-call */
    close?: () => (event: { reason: string }) => void;
    /** Called when the call fails. When `fatal` is true, `callEnded` and `close` follow. */
    error?: () => (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',
      on: {
	   close: ({ reason }) => analytics.track('call_ended', { reason }),
        error: ({ code, fatal }) => console.warn('Quarterzip call failed', code, fatal)
	 }
    },
  );
});

`locale`

Provide a BCP-47 language tag in this field to hint Quarterzip with the language preferences of the user. This merely decides the default language setting that will be presented to the user - they will still be able to select any of the languages Quarterzip supports. If the locale supplied in the locale field is empty or not supported by Quarterzip, the picker defaults to the user’s browser-configured locale. If this is also unavailable, it defaults to the default value configured for that agent. The agent language will match the narrowest possible locale. For instance: Quarterzip currently does not support Quebecois agents, so fr-CA will resolve to fr . Quarterzip does support Australian English, so en-AU passes through unchanged. Supported Languages

Locale	Language
`ar`	Arabic
`bg`	Bulgarian
`cs`	Czech
`da`	Danish
`de`	German
`el`	Greek
`en`	English
`en-AU`	English (Australian)
`en-GB`	English (British)
`es`	Spanish
`fi`	Finnish
`fil`	Filipino (Tagalog)
`fr`	French
`hi`	Hindi
`hr`	Croatian
`hu`	Hungarian
`id`	Indonesian
`it`	Italian
`ja`	Japanese
`ko`	Korean
`ms`	Malay
`nl`	Dutch
`no`	Norwegian
`pl`	Polish
`pt`	Portuguese
`ro`	Romanian
`ru`	Russian
`sk`	Slovak
`sv`	Swedish
`ta`	Tamil
`th`	Thai
`tr`	Turkish
`uk`	Ukrainian
`vi`	Vietnamese
`zh`	Chinese

`on.close()`

/** Called once when the call finishes, whatever the reason. */
on.close?: (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()`.

`on.error()`

/** Called when the call fails. When `fatal` is true, `onEnd` follows. */
on.error?: (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();

Quarterzip

Documentation

Security & Privacy

`Quarterzip.open()`

`locale`

`on.close()`

`on.error()`

`Quarterzip.close()`

​Quarterzip.open()

​locale

​on.close()

​on.error()

​Quarterzip.close()

`Quarterzip.open()`

`locale`

`on.close()`

`on.error()`

`Quarterzip.close()`