> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quarterzip.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK API Reference

> SDK API reference and environment requirements

## `Quarterzip.open()`

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

```typescript theme={null}
  Quarterzip.open(args: OpenArgs, options?: OpenOptions): void
```

```typescript theme={null}
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
}
```

<CodeGroup>
  ```tsx CDN theme={null}
  // 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)
      },
    );
  });
  ```

  ```tsx NPM theme={null}
  ```
</CodeGroup>

### `onEnd()`

```typescript theme={null}
/** 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()`

```typescript theme={null}
/** 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](/sdk#grant-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()`

```typescript theme={null}
Quarterzip.close(): void
```

<CodeGroup>
  ```tsx CDN theme={null}
  // 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();
  ```

  ```tsx NPM theme={null}
  ```
</CodeGroup>