Embed SDK - Freya Documentation

Overview

The Freya Client SDK connects a Freya agent directly from the browser. You build whatever UI you want; the SDK handles WebRTC transport, microphone input, remote audio playback, and the real-time event stream between the page and the agent. The SDK is loaded as a script tag — no build step or package manager required.

How it works

The connection flow has two parts: your backend mints a short-lived token, and the browser uses that token to open a WebRTC session.

The user does something on your page that should start a session (a button click, a page load, etc.)
Your page calls your own backend — never the Freya API directly
Your backend calls POST /api/token/embed with your API key and returns the token to the browser
The browser passes the token to FreyaClient, which connects to the agent over WebRTC
Events fire as the conversation unfolds — transcripts, speaking state, tool calls — and you handle them however your UI needs

The API key never reaches the browser. The token is scoped to a single session and expires on its own.

Minting a token

Token minting must happen server-side. The API key used must have the Issue web call tokens permission (calls:web-token), which allows it to mint tokens for in-browser calls and external embed integrations. You can set this when creating a key from the API Keys button in the sidebar.

import requests

@app.get("/api/assistant-token")
def assistant_token(request: Request):
    resp = requests.post(
        f"{FREYA_BASE_URL}/api/token/embed",
        json={
            "agentId": AGENT_ID,
            "allowedOrigin": f"{request.url.scheme}://{request.headers['host']}",
            "ttlSeconds": 300,
        },
        headers={"Authorization": f"Bearer {API_KEY}"},
    )
    resp.raise_for_status()
    return resp.json()

app.get('/api/assistant-token', async (req, res) => {
  const resp = await fetch(`${process.env.FREYA_BASE_URL}/api/token/embed`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.FREYA_API_KEY}`,
    },
    body: JSON.stringify({
      agentId: process.env.FREYA_AGENT_ID,
      allowedOrigin: `${req.protocol}://${req.get('host')}`,
      ttlSeconds: 300,
    }),
  });
  res.json(await resp.json());
});

The response contains token, expiresAt, and baseUrl. Pass all three to FreyaClient.

If your users are behind firewalls or strict NAT, also fetch TURN credentials server-to-server from GET /api/token/webrtc/ice-servers and forward them alongside the token. This saves a round-trip from the browser and keeps TURN credentials off the client.

Installation

Add the script to your page. The SDK is served directly from the Freya dashboard:

<script src="https://app.freyavoice.ai/freya-client.js"></script>

This exposes window.Freya.FreyaClient globally. No build step, bundler, or package manager is needed.

Quick start

<script src="https://app.freyavoice.ai/freya-client.js"></script>
<script>
  const { FreyaClient } = window.Freya;

  async function startSession() {
    const { token, baseUrl, iceServers } = await fetch('/api/assistant-token')
      .then(r => r.json());

    const client = new FreyaClient({ baseUrl, token, iceServers });

    client.on('stateChanged', (state) => {
      console.log('state:', state); // connecting → connected → ready
    });

    client.on('botTranscript', ({ text }) => {
      appendMessage('agent', text);
    });

    client.on('userTranscript', ({ text, final }) => {
      if (final) appendMessage('user', text);
    });

    await client.connect();
  }
</script>

Configuration

Option	Type	Required	Default	Description
`baseUrl`	`string`	Yes	—	Freya API origin returned by the token endpoint
`token`	`string`	Yes	—	Short-lived embed JWT
`mode`	`"call"` \| `"chat"`	No	`"call"`	`"call"` activates the microphone; `"chat"` is text-only
`metadata`	`Record<string, unknown>`	No	`{}`	Arbitrary key-value pairs forwarded to the agent session
`customerVariables`	`Record<string, string>`	No	`{}`	Variables injected into the agent’s system prompt at runtime
`iceServers`	`RTCIceServer[]`	No	`[]`	TURN/STUN servers for production deployments

Modes

Call mode

The microphone is activated when connect() resolves. The agent hears the user in real time and responds with voice. This is the default.

const { FreyaClient } = window.Freya;
const client = new FreyaClient({ baseUrl, token }); // mode: "call" by default

Chat mode

The microphone stays off. Send text with sendMessage() and listen to botLlmText or botTranscript for the agent’s response. If the agent has TTS configured, audio is still played.

const { FreyaClient } = window.Freya;
const client = new FreyaClient({ baseUrl, token, mode: 'chat' });
await client.connect();
await client.sendMessage('What are your opening hours?');

Token lifecycle

Tokens expire after ttlSeconds (default 300 seconds). Mint a fresh one each time the user starts a new session rather than caching across page loads.
Set allowedOrigin on the server to the exact origin of the embedding page. The Freya backend rejects WebRTC connection attempts from other origins.
Tokens are single-use for establishing a session. Once a session is open the token is consumed.

Next steps

Client Reference

Full reference for all FreyaClient methods, events, and their payloads.

Agents

Configure the agent your embed session connects to — voice, system prompt, and tools.

​Overview

​How it works

​Minting a token

​Installation

​Quick start

​Configuration

​Modes

​Call mode

​Chat mode

​Token lifecycle

​Next steps

Client Reference

Agents

Overview

How it works

Minting a token

Installation

Quick start

Configuration

Modes

Call mode

Chat mode

Token lifecycle

Next steps