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

# Embed options

> Every attribute the widget script tag understands.

## One script tag

The dashboard's Share page writes the tag for you. This is what it can carry:

```html theme={null}
<script src="https://app.pepline.ai/widget/pepline.js"
  data-agent-public-key="pk_…"
  data-embed-mode="popover"
  data-open-button-text="Ask us anything"
  data-open-button-icon="message-circle"
  async></script>
```

Everything but the key is optional. Attributes are the whole embed configuration: nothing about the placement is stored server-side, so two pages can carry the same agent with different settings.

## Attributes

### Identity

| Attribute               | Values          | What it does                                                                                                      |
| ----------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------- |
| `data-agent-public-key` | the agent's key | Required. Which agent this embed talks to.                                                                        |
| `data-embed-id`         | a short name    | Names the embed so host-page triggers can address it (`data-pepline-for="pricing"`) when several sit on one page. |
| `data-api-origin`       | a URL           | The API origin, defaults to the script's own. Self-hosting and local development only.                            |

### Placement

| Attribute               | Values                                         | Applies to                  | What it does                                                                            |
| ----------------------- | ---------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------- |
| `data-embed-mode`       | `inline` `popup` `slider` `popover` `side-tab` | all                         | How the chatbox appears. Unset: an inline card when a container exists, else a popover. |
| `data-inline-target`    | CSS selector                                   | inline                      | The element the card renders into, default `#pepline`.                                  |
| `data-inline-height`    | pixels                                         | inline                      | The card's height, default auto.                                                        |
| `data-popup-size`       | `s` `m` `l`                                    | popup                       | The modal's width.                                                                      |
| `data-chatbox-position` | `left` `right`                                 | slider · popover · side-tab | Which side the chatbox and its button sit on.                                           |

### The open button

| Attribute                        | Values                                         | What it does                                                                                                                |
| -------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `data-open-button`               | `button` `none`                                | `none` hides the floating button; the page opens the chatbox from its own link (`[data-pepline-open]` or `Pepline.open()`). |
| `data-open-button-text`          | text                                           | The button's label. Takes locale twins: `data-open-button-text-fr`.                                                         |
| `data-open-button-color`         | a CSS color                                    | The button's color before the agent's theme loads.                                                                          |
| `data-open-button-icon`          | a [Lucide](https://lucide.dev/icons) icon name | An icon next to the label.                                                                                                  |
| `data-open-button-icon-position` | `before` `after`                               | Where the icon sits, default before.                                                                                        |

### The close button (popover)

While a popover is open, its button becomes the close control.

| Attribute                | Values               | What it does                                            |
| ------------------------ | -------------------- | ------------------------------------------------------- |
| `data-close-button-mode` | `text` `icon` `both` | The word Close (default), a round icon button, or both. |
| `data-close-button-icon` | a Lucide icon name   | The icon it shows, default `x`.                         |

### Opening on its own

| Attribute                     | Values                               | What it does                                                                                  |
| ----------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------- |
| `data-chatbox-open`           | `load` `exit` `scroll:30` `delay:20` | Opens the chatbox on page load, on exit intent, past a scroll percentage, or after N seconds. |
| `data-chatbox-prevent-reopen` | `true`                               | Once a visitor closed it, an automatic trigger stays quiet for the tab.                       |

### Copy on this page

These change what the start card says on this placement only. They never reach the agent.

| Attribute          | Example                             | What it does             |
| ------------------ | ----------------------------------- | ------------------------ |
| `data-start-text`  | `"Ask about our pricing"`           | The start card's button. |
| `data-start-hint`  | `"Answers come from our own pages"` | The line under it.       |
| `data-placeholder` | `"Your question…"`                  | The input's placeholder. |

Each takes locale twins (`data-start-text-fr`, `data-placeholder-de`, any two-letter code), shown to visitors resolved to that locale.

### Context and identity of the conversation

| Attribute      | Example                             | What it does                                                                                                                                           |
| -------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-context` | `'{"page":"pricing","plan":"pro"}'` | A JSON object of facts about the visitor's situation the agent may use (page, plan, product). Merge more at any time with `Pepline.setContext({...})`. |
| `data-thread`  | `"pricing"`                         | A conversation-thread scope. Embeds sharing a key share one thread; a scope isolates this embed's thread, and the same scope on two pages shares one.  |
| `data-source`  | `"www-pricing"`                     | An attribution label stored on the conversation.                                                                                                       |
| `data-locale`  | `"fr"`                              | The chrome's language; defaults to the browser's.                                                                                                      |
| `data-manual`  | `"true"`                            | Skip the automatic mount; drive the embed through `window.Pepline.mount`.                                                                              |

## Host-page triggers

Any element with `data-pepline-open` opens the chatbox; one with `data-pepline-ask="…"` opens it and sends that question. With several embeds on a page, the trigger or any ancestor names its embed with `data-pepline-for="<embed id or selector>"`.