Skip to main content
a voice agent is an agent you configure once — its prompt, greeting, voice and language — in the dashboard or with the agents api, and then start from your own product with a single api call. the agent listens, thinks and speaks; you only carry audio, or let the phone network carry it. there are three ways to connect a caller, and the right one depends on where the audio lives.

web call

your browser joins the call directly over webrtc. lowest latency, and the media never passes through your servers.

realtime socket

a plain websocket carrying base64 pcm. no webrtc stack — good for servers, native apps and anything that already has audio buffers.

phone call

the agent dials a number and talks to whoever answers. no audio on your side at all; inbound calls on your numbers land on the agent too.

​
which one

the choice of transport does not affect what a call costs — see billing for that, which depends on your plan rather than on how the caller connected.

​
authentication

every endpoint takes your api key as a bearer token:
the key needs the agent scope. keys created in the dashboard have it by default; older keys were granted it automatically, so nothing you already ship stops working.
never put a rk_live_ key in a browser. for web calls, start the call from your server and pass the returned join credentials to the page. for the realtime socket, mint a short-lived token with /v1/register-call and hand that to the page.

​
before you start

1

create an agent

in the dashboard, open agents and build one — or POST /v1/agents. note its id (a UUID) or its handle (ua_…) — either works everywhere an agent is named.
2

deploy it

press deploy, or POST /v1/agents/{agent_ref}/deploy. saving records a draft; deploying is what puts a version live. the api refuses an agent that has never been deployed with 409 agent_not_deployed, so it can never answer a caller with a configuration you did not release.
3

create an api key

api keys → new key. the full key is shown once.
4

check your capacity

GET /v1/agent/limits tells you how many concurrent calls your plan allows and how many are running right now.

​
errors

every endpoint — these and the agents api — answers with the same envelope the rest of the api uses:
a 429 carries the numbers you need to back off intelligently:

​
billing

how a call is paid for depends on which plan the account is on. the two work differently enough that it is worth knowing which one you are testing against — plan in /v1/agent/limits tells you.
every second is billed from your balance, at the agent’s per-minute rate.a call is capped at what your balance can fund: if you can only afford 40 seconds, the call ends after 40 seconds rather than being refused up front. if you cannot afford a usable call at all, the start returns 402 insufficient_balance.new accounts also get a small grant of free agent seconds, which is spent before your balance is touched.

​
concurrency is used first, and credits are never a fallback

an account can hold a concurrency plan and a credit balance at the same time. when it does:
1

the plan is used first

while a slot is free, the call runs on the plan. your credit balance is not touched — not partially, not for the overflow, not at all.
2

when the slots run out, the call is refused

a call that arrives with every slot busy gets 429 concurrency_limit_exceeded. it does not fall through to your credits, even if the balance would comfortably cover it.
credits are not an overflow buffer for a concurrency plan. if you are on a concurrency plan, a balance sitting in the account will never be spent on agent calls — the only thing that raises your ceiling is a bigger plan.
so a single account behaves like exactly one of these at a time:

​
where calls show up

every call appears in conversations in the dashboard with its transcript and recording, and in your usage — attributed to the api key that started it. calls that ran on a concurrency plan appear there too, at zero cost.