Examples
The smallest server that starts a call, listens to it and checks webhooks, and the smallest page that talks.
Two small examples show the whole flow: a server that holds the secret key, and a page with <Conversation>. They live beside the SDKs in our repository (packages/examples/).
The examples come out with the SDK packages, once the product has its name. This page shows what they do and how they run.
The server
No framework, Node 22+. Two routes:
| Route | What it does |
|---|---|
POST /api/calls | Starts a call with the secret key (POST /v1/calls), passing on the page's Idempotency-Key; listens to it on events_url; answers the page forBrowser(start), without the events socket |
POST /webhooks | Checks a webhook's signature with readWebhook, answers 204 at once, skips an event it has already seen, and logs it |
const answer = await fetch(`${API_BASE}/v1/calls`, {
method: "POST",
headers,
body: JSON.stringify({ character_id: CHARACTER_ID, metadata: { from: "example" } }),
});
if (!answer.ok) {
// Our refusals are { error: { code, message } }; 429s say when to try again.
const body = await answer.json().catch(() => null);
const retry = answer.headers.get("retry-after");
return send(res, answer.status, body, retry ? { "retry-after": retry } : {});
}
const start = await answer.json();
if (start.events_url) watch(start.id, start.events_url);
send(res, 200, forBrowser(start));While the call runs it logs the transcript, each tool the character used and how the call ended, from the live events socket. Once connected, where the call takes it, it gives the character a note with context.
Its settings
| Variable | What it is |
|---|---|
ACME_SECRET_KEY | A secret key, sk_test_… or sk_live_…. Required |
ACME_CHARACTER_ID | The character to call (chr_…). Required |
ACME_WEBHOOK_SECRET | An endpoint's signing secret (whsec_…). Without it, /webhooks isn't served |
DAXOV_API_BASE | The API's address (default https://api.daxov.com) |
PORT | Where it listens (default 3000) |
The page
A Vite page with one <Conversation>. It asks the example server for the call, with a fresh Idempotency-Key for each attempt, so a retried request gets the same call back instead of a second:
import { Conversation, type BrowserCallStart } from "@daxov/react";
import "@daxov/react/theme.css";
async function getCallStart(): Promise<BrowserCallStart> {
const res = await fetch("/api/calls", { method: "POST", headers: { "idempotency-key": crypto.randomUUID() } });
const body = await res.json().catch(() => null);
if (!res.ok || !body) throw new Error(body?.error?.message ?? "The call couldn't start. Try again in a minute.");
return body;
}
export function App() {
return (
<Conversation name="Alex" getCallStart={getCallStart}>
<p className="conversation-note">Your microphone is used only while the call is on.</p>
</Conversation>
);
}Its dev server runs on http://localhost:5173 and sends /api to the example server on port 3000.
Run them
ACME_SECRET_KEY=sk_test_… ACME_CHARACTER_ID=chr_… ACME_WEBHOOK_SECRET=whsec_… pnpm --filter acme-example-server start
pnpm --filter acme-example-page dev # http://localhost:5173Use a test key: test calls are real calls, at most 60 seconds, never charged. To receive webhooks on your machine, the endpoint's address must be public https: see Webhooks.