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

# Link

The fastest way to connect users with your Quarterzip agent. Each agent gets a dedicated URL — embed it anywhere and users can start a guided call in seconds.

<Info>
  New to Quarterzip? Be sure to visit the [Getting Started](/getting-started) page before continuing with this section.
</Info>

<Frame>
  <img src="https://mintcdn.com/quarterzip/3eoe3T3Ys__wuR4v/images/image.png?fit=max&auto=format&n=3eoe3T3Ys__wuR4v&q=85&s=8783bdeb1a3382c55fdb4902c541e9d1" alt="Image" width="1080" height="642" data-path="images/image.png" />
</Frame>

## Where to embed your link?

Your agent URL can be placed anywhere users interact with your product. Common entry points:

* **In-product button -** A contextual help button inside your application
* **Email CTA -** Onboarding, re-engagement, or expansion emails
* **Marketing site -** Landing pages, pricing pages, or demo CTAs
* **Help centers -** Provide 1:1 personalized support

## What is the User's Experience?

<Steps>
  <Step title="User clicks the link">
    The user is taken to the Quarterzip-hosted page for the agent. This page is customised with your logo & branding.
  </Step>

  <Step title="User starts a call with the Agent">
    First-time users are asked to grant microphone access permissions. The Quarterzip agent introduces themselves & handles any immediate questions or needs from the user. 
  </Step>

  <Step title="User is asked to share their screen">
    The user is prompted to share their tab, window, or screen, and to open the product if required.
  </Step>

  <Step title="User is presented with an Agent player across tabs">
    The agent's player appears early in the call in a Picture-in-Picture (PiP) window. An always-on-top, draggable window from which the user can control the call where ever they go.
  </Step>

  <Step title="Agent guides the user">
    After resolving any immediate issues the user may raise, the Quarterzip agent offers the user through guides you've crafted; e.g. first-time onboarding, new-feature discovery, deeper technical support.
  </Step>
</Steps>

## Distribution

### Embedding the link in a button

The most common pattern is a plain anchor tag styled as a button. Keep the CTA copy action-oriented and clear that it starts a voice call:

```jsx theme={null}
<a href="https://app.quarterzip.ai/a/YOUR_AGENT_ID" target="_blank" rel="noopener noreferrer">
  Talk to an agent
</a>
```

<Tip>
  See [Best Practices](/best-practices) for guidance on CTA copy — phrases like "Talk to an agent" or "Join a call" consistently outperform generic labels like "Get help".
</Tip>

### Using the link in email CTAs

Quarterzip links work anywhere a URL is valid — including email. Drop the link into onboarding sequences, re-engagement campaigns, or post-trial follow-ups:

```jsx theme={null}
<a href="https://app.quarterzip.ai/a/YOUR_AGENT_ID">
  Book a 1:1 onboarding session →
</a>
```

### Linking from a help center

Add the agent link to help center articles as a contextual escalation path. Place it at the top for high-complexity topics, or at the bottom as a fallback:

```markdown theme={null}
Still stuck? [Talk to an onboarding agent](https://app.quarterzip.ai/a/YOUR_AGENT_ID) for live, step-by-step help.
```

### Linking from in-app empty states

Empty states are high-intent moments — the user is on a feature page but hasn't taken action yet. A Quarterzip link here offers guided help exactly when it's needed, and can be paired with a more persistent entry-point (e.g. a sidebar button) so users can return to the agent after their first session.

```jsx theme={null}
<div class="empty-state">
  <h3>No reports yet</h3>
  <p>Not sure where to start? An agent can walk you through it.</p>
  <a href="https://app.quarterzip.ai/a/YOUR_AGENT_ID" target="_blank">
    Get a guided walkthrough
  </a>
</div>
```

### Sharing links with multiple stakeholders

Because the Quarterzip link requires no login, it's easy for a buyer champion to forward it to other stakeholders. Anyone with the link can start a session. This makes it well-suited for:

* **Sales rooms** (Arrows, Dock) — embed the link so champions can share it internally
* **Proposals and decks** — add the link as a resource for evaluators who want a live demo
* **Slack or Teams messages** — paste the link directly into a channel for team onboarding

***

## Link API Reference

### URL Query Parameters

The Quarterzip agent link can receive additional information through the URL's query parameters. Providing a `userId` will allow users to skip the form on the agent's landing page.

| Parameter         | Description                                                                                                                                                                    |
| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userId`          | The user's unique identifier — typically their email address or your internal user ID                                                                                          |
| `userDisplayName` | The user's name or username to display <br />in the call log                                                                                                                   |
| `context`         | A free-text string input for providing additional context to the agent at the start of the call.<br />The value must be **URI-encoded** and is capped at **2,000 characters**. |

```javascript theme={null}
const agentUrl = new URL('https://app.quarterzip.ai/a/YOUR_AGENT_ID');
agentUrl.searchParams.set('userId', user.email);
agentUrl.searchParams.set('userDisplayName', user.displayName);

const context = `Plan: ${user.plan}. Country: ${user.country}. Signed up: ${user.createdAt}.`;
agentUrl.searchParams.set('context', context);

// e.g. https://app.quarterzip.ai/a/YOUR_AGENT_ID?userId=jane%40company.com&userDisplayName=Jane+Smith&context=Plan%3A%20Pro...
```

### Passing context to the agent

The agent link accepts a `context` query parameter — a free-text string the agent receives at the start of the call. Use it to pass information about the user so the conversation can be personalised without the user having to repeat themselves.

Use cases include:

* **Current plan** — so the agent knows what features are available
* **Country or locale** — for region-specific guidance
* **Handover notes** — if the user is being transferred from another tool like Intercom

The value must be **URI-encoded** and is capped at **2,000 characters**.