Embed

The <speechify-agent> web component is the shortest path from “I have an agent ID” to “my users are talking to it on my landing page”. One script tag, one element, no realtime plumbing to wire up.

1
<script src="https://api.speechify.ai/v1/widget/agents.js"></script>
2
<speechify-agent agent-id="a_01HS..."></speechify-agent>

That’s the whole integration for a public agent. Private agents use the same tag with a server-minted session token (see below).

Two modes

Public agent (direct embed)

Flip the Public toggle on the agent’s Embed tab in the console, add the domains you want the widget to work on to the origin allowlist, and paste the snippet into your page. The widget calls POST /v1/agents/{id}/sessions unauthenticated; the server verifies that Origin matches your allowlist before minting a session.

1
<script src="https://api.speechify.ai/v1/widget/agents.js"></script>
2
<speechify-agent agent-id="a_01HS..."></speechify-agent>

Use this for marketing sites, demo pages, and anywhere the agent conversation is the product itself.

Security

• Embed only works from origins you explicitly allowlist on the agent. An empty allowlist with the public toggle on means “any origin accepted” — intended for open demos; enable deliberately.
• No subdomain wildcards. Add each origin exactly (e.g. https://app.example.com, https://www.example.com).
• The session endpoint is per-IP rate-limited. Repeat abuse from one source is throttled without affecting legitimate users.
• The agent owner is always the billed principal regardless of who triggered the session.

Private agent (server-minted token)

Keep the agent private, mint a short-lived session token on your backend with your API key, and pass it to the widget. The API key never reaches the browser.

1
# On your backend (Flask / FastAPI / etc).
2
from speechify import Speechify
3
4
client = Speechify()  # uses SPEECHIFY_API_KEY
5
6
session = client.tts.agents.create_session(id=agent_id)
7
# Return session.url + session.token to your browser via your own API.

Browser side:

1
<script src="https://api.speechify.ai/v1/widget/agents.js"></script>
2
<speechify-agent
3
  session-token="<token from your backend>"
4
  session-url="<url from your backend>">
5
</speechify-agent>

Attributes

Events

The element emits CustomEvents you can listen for with addEventListener:

1
<speechify-agent id="agent" agent-id="a_01HS..."></speechify-agent>
2
<script>
3
  const el = document.querySelector("#agent");
4
  el.addEventListener("status", (e) => console.log("status:", e.detail));
5
  el.addEventListener("message", (e) => console.log(e.detail.role, e.detail.text));
6
</script>

Programmatic API

For React/Vue/Svelte apps that don’t want the default button UI, import the ESM bundle and call startAgent directly:

1
import { startAgent } from "https://api.speechify.ai/v1/widget/agents.mjs";
2
3
const handle = await startAgent({
4
  agentId: "a_01HS...",
5
  onStatus: (s) => console.log("status:", s),
6
  onMessage: (m) => console.log(m.role, m.text),
7
  onError: (err) => console.error(err),
8
});
9
10
// Client tools attached to the agent route here:
11
handle.registerTool("navigate_to", (args) => {
12
  window.location.hash = String(args.section);
13
});
14
15
await handle.setMicEnabled(false); // mute
16
await handle.stop(); // tear down

Styling

The component uses Shadow DOM so your page’s CSS can’t leak in. Light theming is exposed through CSS custom properties on the host:

1
speechify-agent {
2
  --speechify-agent-bg: #0a0a0a;
3
  --speechify-agent-fg: #ffffff;
4
  --speechify-agent-accent: #6366f1;
5
  --speechify-agent-muted: #71717a;
6
  --speechify-agent-radius: 9999px;
7
}

Need more control than that? Use the programmatic API and build your own UI on top of the returned AgentHandle.

What’s next