@characterxyz/widget
Put your Character XYZ agent on any website: the character in the corner, text chat that streams, and real-time voice calls with a fair queue when every line is busy. One Web Component in a Shadow DOM, so it works in plain HTML, React, Vue, Svelte, Angular or anything else, and nothing of your page's CSS leaks in or out. 34 KB gzipped, everything included; it starts once the page is idle.
Create a publishable key, choose the sites it may run on and pick the look in Character XYZ › Settings › Developers.
Script tag (no build step)
<script src="https://unpkg.com/@characterxyz/widget@0/dist/cx.js" data-key="cxyz_pk_live_…" async></script>
Settings go on the tag as data-* attributes: data-display="full", data-accent="#e11d48",
data-position="bottom-left", data-mode="dark", data-show-call="false", data-agent="agent_…".
Drive it from your own buttons with CharacterXYZ.open('chat') or CharacterXYZ.open('call').
Binding the page
// Who this is / what is true now. Stays in scope for every later turn.
CharacterXYZ.identify({ id: 'u_42', name: 'Asha', traits: { plan: 'pro' } });
CharacterXYZ.setContext({ page: '/pricing', cart: { items: 2 } });
// Something they did. Only names the agent's graph declares.
CharacterXYZ.track('pricing_viewed', { plan: 'pro' });
// Something the agent may ask the page to do.
CharacterXYZ.registerAction('openCart', async ({ itemId }) => { cart.open(itemId); return { opened: true }; });
track is fire-and-forget (void), sends an idempotency id, and survives a
navigating click. An awaited page action runs your handler and posts the result
back on the same request; the agent's reply follows. The graph nodes are On
Site Event and Client Action.
npm
npm install @characterxyz/widget
import { mount } from '@characterxyz/widget';
const widget = mount({ publishableKey: 'cxyz_pk_live_…', accent: '#e11d48' });
widget.open('chat'); // or 'call'; widget.close(); widget.destroy()
Using React or Next.js? Install @characterxyz/react
instead; it includes this package.
Settings
The defaults come from the key (set on the Embed page); anything passed here overrides them for this site.
| Setting | Values |
|---|---|
agentId | Which of the key's agents. Default: the key's first |
display | bubble · half · full (how much of her shows) |
launcher, position | Launcher style; bottom-right · bottom-left |
accent, mode, radius, font | Colour, auto · light · dark, corner radius, font family |
showChat, showCall, branding | Turn chat, calls or the footer off |
offsetX, offsetY, zIndex, container | Placement |
movable | Visitors can drag her anywhere along the bottom (hold first on touch); let go higher up and she falls back down. The chat then opens from where she stands. Off by default |
What the agent says (persona, knowledge, greeting) is the agent's own, set in Character XYZ.
Styling
CSS tokens on the element: character-xyz { --cx-accent: …; --cx-font: …; --cx-radius: … }. Parts:
::part(launcher | presence | actions | panel | header | composer | banner | message | message-agent | message-visitor | message-event | event | greeting).
Events
The element fires bubbling events: cx-ready, cx-open, cx-close, cx-call ({phase, position, endReason}) and cx-error.
Signed-in visitors
Mint the session on your server with @characterxyz/server,
then: mount({ getSessionToken: () => fetch('/api/characterxyz/session').then((r) => r.json()) }).
Their chat history then follows them across devices.
Security
A publishable key (cxyz_pk_…) is public by design: it works only from the sites listed on it and
exchanges for a 15-minute session bound to that site. Never put a secret key (cxyz_sk_…) in a page;
the SDK refuses to run with one.
License
MIT