Skip to main content

Allow cookies so we can count page views, see which pages and campaigns bring people here, and measure our ads on Meta, Google and LinkedIn. Cookie policy

Is there runnable example code for the VARTA API?

Yes. Four runnable examples live in this repository's examples/ directory, one per major shape of /v1 usage: a plain-text conversation, a phone call that actually dials, telephony provisioning, and a browser voice widget. Each is a complete, working project — fetch and the Node or browser standard library only, no @varta/* package to install — that you can download as a zip and run against your own VARTA instance in well under sixty seconds. The zips below are built from this same source at every deploy of this site, not hand-assembled once and left to drift, so what you download always matches what this page shows.

Prerequisites

Every example below needs the same three things:

  • A reachable VARTA instance and its base URL, including the /v1 prefix — e.g. https://your-varta-host/v1. Set it as VARTA_BASE_URL in each example's .env.
  • An agent id from the VARTA studio (VARTA_AGENT_ID). See Quickstart if you haven't built one yet.
  • Node 20 or later.

Each example also has its own .env.example to copy to .env, and its own README.md with a verified transcript of what happens when you run it — including what it prints when VARTA_BASE_URL is unset or unreachable, with no backend required to see that part.

01 — Text conversation CLI

Download varta-example-01-text-conversation-cli.zip

The fastest way to see the /v1 API work end to end: load an agent, type replies at a prompt, end the session. No audio, no telephony — proves the three-call shape from Quickstart (load → turn → end) actually works against a real agent, with trace.layer (which engine layer decided each reply) and cost.total_inr (that turn's spend) printed next to every line the agent says.

for await (const rawLine of rl) {
  const text = rawLine.trim()
  if (text === '/quit') break
  if (!text) continue

  const turn = (await api(`/sessions/${sessionId}/turn`, {
    method: 'POST',
    body: JSON.stringify({ text }),
  })) as TurnResponse

  // trace.layer names which decision layer of the engine produced the reply (a keyword match,
  // a rule, the LLM) -- see /docs/api/sessions. cost is this turn's spend.
  console.log(`agent [${turn.trace.layer}, ${fmtCost(turn.cost)}]: ${turn.text}`)

  if (turn.ended) {
    console.log('\n(the agent ended the session on this turn)')
    break
  }
}

02 — Outbound call

Download varta-example-02-outbound-call.zip

Places a real phone call (POST /v1/calls with "dial": true) and polls it to completion. What it actually proves is idempotency: a --ref you pass on the command line becomes a stable Idempotency-Key, so running the script twice with the same --ref replays the first call's response (Idempotency-Replayed: true) instead of dialling the same person twice — and the same key with a different request body comes back 409 idempotency_key_reuse rather than silently merging or redialling. Read this one before you write any retry logic near POST /v1/calls.

const idempotencyKey = `outbound-call:${ref}`

console.log(`Placing call to ${TO} (Idempotency-Key: ${idempotencyKey})`)

// "dial": true is set explicitly here -- POST /v1/calls is prepare-only by default (it loads
// the agent, pre-fetches context and pre-synthesises the opening line, but never rings
// anyone). Only "dial": true, against a deployment with a configured trunk, places the real
// SIP dial. This example exists to show that path, so it always sets it.
const body: Record<string, unknown> = { agent_id: AGENT_ID, to: TO, dial: true }
if (FROM) body.from = FROM
if (TRUNK_ID) body.trunk_id = TRUNK_ID

const placed = (await api('/calls', {
  method: 'POST',
  headers: { 'Idempotency-Key': idempotencyKey },
  body: JSON.stringify(body),
})) as CallResponse

03 — Telephony provisioning

Download varta-example-03-provision-telephony.zip

Registers a SIP trunk, registers a DID number with VARTA, and binds that number to an agent for inbound — the dial plan a deployment needs before POST /v1/calls can place a real call, or before it can answer one. It also proves the distinction that trips up first-time integrators: POST /v1/numbers registers a number you already hold with a carrier, it does not purchase or provision anything — buy the DID from your carrier first.

const trunk = (await api('/trunks', {
  method: 'POST',
  headers: { 'Idempotency-Key': uuid() },
  body: JSON.stringify(trunkBody),
})) as Trunk
console.log(`  trunk id=${trunk.id} has_credentials=${trunk.has_credentials}`)

const numberRecord = (await api('/numbers', {
  method: 'POST',
  headers: { 'Idempotency-Key': uuid() },
  body: JSON.stringify({ number: NUMBER, trunk_id: trunk.id }),
})) as NumberRecord
console.log(`  number id=${numberRecord.id}`)

const bound = (await api(`/numbers/${encodeURIComponent(NUMBER!)}/bind`, {
  method: 'POST',
  headers: { 'Idempotency-Key': uuid() },
  body: JSON.stringify({ agent_id: AGENT_ID }),
})) as NumberRecord
console.log(`  ${bound.number} now bound to agent_id=${bound.agent_id}`)

04 — Browser voice widget

Download varta-example-04-browser-voice-widget.zip

A single web page with a mic button: press it, speak, hear the agent reply. It proves two things at once. First, that POST /v1/sessions/{id}/turn takes transcribed text, not audio — VARTA does not do speech recognition on this path, so this widget uses the browser's own Web Speech API to produce a transcript itself, and is careful about a real gotcha in doing so: Chrome commonly reports confidence: 0 on a final result, which is not the same signal as "no confidence available" to the engine's low-confidence gate, so a bare 0 is never forwarded as stt_confidence. Second, that a browser client has to keep its API key server-side: server.mjs is a small allowlisted proxy that attaches Authorization to exactly the three routes this widget calls — the browser itself never holds the key.

const sttConfidence = typeof confidence === 'number' && Number.isFinite(confidence) && confidence > 0
  ? confidence
  : undefined
void submitTurn(text, sttConfidence)

Download all four

Download varta-examples.zip — all four examples in one archive, each nested under its own directory inside a single top-level varta-examples/ folder (varta-examples/01-text-conversation-cli/, varta-examples/02-outbound-call/, and so on), so extracting it doesn't scatter four projects' worth of files into wherever you extracted it.