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

# Embeds

> Add a hosted Protoface avatar to a website or share it with a direct link.

Embeds let people talk to one of your ready custom or stock avatars. Protoface
starts the conversation on the server, so you never need to put an API key in
your website's code.

You can publish an avatar in three ways:

| Option       | Use It When                                        |
| ------------ | -------------------------------------------------- |
| Share Link   | Send people a link they can open directly.         |
| iFrame Embed | Add the avatar directly to a page on your website. |
| Custom UI    | Build your own interface with `protoface-client`.  |

All three options use the same embed settings, usage credits, and conversation
limits.

## Start With the Default Embed

Every ready avatar has a default embed. It is enabled and works on any website,
so you can use its **Share Link** or **Embed Code** right away.

To find it:

1. Open **Avatars** in the [Protoface dashboard](https://app.protoface.com).
2. Find a ready avatar and select **Embed**.
3. The default embed appears under **Current Embed**.

From the Embed panel, you can change the intro headline and description,
placement, conversation limits, and domain restrictions. Select **Save Changes**
when you are finished.

An embed uses the avatar's voice and instructions. To change them, open the
avatar's **Avatar Settings**. Those settings apply anywhere the avatar is used.

## Create Another Embed

Select **New Embed** if you want different settings for another website,
environment, or campaign. New embeds start enabled with **Domain Restrictions**
off, just like the default embed.

To limit where an embed can run, open **Advanced Options** and turn on **Domain
Restrictions**. Add each permitted domain under **Allowed Website Origins**.
These entries are origins, not full page URLs. An origin contains only the
protocol, domain, and optional port.

| Accepted                | Not Accepted                |
| ----------------------- | --------------------------- |
| `https://acme.com`      | `https://acme.com/products` |
| `https://app.acme.com`  | `https://acme.com/*`        |
| `http://localhost:3000` | `*.acme.com`                |

Put one origin on each line. Do not add a path, query string, fragment, or
wildcard.

<Warning>
  When **Domain Restrictions** is off, the embed works on any website. This is
  convenient for testing, but we recommend limiting production embeds to the
  websites where you plan to use them. Each domain and subdomain must be added
  separately. Adding `https://acme.com` does not also allow
  `https://www.acme.com`.
</Warning>

## Share Link

Use the **Share Link** when you want to send someone directly to the avatar.
Copy or open it from the Embed panel.

The link opens a Protoface-hosted page, so there is nothing to add to a website.

## iFrame Embed

The iFrame embed is the quickest way to add an avatar to your site. Select
**Embed Code**, copy the code from the Embed panel, and paste it into your page:

```html theme={null}
<protoface-avatar embed-public-id="emb_..."></protoface-avatar>
<script src="https://app.protoface.com/embed-widget.js" async></script>
```

Choose a **Placement** before copying the code. **Inline** places the avatar in
the normal flow of your page. The four corner placements keep it visible in the
selected corner as visitors move through the page. The saved placement is
applied automatically wherever you use the embed code.

For an inline embed, the element fills the available width. The copied code
includes an aspect ratio based on the avatar's portrait. You can adjust its size
with CSS:

```css theme={null}
protoface-avatar {
  width: min(100%, 720px);
  aspect-ratio: 16 / 9;
}
```

### Respond to Embed Events

The iFrame embed can notify your page when something happens inside it. These
notifications are called browser events. You might use them to update text on
the page, record that a conversation started, or display a final transcript in
another part of your interface.

Events are optional. The embed works normally if your website does not listen
for them.

Each event is sent from the `<protoface-avatar>` element. The event's
`detail` property contains information about what happened. For example, this
updates a status message when a conversation starts and ends:

```html theme={null}
<p id="avatar-status">Ready to talk</p>

<script>
  const avatar = document.querySelector("protoface-avatar");
  const status = document.querySelector("#avatar-status");

  avatar.addEventListener("protoface-avatar:conversation-started", () => {
    status.textContent = "Conversation started";
  });

  avatar.addEventListener("protoface-avatar:ended", () => {
    status.textContent = "Conversation ended";
  });
</script>
```

The available events are:

| Event                                   | When It Happens                                                                      | Useful Details                       |
| --------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------ |
| `protoface-avatar:config-loaded`        | The embed finishes loading its settings.                                             | `enabled`, `avatarName`, `placement` |
| `protoface-avatar:consent-changed`      | The visitor changes the consent checkbox.                                            | `checked`                            |
| `protoface-avatar:conversation-started` | Protoface creates the conversation.                                                  | `room`, `expiresAt`                  |
| `protoface-avatar:live`                 | The conversation connects and is ready.                                              | `room`                               |
| `protoface-avatar:transcript`           | The visitor or avatar speaks. This may fire more than once as speech is transcribed. | `role`, `content`, `final`           |
| `protoface-avatar:ended`                | The conversation ends.                                                               | `reason`, `failed`                   |
| `protoface-avatar:error`                | The embed cannot complete an action.                                                 | `code`, `message`                    |
| `protoface-avatar:closed`               | The visitor hides a corner embed.                                                    | `reason`                             |
| `protoface-avatar:reopened`             | The visitor reopens a corner embed.                                                  | None                                 |

For transcript events, `role` is either `user` or `agent`, `content` contains
the transcribed speech, and `final` is `true` once that part of the transcript
is complete. The `room` value identifies the individual conversation.

You can listen on the `<protoface-avatar>` element or one of its parent
elements. Events can report activity, but they do not provide methods for
starting or controlling a conversation.

## Custom UI With Protoface Client

Use `protoface-client` when you want to design the whole interface yourself,
including consent, controls, avatar placement, transcripts, errors, and status
messages.

Start with the
[Protoface Conversations quickstart](https://github.com/protoface-ai/protoface-quickstart-conversations),
then replace its embed ID with the public ID from your Embed panel.

Your frontend only needs the public embed ID. Protoface still applies the saved
embed settings and account limits behind the scenes.

## What Visitors Experience

The iFrame embed and Share Link show the avatar portrait and intro. Before a
conversation begins, visitors are guided through consent and microphone access.
A custom UI presents the same steps in its own design.

Visitors can end a conversation at any time. The hosted options also explain
when an embed is disabled, has reached a limit, or is temporarily unavailable.

Conversation starts consume the embed owner's Protoface credits and count
toward the account's concurrent-session limits.

## Manage Access and Limits

* **Deactivate** stops new conversations but keeps the embed's settings.
* **Regenerate Link** creates a new public ID. Anything using the old ID will
  stop working, including iFrame embeds, custom UIs, and Share Links.
* **Starts per Hour** limits new conversations started through that embed.
* **Active per Visitor** limits simultaneous conversations by the same visitor.
* **Max Seconds** ends an individual conversation after the configured time,
  up to 3,600 seconds.

## Troubleshooting

Most embed issues can be resolved with a quick check in the Embed panel.

### Embed Display

If the avatar does not appear, open the Embed panel and check that it is
enabled. When **Domain Restrictions** is on, the website's origin should appear
under **Allowed Website Origins**. Leaving restrictions off can make testing
easier; you can add the origins before launching.

### Microphone Access

If the avatar cannot hear the visitor, the browser may simply need microphone
permission. Select the lock or settings icon beside the website address, allow
microphone access, and reload the page.

### Starting a Conversation

Give it a moment, then try again. If the conversation still does not start,
review **Starts per Hour** and **Active per Visitor** in the Embed panel. It may
also help to check **Billing** for the account's available credits.

### Older Links

The embed's public link may have been regenerated since the page was set up.
Open **Avatars**, select **Embed**, and copy the current **Share Link** or
**Embed Code**.

If you are still stuck, ask the person who manages your Protoface account or
[contact Protoface support](https://protoface.discourse.group/).