Call tab

Fields

All fields live under call in the agent object.

Field	Type	Default	Allowed	Section
record	boolean	true		Recording
allow_interruptions	boolean	true		Interruptions
interruption_min_words	integer	2	1 to 10	Interruptions
check_user_online	boolean	false		User online check
user_online_message	string	Are you still there?		User online check
user_online_after_seconds	integer	9	3 to 60	User online check
hangup_after_silence_seconds	integer	15	5 to 120	Hang up on silence
hangup_on_prompt	boolean	false		Hang up using a prompt
hangup_prompt	string	see below		Hang up using a prompt
hangup_message	string	""		Hang-up message
max_duration_seconds	integer	600	30 to 3600	Maximum length
call_start_hour	integer	9	0 to 23	Calling hours
call_end_hour	integer	21	1 to 24	Calling hours
timezone	string	Asia/Kolkata	an IANA time zone	Calling hours

{
  "call": {
    "record": true,
    "allow_interruptions": true,
    "interruption_min_words": 2,
    "check_user_online": true,
    "user_online_message": "Hello, are you still there?",
    "user_online_after_seconds": 8,
    "hangup_after_silence_seconds": 20,
    "hangup_on_prompt": true,
    "hangup_prompt": "You are deciding whether a phone conversation is complete. ...",
    "hangup_message": "Thank you for your time. Goodbye!",
    "max_duration_seconds": 300,
    "call_start_hour": 10,
    "call_end_hour": 19,
    "timezone": "Asia/Kolkata"
  }
}

The console’s New agent template turns check_user_online on. An agent created through the API without it has the check off.

Interruptions

With allow_interruptions on, the caller can talk over the agent. As soon as the caller has said at least interruption_min_words words while the agent is speaking or preparing a reply, Voxa:

1. stops the reply and clears the audio not yet played;
2. keeps only the part of the reply the caller heard, marked "interrupted": true in the transcript;
3. emits an interrupted event;
4. answers what the caller says.

interruption_min_words stops coughs and one-word fillers (“haan”, “ok”) from cutting the agent off. Raise it to 3 or 4 on noisy lines.

With allow_interruptions off, partial speech never stops the agent. If the caller finishes a whole turn while a reply is still being generated, that reply is still dropped and the agent answers the new turn.

Once the agent has decided to hang up (with end_call, the hang-up prompt or on silence), nothing the caller says interrupts the goodbye. Those last words are kept in the transcript but not answered.

User online check

When the caller goes quiet, the agent can ask once whether they are still there.

Field	What it does
check_user_online	Turns the check on.
user_online_message	What the agent says. If empty, the check is skipped.
user_online_after_seconds	Seconds of silence before asking. Must be less than hangup_after_silence_seconds, or the check never runs.

Silence is counted from the later of: the last time the caller spoke, or the end of the agent’s last audio. The question is asked once per stretch of silence; when the caller speaks again, the check resets. It emits a user.online_check event.

Hang up on silence

If neither side speaks for hangup_after_silence_seconds, the agent ends the call. If there is a hangup_message, the agent says it first. The call ends with hangup_by: "agent" and hangup_reason: "caller was silent".

The timer does not run while the agent is preparing or speaking a reply, or waiting for a tool.

Hang up using a prompt

With hangup_on_prompt on, after each reply the LLM writes, Voxa asks the agent’s LLM a separate short question: given the transcript so far and hangup_prompt, is the conversation complete? If the answer starts with “Yes”, the agent says the hangup_message (if any) and hangs up. The call ends with hangup_reason: "hang-up prompt: conversation complete" and a hangup.prompt event.

• The check runs in the background; it does not delay the next reply.
• If the caller has started talking again by the time the answer comes back, the call goes on.
• The check uses the agent’s llm.model with temperature 0, and its tokens count in the call’s usage.
• It does not run after scripted lines (welcome, “are you still there?”) or after a reply that already ended the call.

This is useful when your prompt can’t be relied on to call end_call, or when you want a clear rule for when a call is over. The default hangup_prompt is:

You are deciding whether a phone conversation is complete.
It is complete if:
1. The caller said goodbye, asked to end the call, or said they have nothing else to ask.
2. The agent has finished what the caller needed and there is nothing left to do.
3. The caller is clearly not interested or asked not to be called.
It is not complete while a question is unanswered or the caller is mid-request.
Answer with only "Yes" or "No".

Write your own if your calls have a different end, for example “complete once the caller has confirmed or declined the appointment”. Keep the last line asking for only “Yes” or “No”: Voxa reads at most a few tokens of the answer.

Hang-up message

hangup_message is said just before the agent hangs up on silence or by the hang-up prompt. Leave it empty to hang up without a word.

It is not said when the LLM calls end_call (the LLM says its own goodbye in the same reply), when the call hits its maximum length or runs out of credit, or when the caller hangs up.

Maximum length

max_duration_seconds is the longest a call may last, counted from the moment the agent goes live. When it is reached, the call ends at once with hangup_reason: "maximum call length reached".

The limit is lowered for a call when your credits would run out sooner. In that case, the call ends with hangup_reason: "credits ran out" and an error event. See Limits and billing.

Calling hours

Outbound calls are dialled only when the current hour in timezone is at least call_start_hour and less than call_end_hour. With the defaults, calls go out from 9:00 to 20:59 India time.

• Calls placed outside the window wait in the queue until it opens (and expire after 24 hours).
• ignore_call_window: true on the place-call request skips the check for that call.
• Inbound and browser calls ignore calling hours.
• The window can’t wrap past midnight. If call_start_hour is not less than call_end_hour, outbound calls are never dialled.
• timezone is an IANA name such as Asia/Kolkata, Asia/Dubai or Europe/London. It also sets the date and time the agent is told at the start of each call.

See Call flow.

Recording

With record on, Voxa saves a stereo WAV of the call on its server: the caller on the left channel, the agent on the right. The agent’s audio is placed where the caller actually heard it, and audio cut off by an interruption is removed.

• Phone calls are recorded at 8 kHz, browser calls at 16 kHz.
• Calls shorter than half a second are not saved.
• The call’s recording_seconds gives the length. Download it with GET /api/v1/calls/{id}/recording (add ?download=true for a file name).

curl -o call.wav "https://voxa.abhinavyadav.in/api/v1/calls/$CALL_ID/recording?download=true" \
  -H "X-API-Key: $VOXA_API_KEY"

A call without a recording returns 404 no recording for this call.