Guides / Embed a persona
Embed a persona on your website
Built a persona in the portal? Put it on your own website with one line of HTML. Visitors click, allow their microphone, and talk to the persona without leaving your page or signing in to anything. Only the websites you name can show it: any other site gets a blank frame from the browser.
In three steps
- Publish the persona. Open it in the portal (Personas), then press Publish. An embed always shows a published version, never your draft.
- Name your websites. On the Share tab, under Embed on your website, add every address your visitors use, then press Create embed.
- Paste the snippet. Press Copy snippet and paste it into your page,
just before the closing
</body>tag. That is all.
The snippet looks like this:
<script src="https://avatar.zeligate.ai/embed/v1.js" integrity="sha384-JuMMLzkxc0by0j5MbHE6WMM6i7qZswryw7AYez/wIygcWgQymQA7OkvnLPgduRLv" crossorigin="anonymous" data-persona-link="lnk_YOUR_LINK_ID" async></script>It names the embed's link id and nothing else. The link id is not a secret: it is in the source of every page that shows the persona. What protects the persona is the list of websites you named, checked by the visitor's own browser.
Use Show live preview on the Share tab to try the real embed before you paste it anywhere. The preview works only for you, signed in to the portal: anyone else who opens the embed's address on our site directly sees a short note that it lives on its owner's website.
The loader is versioned and pinned
/embed/v1.js never changes once published. The integrity attribute is its
SHA-384 hash, so the visitor's browser refuses to run the loader if a single
byte differs from what you pasted, and crossorigin="anonymous" lets the
browser check it. The hash for v1 is:
sha384-JuMMLzkxc0by0j5MbHE6WMM6i7qZswryw7AYez/wIygcWgQymQA7OkvnLPgduRLvWhen the loader improves, it ships as a new version (/embed/v2.js) with its
own hash, and your pasted v1 snippet keeps working exactly as before. Copy a
new snippet from the Share tab when you want the new version.
Pasted a snippet before versioning, pointing at /embed.js? It keeps working.
That address always serves the current loader, with no integrity pin; switch to
the v1 snippet when convenient.
Which websites to add
Add the address visitors see in their address bar, without a path:
| You type | It allows |
|---|---|
https://www.example.com | exactly https://www.example.com |
https://example.com | exactly https://example.com (add both if you use both) |
https://*.example.com | every subdomain, such as https://shop.example.com and https://a.b.example.com, but not https://example.com itself |
https://www.example.com:8443 | that site on that port only |
http://localhost:3000 | your own machine, for testing |
Refused, with a sentence beside the field saying why: a path or query
(https://example.com/shop), plain http for anything but localhost and
127.0.0.1, a wildcard anywhere but a whole leftmost label (*,
https://*.com, https://shop*.example.com), and more than ten websites on
one embed.
How it appears
Pick one on the Share tab; the snippet changes to match.
| Layout | What visitors see | Snippet attribute |
|---|---|---|
| Floating button (default) | A round button in the bottom corner. It opens the persona in a panel and closes with the button or the Escape key. | none |
| In the page | The persona where you put the script tag, as part of your page. | data-layout="inline" |
Optional attributes, all on the same <script> tag:
| Attribute | Default | What it does |
|---|---|---|
data-layout | bubble | bubble or inline |
data-position | right | left puts the button in the bottom left corner |
data-width | 380 | frame width in pixels (280 to 960) |
data-height | 600 | frame height in pixels (360 to 1000) |
data-label | Talk to us | the button's text |
data-accent | a Zeli purple | the button's colour, a hex colour such as #3355ff |
The persona's own light, dark and accent settings come from the embed's theme, never from your page's CSS.
What happens when a visitor talks
- The loader adds one iframe of
https://avatar.zeligate.ai/e/<link id>to your page. It makes no request of its own, sets no cookie and reads nothing from your page except its origin. - The iframe page is served with
Content-Security-Policy: frame-ancestorsnaming your websites, so the browser refuses to show it anywhere else. - When the visitor presses Start, the page asks for their microphone (the
iframe carries
allow="microphone; camera; autoplay"), proves it is a real browser, and asks for a session. The server checks the embedding website against your list again, then connects the visitor to the persona. - Before Start the visitor reads a short notice: "This conversation, including your voice, is recorded and transcribed." The recording keeps the avatar's picture and voice and the visitor's voice, never their camera. A muted visitor is not recorded while muted.
- Every session is listed on the persona's Sessions tab, and its record keeps the website it came from.
The same limits as a share link apply: availability windows, the queue when every slot is busy, per visitor limits and your monthly minutes.
Change or remove an embed
- Remove an embed on the Share tab. The persona disappears from every website that shows it at the next page load. Create a new embed to bring it back; the new one has a new link id, so update your snippet.
- Publish a new version and every embed on "latest" serves it straight away. Your snippet does not change.
Troubleshooting
| You see | Why | Fix |
|---|---|---|
| A blank frame, or the browser's "refused to connect" page | The website is not on the embed's list | Add the exact address on the Share tab (mind www and the port) |
| "This link is not available" | The embed was removed, or the persona archived | Create a new embed and update the snippet |
| Start does nothing on a phone | The microphone prompt was dismissed | Allow the microphone for your site in the browser settings |
| The button does not appear | The script tag is missing its data-persona-link, or it is not a whole link id | Paste the snippet exactly as copied |
| The button does not appear, and the browser console mentions integrity | The integrity value was edited, or the src changed without it | Paste the snippet exactly as copied; the hash belongs to that exact src |
| "This persona is embedded on its owner's website" | The embed's address was opened directly instead of inside your page | Visit your own page that holds the snippet |
Share links and embeds
A share link (/p/<link id>) is a page on our site you send to people. It
can never be shown inside another website. An embed is for your own
website, and only works on the websites you named. A persona can have both.