@supportwave/voice

Put a Supportwave voice agent in your own web page. The SDK is headless: it ships no markup and no CSS, and your UI drives it through events.

npm install @supportwave/voice

Quick start

import { createVoiceAgent } from "@supportwave/voice";

const agent = createVoiceAgent({ publishableKey: "swp_pub_…", agentId: "<agent id>" });

agent.on("state", (s) => (button.dataset.state = s)); // idle | connecting | listening | thinking | speaking | error
agent.on("transcript", ({ id, role, text, final }) => upsertLine(id, role, text, final));
agent.on("level", ({ input, output }) => orb.style.setProperty("--level", Math.max(input, output)));
agent.on("error", (e) => showMessage(e.code)); // e.g. mic_denied, voice_budget_exceeded, concurrency_limit_reached (all lines busy: retry shortly)

button.onclick = () => (agent.state === "idle" || agent.state === "error" ? agent.start() : agent.stop());

Call start() directly from a click, because it opens the microphone. The other methods are stop(), mute(true | false) and sendText(text). The tool and handoff events tell you what the agent is doing.

Handing over to a person

handoff fires when the agent escalates the call. The call's session is now waiting for a person, and the visitor carries on in chat. Pass the event to @supportwave/chat, created with the same key and agent id:

import { createChatAgent } from "@supportwave/chat";

const chat = createChatAgent({ publishableKey: "swp_pub_…", agentId: "<agent id>" });
chat.on("message", (m) => addPersonReply(m.content)); // the person's replies

agent.on("handoff", (h) => chat.attach(h)); // h has sessionId and sessionToken
// from here on: chat.send({ text }) reaches the person

After a handoff the visitor's messages are stored for the person and get no AI reply. What was said on the call is in chat.history().

React:

import { useVoiceAgent } from "@supportwave/voice/react";
const { state, transcript, level, error, muted, start, stop, mute } = useVoiceAgent({ publishableKey, agentId });

Setup

• Allowed origins. Add your site's origin to the publishable key's allowed origins in Supportwave. Calls from any other origin are refused.

• HTTPS. Browsers only allow the microphone on secure pages (and on localhost).

• Content Security Policy. If your site sends one, allow:

  • connect-src https://agents.supportwave.com wss://voice.agents.supportwave.com (the API, or your baseUrl's origin, and the voice gateway: the gateway_url origin the API returns)
  • script-src blob:: the microphone processor is an AudioWorklet that loads from a blob: URL

  Audio plays through Web Audio, so media-src needs no change. Since 0.2 the browser never connects to the voice model provider, so wss://api.x.ai is no longer needed.

What the browser sees

Since 0.2 the call runs through the Supportwave voice gateway. The agent's instructions and tool definitions stay on the platform: the page receives audio, transcripts and response status, plus calls to the clientTools it declared, and nothing else. The gateway also runs the agent's own tools, saves the transcript and meters the call, so closing the page (or stop()) is the whole hang-up.

Tools

The tools configured on the agent run on the Supportwave platform; the page is not told about them. To run one in the page instead, pass clientTools: { tool_name: (args) => result }. Only the names you pass are forwarded to the page. The arguments come from the model, so treat them as untrusted input.

A client tool is declared through an OpenAPI connection on the agent, so the model gets its schema. Mark the operation with "x-supportwave-client": true (and re-import the connection): a call reaches the page only when the agent marks the tool AND you pass it in clientTools, so a page can never take over one of the agent's server tools. The platform names it <connection>__tool_name; the SDK handles that prefix, so key clientTools by the plain tool_name.