Voice Agent

Session options

Set the prompt, intro, voice, variables, and client tools of a Voice Agent session, read back its settings and limits, and look up past sessions.

Every call starts with one request from your backend. The request decides what the agent says and can do for that call; nothing is stored between calls.

Start a session

curl -sS -X POST "$API_URL/agent/sessions" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "participant": { "identity": "user-123", "name": "Sara" },
    "agent": {
      "prompt": "You help {{name}} track order {{order}}. Keep answers short.",
      "intro": "Hi {{name}}, how can I help with your order?",
      "voice_id": "42e38a63-849a-481a-b5bf-3c1b7a985de3"
    },
    "variables": { "name": "Sara", "order": "T-1182" }
  }'

Get a voice ID from the voice list; IDs differ per environment. The SDKs send the same request: createSession() in JavaScript and create_session() in Python.

HeaderRequiredMeaning
x-api-keyYesAn API key with the agent scope. Enable it on the key under API keys in the console; without it the request returns 403 AUTH_SCOPE_MISSING.
Content-TypeYesapplication/json.
Idempotency-KeyNo1–255 printable ASCII characters. Within 24 hours, a retry with the same key returns the first response instead of starting a second session.

Request fields

Unknown fields and invalid values are rejected with 400.

FieldTypeRequiredMeaning
participant.identitystringYesYour ID for the user, such as your account ID, up to 128 characters. Appears in usage and support requests.
participant.namestringNoThe user's display name in the call. The agent doesn't see it; use a variable to greet the user by name.
participant.gendermale or femaleNoLets Arabic replies address the user with the right grammatical gender.
agent.promptstringNoInstructions: who the agent is, what it helps with, and how it speaks. Can't be empty; omit it to get a general assistant.
agent.introstringNoThe agent's first sentence, spoken exactly as written. "" makes the agent wait for the user to speak first. Defaults to a short Arabic greeting.
agent.voice_idstringNoThe id of a voice from the voice list, the same value text to speech takes. Defaults to the mul_nourah voice.
agent.client_toolsarrayNoUp to 16 functions in your page the agent can call; see Client tools.
agent.tool_acknowledgmentsobjectNoWhen the agent tells the user it's still working on a tool call; see Tool acknowledgments.
agent.web_searchbooleanNoLets the agent search the web during the call. Defaults to false; see Web search.
variablesobject of string, number, or boolean valuesNoValues for the {{name}} placeholders in agent.prompt and agent.intro; see Variables.

Size limits for the request are in Limits.

Maximum call length, idle timeout, the number of people in a call, the room, and the agent that joins it are fixed by your plan or HUMAIN Voice. Sending any of these fields returns 400.

Variables

Write {{name}} in agent.prompt or agent.intro, and send the value in variables. Each session fills in its own values, so one prompt serves every user.

RuleDetail
NamesLetters, digits, and _, starting with a letter. Case-sensitive. now and session_id are built in, so you can't send them.
Missing valueA placeholder with no value returns 400 naming the field and the variable.
Unused valuesAllowed.
ValuesInserted as text. Numbers and booleans are written as JSON (3, true).
Built-in {{now}}The time of the session request in UTC, ISO 8601.
Built-in {{session_id}}The session_id of the call.

The agent reads every variable, so don't send secrets or data the user shouldn't hear. To tell the agent something new during the call, such as the page the user just opened, use updateContext().

Tool acknowledgments

While a client tool runs, the agent fills the silence with a short line it writes for that request, such as "Let me check that for you".

FieldDefaultMeaning
initial.enabledtrueSay a line when a tool hasn't answered yet.
initial.after_ms1200Milliseconds to wait before that line, from 0 to 120000.
long_wait.enabledtrueSay a second line on a long wait.
long_wait.after_ms10000Milliseconds to wait before the second line, from 0 to 120000.

Set enabled to false to stay silent at that stage. If a line isn't ready in time, the agent stays silent rather than using a fixed phrase.

Set agent.web_search to true to let the agent look up current information on the web, such as news, opening hours, or prices. The agent decides when to search, and fills the wait the same way it does for a tool call.

Web search is off by default. Without it, the agent answers only from your prompt, your variables, your client tools, and what the model already knows. The agent sends its search queries to an external search provider, so leave web search off if what users say must stay inside HUMAIN Voice.

A client tool named web_search replaces the built-in search.

Response

201 Created:

{
  "server_url": "<server_url>",
  "participant_token": "eyJhbGciOiJIUzI1NiJ9…",
  "session_id": "as_01j9z3k7q4m8xv6t2n5r8b1c0d",
  "expires_at": "2026-10-05T12:01:00Z",
  "effective": {
    "prompt": "You help Sara track order T-1182. Keep answers short.",
    "intro": "Hi Sara, how can I help with your order?",
    "voice_id": "42e38a63-849a-481a-b5bf-3c1b7a985de3",
    "client_tools": [],
    "tool_acknowledgments": {
      "initial": { "enabled": true, "after_ms": 1200 },
      "long_wait": { "enabled": true, "after_ms": 10000 }
    },
    "web_search": false
  },
  "limits": { "max_duration_s": 900, "idle_timeout_s": 120 }
}
FieldMeaning
server_urlWhere the browser connects. Don't hard-code it.
participant_tokenAdmits this user to this call only. Send it to the browser together with server_url.
session_idThe call's ID: as_ and 26 lowercase characters. Appears in usage and support requests.
expires_atThe token must be used before this time, about 60 seconds after the request.
effectiveThe agent settings after defaults and variables are applied.
limitsThis call's limits from your plan, in seconds. null means your plan sets no limit. See Limits and billing.

server_url and participant_token follow LiveKit's token-endpoint response, so LiveKit clients can join with them.

Start the session when the user is ready to talk, such as on a button click, and connect right away. A token used after expires_at is refused, and the session ends as user_never_joined without a charge.

Validation errors

A 400 returns the standard error response with code VALIDATION_INVALID_PARAM. data.errors lists every problem with its path, sorted by path:

"data": {
  "errors": [
    { "path": "agent.prompt", "reason": "missing variable: order" },
    { "path": "agent.voice_id", "reason": "unknown voice" }
  ]
}

Other session errors, such as no credit or too many calls, are in Voice Agent codes.

Read sessions

Both routes return only your account's sessions, need any active API key (no agent scope), and never return the prompt, intro, tools, variables, or the user's name.

Get a session

curl -sS "$API_URL/agent/sessions/as_01j9z3k7q4m8xv6t2n5r8b1c0d" \
  -H "x-api-key: $API_KEY"
{
  "session_id": "as_01j9z3k7q4m8xv6t2n5r8b1c0d",
  "status": "ended",
  "api_key_id": "5f0c1e2a-7b4d-4c1e-9a3f-2d8b6e0a1c44",
  "participant_identity": "user-123",
  "created_at": "2026-10-14T09:00:00Z",
  "expires_at": "2026-10-14T09:01:00Z",
  "started_at": "2026-10-14T09:00:04Z",
  "ended_at": "2026-10-14T09:02:19Z",
  "end_reason": "user_left",
  "duration_s": 135,
  "billed_minutes": 3,
  "limits": { "max_duration_s": 900, "idle_timeout_s": 120 }
}
FieldMeaning
session_idThe ID from the response.
statuspending: started, nobody has joined. live: the agent has joined. ended: finished.
api_key_idThe key that started the session.
participant_identityThe participant.identity you sent.
created_at, expires_atWhen the session was requested, and the join deadline.
started_atWhen the agent joined. null while pending.
ended_atWhen the call ended. null until then.
end_reasonOne of the end reasons. null until the call ends.
duration_sSeconds from started_at to ended_at, or to now while live. null until the agent joins.
billed_minutesMinutes charged so far; see Limits and billing.
limitsmax_duration_s and idle_timeout_s frozen when the session started; null means no limit.

An unknown or malformed ID, or a session of another account, returns 404 AGENT_SESSION_NOT_FOUND.

List sessions

curl -sS "$API_URL/agent/sessions?status=ended&limit=20" \
  -H "x-api-key: $API_KEY"

Returns { "sessions": [ … ], "next_cursor": "…" }: sessions newest first, each shaped as above. Pass next_cursor as cursor to get the next page; it is null on the last page.

ParameterMeaning
statuspending, live, or ended.
end_reasonOnly sessions that ended with this end reason.
api_key_idOnly sessions started with this key.
from, toFilter on created_at, as RFC 3339 timestamps. from is inclusive, to is exclusive.
limit1 to 100. Default 50.
cursorThe next_cursor of the previous page.

An unknown or repeated parameter returns 400 VALIDATION_INVALID_PARAM, with every problem in data.errors.

On this page