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.
| Header | Required | Meaning |
|---|---|---|
x-api-key | Yes | An 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-Type | Yes | application/json. |
Idempotency-Key | No | 1–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.
| Field | Type | Required | Meaning |
|---|---|---|---|
participant.identity | string | Yes | Your ID for the user, such as your account ID, up to 128 characters. Appears in usage and support requests. |
participant.name | string | No | The user's display name in the call. The agent doesn't see it; use a variable to greet the user by name. |
participant.gender | male or female | No | Lets Arabic replies address the user with the right grammatical gender. |
agent.prompt | string | No | Instructions: who the agent is, what it helps with, and how it speaks. Can't be empty; omit it to get a general assistant. |
agent.intro | string | No | The 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_id | string | No | The id of a voice from the voice list, the same value text to speech takes. Defaults to the mul_nourah voice. |
agent.client_tools | array | No | Up to 16 functions in your page the agent can call; see Client tools. |
agent.tool_acknowledgments | object | No | When the agent tells the user it's still working on a tool call; see Tool acknowledgments. |
agent.web_search | boolean | No | Lets the agent search the web during the call. Defaults to false; see Web search. |
variables | object of string, number, or boolean values | No | Values 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.
| Rule | Detail |
|---|---|
| Names | Letters, digits, and _, starting with a letter. Case-sensitive. now and session_id are built in, so you can't send them. |
| Missing value | A placeholder with no value returns 400 naming the field and the variable. |
| Unused values | Allowed. |
| Values | Inserted 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".
| Field | Default | Meaning |
|---|---|---|
initial.enabled | true | Say a line when a tool hasn't answered yet. |
initial.after_ms | 1200 | Milliseconds to wait before that line, from 0 to 120000. |
long_wait.enabled | true | Say a second line on a long wait. |
long_wait.after_ms | 10000 | Milliseconds 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.
Web search
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 }
}| Field | Meaning |
|---|---|
server_url | Where the browser connects. Don't hard-code it. |
participant_token | Admits this user to this call only. Send it to the browser together with server_url. |
session_id | The call's ID: as_ and 26 lowercase characters. Appears in usage and support requests. |
expires_at | The token must be used before this time, about 60 seconds after the request. |
effective | The agent settings after defaults and variables are applied. |
limits | This 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 }
}| Field | Meaning |
|---|---|
session_id | The ID from the response. |
status | pending: started, nobody has joined. live: the agent has joined. ended: finished. |
api_key_id | The key that started the session. |
participant_identity | The participant.identity you sent. |
created_at, expires_at | When the session was requested, and the join deadline. |
started_at | When the agent joined. null while pending. |
ended_at | When the call ended. null until then. |
end_reason | One of the end reasons. null until the call ends. |
duration_s | Seconds from started_at to ended_at, or to now while live. null until the agent joins. |
billed_minutes | Minutes charged so far; see Limits and billing. |
limits | max_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.
| Parameter | Meaning |
|---|---|
status | pending, live, or ended. |
end_reason | Only sessions that ended with this end reason. |
api_key_id | Only sessions started with this key. |
from, to | Filter on created_at, as RFC 3339 timestamps. from is inclusive, to is exclusive. |
limit | 1 to 100. Default 50. |
cursor | The next_cursor of the previous page. |
An unknown or repeated parameter returns 400 VALIDATION_INVALID_PARAM, with every problem in
data.errors.