SDK

New to Quarterzip?Be sure to visit the Getting Started page before continuing with this section.

Quickstart Plan

Configure your Quarterzip Workspace for SDK
Install the Quarterzip SDK
Grant Security Permissions
Trigger the Quarterzip Agent

Configure your Quarterzip Workspace for SDK

Within the Quarterzip app, visit the SDK Settings (Settings -> SDK) for the Quarterzip workspace that has the agent you wish to integrate. This page provides the configuration options to restrict who may serve your agent on your behalf.

Workspace Token: a public token used to authenticate your site to Quarterzip.
Allowed Origins: an optional list of site origins that are authorised to serve your Quarterzip agent. This list may include wildcards for subdomains, i.e. https://*.example.com

Install the Quarterzip SDK

CDN Script

<script>
  (function() {
    var q = [];
    window.Quarterzip = {
      _q: q,
      open: function(args) { q.push(['open', args]); },
      close: function(args) { q.push(['close', args]); },
    };
    var s = document.createElement('script');
    s.async = true;
    s.src = 'https://sdk.quarterzip.ai/sdk/quarterzip.js';
    document.head.appendChild(s);
  })();
</script>

NPM Package

The CDN Script is the recommended installation method for Quarterzip. Please contact support before using this NPM package installation.

pnpm add @quarterzip.ai/sdk

Grant Security Permissions

The Quarterzip SDK operates in a security sandbox separate from your site. In order for your Quarterzip agent to communicate with your users, the following permissions must be granted if enforced.

CSP requirements

Only relevant if your page sends a Content-Security-Policy header, then it must permit Quarterzip’s SDK origin to be framed.

Content-Security-Policy:
  frame-src https://sdk.quarterzip.ai;
  child-src  https://sdk.quarterzip.ai;

Permissions Policy

Only relevant if your page sends a Permissions-Policy header, then it must permit Quarterzip’s SDK origin the following permissions:

Permissions-Policy:
  microphone=(self "https://sdk.quarterzip.ai"),
  display-capture=(self "https://sdk.quarterzip.ai"),
  autoplay=(self "https://sdk.quarterzip.ai"),
  speaker-selection=(self "https://sdk.quarterzip.ai"),
  storage-access=(self "https://sdk.quarterzip.ai")

Learn more at Security.

Trigger the Quarterzip Agent

Call window.Quarterzip.open() from any user interaction; i.e. a button-press. Visit API Reference for more details.

window.Quarterzip.open({
  workspaceToken: 'YOUR_WORKSPACE_TOKEN',
  agentId: 'YOUR_AGENT_ID',
  user: {
    id: 'your_internal_user_id'
    email: 'jane@company.com',
    displayName: 'Jane Smith',
  }
});

Quarterzip.open({
  workspaceToken: 'YOUR_WORKSPACE_TOKEN',
  agentId: 'YOUR_AGENT_ID',
  user: {
    id: 'your_internal_user_id'
    email: 'jane@company.com',
    displayName: 'Jane Smith',
  }
});

It’s important to verify integration by conducting a call with the agent; completing expected steps such as: granting microphone permissions, screen-sharing, ending the call.

Best Practices

Set yourself up for success.

Webhooks

React and receive call data.

Advanced patterns

Passing additional context to the agent

The context parameter may be used to provide additional information to the agent to enhance the conversation; e.g. the user’s plan, country, or handover notes from another support tool. The agent only receives this information if the user decides to start the call. The amount of context is capped at 2,000 characters.

window.Quarterzip.open({
  workspaceToken: 'YOUR_WORKSPACE_TOKEN',
  agentId: 'YOUR_AGENT_ID',
  user: { id: user.id, email: user.email, displayName: user.displayName },
  context: `Plan: ${user.plan}. Country: ${user.country}.`,
});

Quarterzip.open({
  workspaceToken: 'YOUR_WORKSPACE_TOKEN',
  agentId: 'YOUR_AGENT_ID',
  user: { id: user.id, email: user.email, displayName: user.displayName },
  context: `Plan: ${user.plan}. Country: ${user.country}.`,
});

Conditionally present Quarterzip agents

Most customers prefer to show agents to users based on feature-flags or user-attributes. Screen-sharing requires the user’s browser to have the getDisplayMedia() web API, which is unavailable on most mobile devices & can help determine which users filter against.

import { useFeatureFlagEnabled } from 'posthog-js/react';

function maybeOpenAgent() {
  // Feature-flag Quarterzip agent
  const enabled = useFeatureFlagEnabled('quarterzip-sdk');
  if (!enabled) return null;
  
  // Does browser support screen-sharing
  const canScreenShare = !!(navigator.mediaDevices?.getDisplayMedia);
  if (!canScreenShare) return null;

  // Show Quarterzip agent based on a user-attribute; i.e. first-time visit
  const user = getCurrentUser();
  if (user.onboardingComplete) return null;

  return (
    <button onClick={() => window.Quarterzip.open({
      workspaceToken: 'YOUR_WORKSPACE_TOKEN',
      agentId: 'YOUR_AGENT_ID',
      user: { id: user.id, email: user.email, displayName: user.displayName },
    })}>
      Get guided help
    </button>
  );
}

import { Quarterzip } from '@quarterzip.ai/sdk';
import { useFeatureFlagEnabled } from 'posthog-js/react';

function maybeOpenAgent() {
  // Feature-flag Quarterzip agent
  const enabled = useFeatureFlagEnabled('quarterzip-sdk');
  if (!enabled) return null;
  
  // Does browser support screen-sharing
  const canScreenShare = !!(navigator.mediaDevices?.getDisplayMedia);
  if (!canScreenShare) return null;

  // Show Quarterzip agent based on a user-attribute; i.e. first-time visit
  const user = getCurrentUser();
  if (user.onboardingComplete) return null;

  return (
    <button onClick={() => Quarterzip.open({
      workspaceToken: 'YOUR_WORKSPACE_TOKEN',
      agentId: 'YOUR_AGENT_ID',
      user: { id: user.id, email: user.email, displayName: user.displayName },
    })}>
      Get guided help
    </button>
  );
}

Closing on route change

End the call when a user navigates away from a specific area (React Router v6 example):

import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

function useCloseAgentOnLeave(protectedPaths = []) {
  const location = useLocation();
  useEffect(() => {
    const isProtected = protectedPaths.some(p => location.pathname.startsWith(p));
    if (!isProtected) window.Quarterzip?.close();
  }, [location.pathname]);
}

useCloseAgentOnLeave(['/onboarding']);

import { Quarterzip } from '@quarterzip.ai/sdk';
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

function useCloseAgentOnLeave(protectedPaths = []) {
  const location = useLocation();
  useEffect(() => {
    const isProtected = protectedPaths.some(p => location.pathname.startsWith(p));
    if (!isProtected) Quarterzip?.close();
  }, [location.pathname]);
}

useCloseAgentOnLeave(['/onboarding']);

React wrapper hook

import { useCallback } from 'react';
import { useCurrentUser } from '../hooks/useCurrentUser';

export function useQuarterzip(agentId) {
  const user = useCurrentUser();

  const open = useCallback(() => {
    window.Quarterzip?.open({
      workspaceToken: process.env.REACT_APP_QUARTERZIP_TOKEN,
      agentId,
      user: { email: user.email, displayName: user.displayName, id: user.id },
    });
  }, [agentId, user]);

  const close = useCallback(() => window.Quarterzip?.close(), []);

  return { open, close };
}

import { Quarterzip } from '@quarterzip.ai/sdk';
import { useCallback } from 'react';
import { useCurrentUser } from '../hooks/useCurrentUser';

export function useQuarterzip(agentId) {
  const user = useCurrentUser();

  const open = useCallback(() => {
    Quarterzip?.open({
      workspaceToken: process.env.REACT_APP_QUARTERZIP_TOKEN,
      agentId,
      user: { email: user.email, displayName: user.displayName, id: user.id },
    });
  }, [agentId, user]);

  const close = useCallback(() => Quarterzip?.close(), []);

  return { open, close };
}

Quarterzip

Documentation

Security & Privacy

Quickstart Plan

Configure your Quarterzip Workspace for SDK

Install the Quarterzip SDK

CDN Script

NPM Package

Grant Security Permissions

CSP requirements

Permissions Policy

Trigger the Quarterzip Agent

Best Practices

Webhooks

Advanced patterns

Passing additional context to the agent

Conditionally present Quarterzip agents

Closing on route change

React wrapper hook

What’s Next?

Best Practices

Webhooks

​Quickstart Plan

​Configure your Quarterzip Workspace for SDK

​Install the Quarterzip SDK

​CDN Script

​NPM Package

​Grant Security Permissions

​CSP requirements

​Permissions Policy

​Trigger the Quarterzip Agent

Best Practices

Webhooks

​Advanced patterns

​Passing additional context to the agent

​Conditionally present Quarterzip agents

​Closing on route change

​React wrapper hook

​What’s Next?

Best Practices

Webhooks

Quickstart Plan

Configure your Quarterzip Workspace for SDK

Install the Quarterzip SDK

CDN Script

NPM Package

Grant Security Permissions

CSP requirements

Permissions Policy

Trigger the Quarterzip Agent

Advanced patterns

Passing additional context to the agent

Conditionally present Quarterzip agents

Closing on route change

React wrapper hook

What’s Next?