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

# Publish an agent

> Put a custom agent on your website or in your app, so people outside your workspace can chat with it

You can publish a [custom agent](https://superthread.com/docs/help/agents.md#custom-agents) so that people outside your workspace can chat with it — visitors to your website, or the signed-in users of your own app. It appears as a chat bubble you add to your site with one line of code. You decide what it can read and do, and when it can't help, it hands the conversation to your team as a card, with your replies showing up in the visitor's chat.

> [!NOTE]
>
> This is different from **Show on forms portal**, which lets people inside your workspace — guests included — chat with an agent on the [forms portal](https://superthread.com/docs/help/forms.md#forms-portal). Publishing is for people who aren't members of your workspace at all.

## Before you start

* **Who can publish.** You need to be a workspace admin or owner **and** have **Full access** to the agent. You also need edit access to everything you let the agent read. Built-in agents can't be published.
* **Who pays.** Every conversation runs on your workspace's [AI credits](https://superthread.com/docs/help/ai-credits.md). [Usage limits](#usage-limits) keep this predictable, and the defaults are deliberately conservative.
* **It starts switched off.** A new publication can only answer questions — from sources you choose — and create tickets, and it does nothing until you turn it on.

## Put a chat bubble on your website

This is the simplest setup: anyone visiting your website can chat with the agent, without signing in.

1. Open the agent's chat and click the **Settings** icon in the header.
2. Expand **Websites and apps (external users)** and click **Publish agent**.
3. Under **Who can chat**, keep **Anyone on your website** turned on.
4. Choose **What it can read**. Pick **Only what you choose** and add the spaces, projects, boards or pages the agent should answer from — the help docs or FAQs you'd want a customer to see. Until you add something, the agent has nothing to answer from.
5. Under **Websites it can appear on**, add your website's address, such as `https://www.example.com`.
6. Turn on **Active**.
7. Click **Save changes** at the top of the settings panel.
8. Under **Install chat bubble**, click **Copy embed code**, and paste it into your site's HTML just before `</body>`.

The embed code looks like this, with your own publication ID:

```html theme={null}
<script
  src="https://assets.superthread.com/agent-bubble/0.1.7/agent-bubble.js"
  data-api-origin="https://api.superthread.com"
  data-publication="apub_…"
  defer
></script>
```

> [!WARNING]
>
> Your website address must match exactly. `https://example.com` and `https://www.example.com` are different addresses, and so is a different port — add each one your visitors actually use. If the bubble doesn't appear, this is the first thing to check.

> [!NOTE]
>
> Changes to a publication are only saved when you click **Save changes**. **Publish agent**, and anything to do with apps and keys, save straight away.

### Customise the bubble

Add these attributes to the `<script>` tag to change how the bubble looks and behaves:

| Attribute | What it does | Values |
| - | - | - |
| `data-title` | The title shown in the chat window | Any text |
| `data-accent-color` | The bubble's main colour | A hex, `rgb()` or named colour |
| `data-position` | Which corner it sits in | `bottom-right` (default), `bottom-left` |
| `data-theme` | Light or dark | `auto` (default), `light`, `dark` |
| `data-launcher-icon` | The launcher icon | `chat` (default), `help`, `sparkles` |
| `data-launcher-label` | Text next to the launcher icon | Any text |
| `data-persistence` | Whether a chat survives a page reload | `memory` (default), `sessionStorage` |
| `data-open` | Open the chat when the page loads | `true`, `false` (default) |

> [!TIP]
>
> By default, a visitor's chat is lost if they reload or move to another page — including any reply from your team. Add `data-persistence="sessionStorage"` to keep the conversation for as long as the browser tab stays open. The bubble never uses cookies.

### If your site has a Content Security Policy

If your website sends a `Content-Security-Policy` header, allow `https://assets.superthread.com` in `script-src` and `https://api.superthread.com` in `connect-src`, or the bubble won't load.

## Choose what visitors can read and do

**What it can read** sets where the agent looks for answers:

* **Only what you choose** – just the spaces, projects, boards and pages you list. This is the safe choice for a public website.
* **Everything this agent can read** – everything the agent has access to, including anything it's given later. Superthread asks you to confirm before allowing this for anonymous visitors.

**What it can do** lists the actions the agent can take in a visitor chat. By default it can search and read the content you've chosen. Open **Developer settings** to add more, such as creating cards or searching the web, and for each action choose:

* who it's for — anyone on your website, people signed in to your app, or both,
* **Visitor confirms first** – the visitor approves that exact action before it runs,
* **Your team approves first** – someone with access to the agent approves it before it runs. **Default** requires approval whenever an anonymous visitor's chat would change something, except creating a ticket,
* **Allowed targets** – for actions that change things, where they're allowed to make changes.

Whenever a change would let anonymous visitors do more — read more, change more, or skip approval — Superthread spells out what's changing and asks you to confirm. The confirmation is recorded, and existing chats keep their current access.

> [!NOTE]
>
> The agent's instructions can shape how it answers, but they can't grant it access or let it skip approval. Only these settings do.

## Hand over to your team

When the agent can't help, it can create a card for your team. This needs a [form](https://superthread.com/docs/help/forms.md): in **Developer settings**, under **Handing over to your team**, choose a **Ticket form**. Until you do, the agent can't create tickets.

The agent fills in the form and the card is created on that form's board, one card per conversation.

* **Your replies reach the visitor.** Comments on that card appear in the visitor's chat, labelled as coming from your team.
* **Internal notes stay private.** Tick **Internal** in the comment box to keep a comment between your team.
* **Status updates** – for each list on the form's board, you can write a message the visitor sees when the card moves there. Moves to lists without a message stay private. Turn on **Resolves** for the lists that mean "done": reaching one ends the handover.
* **After your team replies** – choose whether the **Agent pauses** until the card is resolved (the default), or the **Agent keeps answering** alongside your team.

> [!WARNING]
>
> Every comment on a handover card is shown to the visitor unless you tick **Internal** first, and **Internal** is off by default. Make sure everyone who works these cards knows.

Anonymous visitors only see your reply while they're still in the same chat. They don't leave contact details, so there's no way to reach them afterwards. If follow-up matters, add an **Email** field to your ticket form, or set up [signed-in users](#signed-in-users-in-your-app).

## Signed-in users in your app

If your product has its own login, you can let your users chat with the agent as themselves. Their conversations are recorded against a [customer](https://superthread.com/docs/help/customers.md), and their tickets carry their name.

This needs a developer: your server has to vouch for each user.

1. In **Developer settings**, under **Apps**, click **Register app**. Choose how **Customers** are created — **One customer per person**, or **One customer per account** if your users belong to companies. This can't be changed later.
2. Copy the **signing secret**. It's shown once. Keep it on your server only — never put it in a website, app or chat.
3. **Link** the app to this publication, and turn on **People signed in to your app** under **Who can chat**.
4. On your server, after checking your own login, sign a short-lived token for the user and pass it to the bubble.

The token is an HS256 JWT signed with the app's secret, with the key ID as `kid`, and these claims:

| Claim | Value |
| - | - |
| `iss` | Your app ID |
| `aud` | The publication ID |
| `sub` | Your stable ID for the user |
| `account` | The user's company ID — for **One customer per account** apps |
| `name`, `email`, `account_name` | Optional, used to name the customer |
| `jti` | A unique ID — each token can only be used once |
| `exp` | At most 5 minutes after `iat` |

Then load the bubble with `data-auto-mount="false"` and start it once your user is signed in:

```html theme={null}
<script>
  function startSupportChat() {
    SuperthreadAgentBubble.mount({
      signIn: {
        appId: 'aapp_…',
        personKey: `${currentUser.id}@${currentUser.accountId}`,
        // Called on sign-in and every renewal. Each token is single use.
        getAssertion: async () => {
          const res = await fetch('/api/agent/identity-assertion', { method: 'POST', credentials: 'same-origin' });
          if (!res.ok) throw new Error('Not signed in');
          return res.text();
        },
      },
    });
  }
  window.SuperthreadAgentBubble
    ? startSupportChat()
    : window.addEventListener('superthread-agent-bubble:ready', startSupportChat, { once: true });
</script>
```

When the user signs out of your app, call `SuperthreadAgentBubble.bubble?.logout()`.

### Keys

* **Rotate key** creates a new secret and lets the old one keep working **For 1 hour**, **For 24 hours** or **For 7 days** while your server switches over — or **Stop now**.
* **Revoke key** and **Revoke app** take effect immediately and end every conversation they signed in, for every agent the app is linked to.

Apps are shared across your workspace; each publication chooses which ones to trust.

## What visitors see

Before the first message, visitors see a notice that they're talking to an AI agent, with a link to your privacy notice if you've added one. In the chat:

* the agent's replies are labelled **AI**, and your team's are labelled as human,
* they can rate answers as helpful or not,
* they confirm or reject actions that need their confirmation,
* they're told when an action is waiting for your team's approval.

Visitors can't upload or download files. Links in the agent's replies are shown as full addresses.

## Review conversations

Admins and anyone with **Full access** to the agent can open **Review conversations** from the publication's settings. It has four tabs:

* **Conversations** – every chat, filterable by date, audience, handover, rating, ticket and denied actions. Each shows the full transcript, the actions taken, and what it cost.
* **Approvals** – actions waiting for your team to approve.
* **Blocks** – conversations, people and networks you've blocked from chatting.
* **Metrics**

Deleting a conversation here also removes the visitor's name from any card or customer request it created.

## Privacy and data

In **Developer settings**:

* **Privacy notice link** and **Notice text** – what visitors see before their first message. Leave the text empty to use the default AI notice.
* **Show staff names on replies** – otherwise your team's replies appear as "Support team".
* **Show list names instead of status messages**
* **Links it can share** – limit clickable links in replies to certain domains.
* **How long chats are kept** – website visitors up to 90 days, signed-in people up to 365 days, counted from the last message. Cards and customer records the conversation created are kept, as they're part of your workspace.

## Usage limits

Every publication has daily caps, set in **Developer settings** under **Usage limits**:

| Limit | Default |
| - | - |
| Credits per day for website visitors | 5,000 |
| Credits per day in total | 20,000 |
| Chats per day from one network | 50 |
| Chats per day per visitor | 20 |
| Messages per minute per visitor | 10 |
| Longest message | 4,000 characters |
| Replies per chat | 50 |
| Tickets per day from one network | 5 |

Setting the website visitors' credits to 0 pauses anonymous chats without switching the publication off.

> [!NOTE]
>
> If anonymous visitors use up their daily credits on three days within a week, anonymous chat switches itself off until an admin turns it back on. People signed in to your app aren't affected.

## Turn it off or delete it

Turn off **Active** to stop new chats at any time. **Delete publication** disconnects every visitor and can't be undone; conversations are kept until their retention period runs out.

## Troubleshooting

* **The bubble doesn't appear.** Check that **Active** is on, that the page's exact address is listed under **Websites it can appear on**, and that your Content Security Policy allows the bubble.
* **The agent says it doesn't know anything.** Check **What it can read** — with **Only what you choose** and nothing added, it has nothing to answer from.
* **The agent never hands over.** Choose a **Ticket form** under **Handing over to your team**.
* **A visitor lost the conversation.** Add `data-persistence="sessionStorage"` to the embed code.

## Related

* [Agents](https://superthread.com/docs/help/agents.md) – creating and configuring custom agents
* [Customers](https://superthread.com/docs/help/customers.md) – where signed-in visitors and their requests are recorded
* [Forms](https://superthread.com/docs/help/forms.md) – the forms used for handover tickets
* [AI credits](https://superthread.com/docs/help/ai-credits.md) – how agent usage is charged


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.