Embeds

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:

Open Avatars in the Protoface dashboard.
Find a ready avatar and select Embed.
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.

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.

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:

<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:

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:

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

Get Started

Model Inference

Realtime

Account

Reference

Start With the Default Embed

Create Another Embed

iFrame Embed

Respond to Embed Events

Custom UI With Protoface Client

What Visitors Experience

Manage Access and Limits

Troubleshooting

Embed Display

Microphone Access

Starting a Conversation

Older Links

​Start With the Default Embed

​Create Another Embed

​Share Link

​iFrame Embed

​Respond to Embed Events

​Custom UI With Protoface Client

​What Visitors Experience

​Manage Access and Limits

​Troubleshooting

​Embed Display

​Microphone Access

​Starting a Conversation

​Older Links

Start With the Default Embed

Create Another Embed

Share Link

iFrame Embed

Respond to Embed Events

Custom UI With Protoface Client

What Visitors Experience

Manage Access and Limits

Troubleshooting

Embed Display

Microphone Access

Starting a Conversation

Older Links