Embed element

@spekoai/embed ships one custom element, <speko-voice>. It renders a docked launcher, a transcript panel and mute, connects through VoiceConversation, and takes no framework. Point it at a URL on your own backend that mints the session:

<script type="module">
  import '@spekoai/embed';
</script>

<speko-voice token-endpoint="/api/speko-session" dock="bottom-right"></speko-voice>

Importing the package registers the element. The package is marked sideEffects: true so a bundler cannot tree-shake that registration away.

npm install @spekoai/embed

Attributes

Everything else on the element is either refused or ignored.

The token endpoint

The element sends POST to token-endpoint with accept: application/json and no request body. The endpoint runs on your origin and already knows who the visitor is from its own session. The page has nothing to contribute, and deliberately no channel through which it could.

Answer with a JSON object:

Validation is strict, and it catches two mistakes early: a backend that proxies the whole POST /v1/sessions response, and one that returns an HTML error page with a 200.

// POST /api/speko-session — your server, your session cookie
export async function POST(request: Request) {
  const candidate = await currentUser(request); // your auth, not Speko's

  const session = await fetch('https://api.speko.dev/v1/sessions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SPEKO_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      mode: 'cascade',
      agentId: process.env.SPEKO_AGENT_ID,
      variables: { candidate_first_name: candidate.firstName },
    }),
  }).then((r) => r.json());

  // Forward these three and nothing else.
  return Response.json({
    transportToken: session.transportToken,
    transportUrl: session.transportUrl,
    sessionId: session.sessionId,
  });
}

Everything that shapes the call is bound in that mint call, before a transport token exists — the agent, per-session variables, tool credentials and webhook tags.

Attributes it refuses

The element presents a session; it never configures one. The attributes below are refused, not ignored: the element paints the reason into the panel, names the attribute, and will not dial. An ignored attribute teaches an embedder nothing — they ship, it looks fine, and the value quietly never reaches the agent.

The concrete case this was designed against is an interview widget on a job application page. If variables were an attribute, the candidate would be the one supplying their own name — and their own scoped tool token.

Each belongs in the POST /v1/sessions call your token-endpoint makes, where the visitor cannot reach it. The list covers the migration surface — the attributes someone moving off another vendor's widget would copy across, plus the Speko-shaped equivalents.

States

The current state is readable as element.state and mirrored to a data-state attribute you can style against.

Events

All four bubble and cross shadow boundaries, so you can listen on document.

const widget = document.querySelector('speko-voice');

widget.addEventListener('speko-connect', (event) => {
  analytics.track('voice_call_started', { sessionId: event.detail.sessionId });
});

widget.addEventListener('speko-error', (event) => {
  console.error(event.detail.code, event.detail.message);
});

JavaScript API

start(), stop() and setMuted() report their own failures through speko-error, so a rejected promise is not the channel to watch.

await document.querySelector('speko-voice').start();

Theming

The element renders into a shadow root, so page CSS cannot reach inside it. Theming is by custom property, set on the element or on any ancestor. Defaults live on :host at single-class specificity, which means one declaration of your own wins.

Colours have a dark-scheme default under prefers-color-scheme: dark, so overriding one value in light mode only will show through in dark mode.

Motion is four durations and three easings: --speko-dur-instant (100ms), --speko-dur-fast (150ms), --speko-dur-base (200ms), --speko-dur-slow (300ms), --speko-ease-standard, --speko-ease-out, --speko-ease-in. Under prefers-reduced-motion: reduce the durations drop to 1ms and the widget stops moving without changing shape.

speko-voice {
  --speko-accent: #0f766e;
  --speko-radius: 8px;
  --speko-panel-width: 400px;
}

Icons are inline SVG and there are no webfonts or remote assets, so the widget renders under a strict Content-Security-Policy without changes on your side.

Errors

Every code below arrives as event.detail.code on speko-error. The element never rejects a promise at you — the same codes are exported as the EmbedErrorCode type if you want to switch on them in TypeScript.

Next