Agent tab

Fields

Field	Type	Default	Limits	What it does
name	string	required	1 to 120 characters	Shown in the console, on calls (agent_name) and in the ledger. The caller never hears it unless your prompt says it.
welcome_message	string	""	none	Spoken as soon as the call connects, before the caller says anything. Leave it empty and the agent waits for the caller to speak first.
system_prompt	string	""	none	Instructions for the LLM: who the agent is, what it must do, and how.

{
  "name": "Front desk",
  "welcome_message": "Namaste {customer_name}, City Clinic se baat kar rahi hoon. Main aapki kya madad kar sakti hoon?",
  "system_prompt": "You are Priya, the receptionist of City Clinic in Pune.\nHelp the caller book, move or cancel a visit.\nThe clinic is open 9 am to 7 pm, Monday to Saturday.\nIf the caller asks about medicine or a diagnosis, say a doctor will call them back."
}

Variables

Any {name} in the welcome message or prompt is a variable. A name starts with a letter or underscore and contains only letters, digits and underscores, for example {customer_name} or {slot_2}.

• Filled per call. For outbound calls, values come from user_data in the place-call request. For browser calls, from the test call form. Inbound calls have no user_data.
• {caller_phone} is always set. It is the number being called (outbound) or the number calling in (inbound). It is empty for browser calls.
• Every variable is optional. A variable with no value becomes an empty string; the raw {name} is never spoken. Voxa also tells the LLM which variables were not provided, so it can ask the caller instead of guessing.
• The agent lists its variables. The agent object’s read-only variables field lists every variable the welcome message and prompt use, in order.

curl -X POST https://voxa.abhinavyadav.in/api/v1/agents/$AGENT_ID/call \
  -H "X-API-Key: $VOXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+919812345678", "user_data": {"customer_name": "Rohan"}}'

Values are inserted as text. A number or boolean in user_data is converted as Python would print it (true becomes True), and false, 0 and null become empty. Send strings when the exact wording matters.

What the LLM actually receives

Voxa builds the final system prompt from your prompt plus a few fixed parts, in this order:

1. Your system_prompt, with variables filled in.
2. Voice rules: answer in one to three short spoken sentences; no lists, markdown or emojis; say numbers and dates as a person would; ask one question at a time; when the caller says goodbye, say a short goodbye and call end_call in the same reply.
3. If the voice language is hi: speak natural Hinglish in Roman script (never Devanagari), matching the caller’s mix of Hindi and English.
4. Today’s date and time in the agent’s call.timezone, for example Today is Thursday, 01 October 2026, 02:30 PM (Asia/Kolkata).
5. If any variables are empty: a line listing them, telling the agent to ask the caller if it needs them.
6. If there is a welcome message: a line saying the agent has already greeted the caller with it, so it does not greet twice.

You don’t need to repeat the voice rules in your prompt. Focus on the task, the facts the agent needs, and what to do in edge cases.

Writing a good prompt

• Say who the agent is and who it calls. “You are Priya from City Clinic, calling patients to confirm tomorrow’s appointment.”
• State the goal and when it’s done. “Confirm whether they will come. If not, offer another day. Then say goodbye and end the call.”
• Give facts as facts. Opening hours, prices, addresses. The agent cannot look up anything you don’t give it, except through tools.
• Name your tools. “Before offering a slot, call check_availability.”
• Cover the edge cases. Wrong person, not interested, asks for a human, asks something off-topic.