Made in 10Docs
GuidesAPI
Calls

Calls

Start a live call from your server, hand the browser its ticket, follow the call and end it.

A call is one live conversation between a person and one of your characters. Your server starts it with a secret key; the person's browser or app connects to its sound; your server can listen to it as it happens. When it's over, it is settled: its charge, transcript, analysis and recording are on the call.

Start a call

POST/v1/calls

Prop

Type

Send an Idempotency-Key header so a retry never starts a second call. See Idempotency.

curl https://api.daxov.com/v1/calls \
  -H "Authorization: Bearer $ACME_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c7a52-3d1e-4b8a-9f61-2c4d8e7b9a10" \
  -d '{
    "character_id": "chr_4fT9kQ2mXw7LbN3pZs8V",
    "metadata": { "ticket": 7 },
    "memory_key": "user_42"
  }'

It answers 201 with where to connect:

CallStart
{
  "id": "call_2Gx7Mb9KpQ4sVn1ZrT6e",
  "status": "waiting",
  "character_id": "chr_4fT9kQ2mXw7LbN3pZs8V",
  "max_seconds": 300,
  "ws_url": "wss://api.daxov.com/live/a1b2c3d4?token=1793300300.k3Jx9Q…",
  "events_url": "wss://api.daxov.com/live-events/a1b2c3d4?token=ev.1793300420.k3Jx9Q…",
  "ws": {
    "path": "/live/a1b2c3d4",
    "token": "1793300300.k3Jx9Q…",
    "input_rate": 16000,
    "output_rate": 24000,
    "face": null,
    "events": { "path": "/live-events/a1b2c3d4", "token": "ev.1793300420.k3Jx9Q…" }
  },
  "created_unix": 1793300000
}
  • ws_url is the call's sound, for the person's browser or app. It connects within 120 seconds; its token works once and for 5 minutes. See The sound socket.
  • ws is the same ticket in parts, with the sample rates. ws.face is null for a voice-only character; with a face it says where the face plays and how to feed it the voice. Our browser SDK handles every face.
  • events_url is the call's live events and control, for your server only. See Live events and control.

Keep events_url on your server

Whoever holds events_url can read the transcript, make the character say anything, and end the call. Send the browser the CallStart without it (and without ws.events). The SDK's forBrowser(start) does that for you.

What is checked

In order: the body (metadata, memory_key), the Idempotency-Key, max_seconds. Then, under your organization's lock: the organization, its calls at once, the character, its tier; for a test key, its 20 calls a day; for a paid organization, the tier's price and the balance.

Then the call starts. If it can't, the call is settled at once with nothing charged and the answer is 503 (call_not_started or engine_unavailable). A call.ended webhook with reason: not_started still goes out, and no call.started.

How long it runs

max_seconds is the least of what you ask, the character's max_call_seconds, 60 seconds for a test key, and what your plan minutes and balance cover. On a paid organization, less than 30 seconds is refused with 402 insufficient_balance. The call ends at max_seconds, so the balance can't run out mid-call. See Limits.

What it costs

  • Billed seconds run from when the person's side connected to the end, rounded up: at least 30, at most max_seconds.
  • They are charged at the price of the character's tier: your plan's minutes first, then your balance.
  • Nothing is charged for a call that failed on our side, never connected, or never played a reply.
  • Test calls are never charged.

When the call starts, what it could cost is held on your balance; when it settles, only the billed seconds are charged. A call is settled once: a retry or a restart on our side never charges twice.

Coming soonBuying credit

Buying credit and plans in the dashboard is coming soon. For now, we add credit to your organization for you.

Follow a call

GET/v1/calls/{call_id}

One call with its transcript, its analysis, the tools it used and its recording. Reading a call that is over settles it first, so the answer shows its charge. While it runs, live says whether the person's side is connected, and the transcript comes live. A call of your key's other env (a live call for a test key, or the other way round) is 404 not_found, as if it didn't exist.

Call
{
  "id": "call_2Gx7Mb9KpQ4sVn1ZrT6e",
  "character_id": "chr_4fT9kQ2mXw7LbN3pZs8V",
  "character_name": "Alex",
  "status": "ended",
  "source": "api",
  "env": "live",
  "max_seconds": 300,
  "billed_seconds": 94,
  "charged_usd": 0.94,
  "price_per_min_usd": 0.6,
  "end_reason": "completed",
  "error": null,
  "metadata": { "ticket": 7 },
  "created_unix": 1793300000,
  "settled_unix": 1793300100,
  "transcript": [
    { "n": 1, "customer": "", "ai": "Hi, I'm Alex, an AI assistant. What can I help you with?" },
    { "n": 2, "customer": "What does it cost?", "ai": "It's ten dollars a month." }
  ],
  "analysis": { "status": "ready", "summary": "…", "fields": null, "verdict": null, "reason": null, "error": null, "analyzed_unix": 1793300110 },
  "tool_calls": [],
  "recording": { "status": "ready", "seconds": 94, "bytes": 6016044, "deleted_unix": null }
}
  • status: starting (for a moment), waiting (started: the browser may connect, and it stays so while the call runs), ended, or failed (on our side; nothing charged).
  • end_reason: null until it settles. completed (it ran and ended: hung up, ended through the API, or out of time) or never_connected (the browser didn't connect within 120 seconds, or the call was ended before it did); for a failed call, not_started, interrupted (we lost the call) or error. More reasons may come: treat one you don't know by status.
  • error: a plain sentence for a call that didn't go as planned, such as "The call couldn't start. Nothing was charged."
  • source: where it was started: api, dashboard, widget, or meeting.
  • transcript: one turn per item: what the person said (customer, empty for the greeting) and what the AI answered (ai).
  • analysis: the summary, your fields and the verdict. See Call analysis.
  • tool_calls: each use of a tool, without its arguments or answer. See Tools.
  • recording: pending, ready, none, off or deleted. See Recordings.

List calls

GET/v1/calls

Your calls, newest first, without transcripts: { "data": [...], "has_more": true }. limit is 1 to 100 (20 by default); page back with before set to the last call's created_unix. A key lists the calls of its own env: a live key the live calls (from /v1, the dashboard, the widget and meetings), a test key the test ones.

End a call

POST/v1/calls/{call_id}/end

Ends it now. It answers { "ok": true }; settling follows by itself, and call.ended arrives. Ending a call that is already over changes nothing. A call of the other env is 404.

curl -X POST https://api.daxov.com/v1/calls/call_2Gx7Mb9KpQ4sVn1ZrT6e/end \
  -H "Authorization: Bearer $ACME_SECRET_KEY"

The person can also hang up, your server can send end on the live events socket, and the call ends by itself at max_seconds, or when nobody speaks (below).

When things go wrong

WhatWhat happens
The call can't start503, settled at once as failed, not_started; nothing charged
The browser never connectsAfter 120 seconds the call ends as never_connected; nothing charged
The connection drops mid-callThe call ends (there is no reconnecting yet) and is settled
Nobody speaksAfter the character's silence_check_seconds (10 by default) it asks once if they're still there; silence_end_seconds later (20) it says goodbye and the call ends. See when nobody speaks
We lose the call on our sidefailed, interrupted; nothing charged
The balance would run outIt can't: max_seconds was set from what the hold covers
A double click, a retryThe Idempotency-Key gives back the first call
The character is deletedCalls already running go on; new ones are 404
The organization is disabledIts keys are refused and its calls can't start

On this page