How to Manage Voice Agents

📋 Prerequisites

Valid api-token and app-id from your LigueLead account.
An engine version and voice for the agent — GET /v1/voice-agent/voices lists the available voices, grouped by engine version.
(Optional) An existing Voice Action id to attach via action_id.

🌐 Base URL

https://api.liguelead.com.br/v1

🔑 Authentication

api-token: your-api-token
app-id: your-app-id

Agent Fields

Field	Type	Required	Description
`name`	string	✅	Agent name (1–100 characters).
`prompt`	string	✅	Behavior instructions for the AI. Limit depends on `engine.version`: 2000 characters for `lumen-mini`, 25000 for `lumen-1`, 35000 for `prisma-1` and `horizon-1`.
`engine`	object	✅	Engine that drives the call and the voice it speaks with. No default — every agent declares its engine.
`engine.version`	string	✅	`lumen-mini`, `lumen-1`, `prisma-1` or `horizon-1`. `lumen-mini` ignores `action_id` — combining the two returns `422`. The realtime engines (`prisma-1`, `horizon-1`) do accept `action_id`.
`engine.voice_id`	string	✅	Voice identifier. Each engine version accepts only its own voices — pick one from the list `GET /v1/voice-agent/voices` returns for the chosen `engine.version` (`422` otherwise).
`greetings`	string	❌	Opening line spoken when the call connects (1–600 characters). To have none, omit it or send `null` — an empty string is refused (`422`).
`stability`	number	❌	Voice tuning from 0 to 1, `lumen-mini`/`lumen-1` only (defaults to 0.7). Forbidden for the realtime engines `prisma-1` and `horizon-1` (`422`).
`similarity_boost`	number	❌	Voice tuning from 0 to 1, `lumen-mini`/`lumen-1` only (defaults to 0.75). Forbidden for the realtime engines `prisma-1` and `horizon-1` (`422`).
`speed`	number	❌	Voice tuning from 0.7 to 1.2, `lumen-mini`/`lumen-1` only (defaults to 1.0). Forbidden for the realtime engines `prisma-1` and `horizon-1` (`422`).
`description`	string	❌	Free-text description (max 500 characters).
`action_id`	string	❌	ID of a Voice Action the agent may execute. Not available when `engine.version` is `lumen-mini` (`422`).

Optional fields accept null as equivalent to omitting the field — useful for clients whose JSON serializers always emit every key.

The pre-engine root-level voice_id is still accepted as a deprecated alias of engine.voice_id: it is considered only when engine.voice_id is omitted, and sending both with different values returns 422. Prefer engine.voice_id. The other pre-engine root fields, model_version and model, are no longer accepted: they return 422 pointing to engine.

List Available Voices

GET /v1/voice-agent/voices → 200 OK

Returns the voices each engine version accepts, grouped by engine. Pick the agent's engine.voice_id from the list of its engine.version. Each entry carries the voice's gender (female or male), so a voice picker can group or filter without parsing the name:

{
  "engines": [
    {
      "version": "lumen-mini",
      "voices": [
        { "id": "RGymW84CSmfVugnA5tvA", "name": "Roberta", "gender": "female" },
        { "id": "GDzHdQOi6jjf8zaXhCYD", "name": "Raquel", "gender": "female" },
        { "id": "lWq4KDY8znfkV0DrK8Vb", "name": "Yasmin", "gender": "female" },
        { "id": "F7823wtD50WK1gnmgBk5", "name": "Matheus", "gender": "male" },
        { "id": "GM2UA3fbsIaLHcswCDX9", "name": "Nina", "gender": "female" }
      ]
    },
    {
      "version": "lumen-1",
      "voices": [
        { "id": "RGymW84CSmfVugnA5tvA", "name": "Roberta", "gender": "female" },
        { "id": "GDzHdQOi6jjf8zaXhCYD", "name": "Raquel", "gender": "female" },
        { "id": "lWq4KDY8znfkV0DrK8Vb", "name": "Yasmin", "gender": "female" },
        { "id": "F7823wtD50WK1gnmgBk5", "name": "Matheus", "gender": "male" },
        { "id": "GM2UA3fbsIaLHcswCDX9", "name": "Nina", "gender": "female" }
      ]
    },
    {
      "version": "prisma-1",
      "voices": [
        { "id": "helena", "name": "Helena", "gender": "female" },
        { "id": "carolina", "name": "Carolina", "gender": "female" },
        { "id": "leticia", "name": "Letícia", "gender": "female" },
        { "id": "priscila", "name": "Priscila", "gender": "female" },
        { "id": "bruna", "name": "Bruna", "gender": "female" },
        { "id": "rafael", "name": "Rafael", "gender": "male" },
        { "id": "diego", "name": "Diego", "gender": "male" },
        { "id": "otavio", "name": "Otávio", "gender": "male" },
        { "id": "gustavo", "name": "Gustavo", "gender": "male" },
        { "id": "henrique", "name": "Henrique", "gender": "male" }
      ]
    },
    {
      "version": "horizon-1",
      "voices": [
        { "id": "fernanda", "name": "Fernanda", "gender": "female" },
        { "id": "juliana", "name": "Juliana", "gender": "female" },
        { "id": "patricia", "name": "Patrícia", "gender": "female" },
        { "id": "renata", "name": "Renata", "gender": "female" },
        { "id": "camila", "name": "Camila", "gender": "female" },
        { "id": "adriana", "name": "Adriana", "gender": "female" },
        { "id": "vanessa", "name": "Vanessa", "gender": "female" },
        { "id": "simone", "name": "Simone", "gender": "female" },
        { "id": "marcelo", "name": "Marcelo", "gender": "male" },
        { "id": "eduardo", "name": "Eduardo", "gender": "male" },
        { "id": "ricardo", "name": "Ricardo", "gender": "male" },
        { "id": "anderson", "name": "Anderson", "gender": "male" },
        { "id": "fabio", "name": "Fábio", "gender": "male" },
        { "id": "vinicius", "name": "Vinícius", "gender": "male" },
        { "id": "leandro", "name": "Leandro", "gender": "male" },
        { "id": "rodrigo", "name": "Rodrigo", "gender": "male" },
        { "id": "marcio", "name": "Márcio", "gender": "male" },
        { "id": "thiago", "name": "Thiago", "gender": "male" },
        { "id": "bruno", "name": "Bruno", "gender": "male" },
        { "id": "sergio", "name": "Sérgio", "gender": "male" },
        { "id": "alexandre", "name": "Alexandre", "gender": "male" },
        { "id": "daniel", "name": "Daniel", "gender": "male" },
        { "id": "felipe", "name": "Felipe", "gender": "male" },
        { "id": "rogerio", "name": "Rogério", "gender": "male" },
        { "id": "wagner", "name": "Wagner", "gender": "male" },
        { "id": "claudio", "name": "Cláudio", "gender": "male" }
      ]
    }
  ]
}

The two realtime catalogs never overlap. prisma-1 and horizon-1 each
accept only the voices listed under them — sending a prisma-1 voice on a
horizon-1 agent returns 422, and the reverse too.

Renamed voices (prisma-1). The first four ids this engine shipped with — leimag, nori, norvet and krats — were replaced by helena, rafael, bruna and diego respectively. The old ids are still accepted on create and update, but they are no longer listed here and reads always return the new one. Existing agents are unaffected: the voice they play does not change.

Create a Voice Agent

POST /v1/voice-agent → 201 Created

Agent with an attached Action

curl -X POST https://api.liguelead.com.br/v1/voice-agent \
  -H "Content-Type: application/json" \
  -H "api-token: YOUR_TOKEN" \
  -H "app-id: YOUR_APP_ID" \
  -d '{
    "name": "Scheduling Agent",
    "prompt": "You are a scheduling assistant for company XYZ. Your goal is to book a meeting with the customer. Be polite, objective and professional. Ask for the customer'\''s availability and confirm the time. At the end, use the scheduling action to register the meeting.",
    "greetings": "Hi! This is the virtual assistant of company XYZ. I am calling to schedule a meeting with you. Do you have a minute?",
    "engine": {
      "version": "lumen-1",
      "voice_id": "RGymW84CSmfVugnA5tvA"
    },
    "description": "Agent responsible for booking meetings with customers",
    "action_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

Conversational agent (no Action)

curl -X POST https://api.liguelead.com.br/v1/voice-agent \
  -H "Content-Type: application/json" \
  -H "api-token: YOUR_TOKEN" \
  -H "app-id: YOUR_APP_ID" \
  -d '{
    "name": "NPS Survey Agent",
    "prompt": "You are a satisfaction survey assistant. Ask the customer, on a scale from 0 to 10, how likely they are to recommend the company to a friend. Thank them for participating.",
    "greetings": "Hi! I am calling from company XYZ for a quick satisfaction survey. It takes less than a minute!",
    "engine": {
      "version": "lumen-mini",
      "voice_id": "F7823wtD50WK1gnmgBk5"
    }
  }'

Response (201 Created)

{
  "id": "f9e8d7c6-b5a4-4321-8fed-cba987654321",
  "app_id": "your-app-id",
  "name": "Scheduling Agent",
  "prompt": "You are a scheduling assistant for company XYZ...",
  "greetings": "Hi! This is the virtual assistant of company XYZ...",
  "engine": {
    "version": "lumen-1",
    "voice_id": "RGymW84CSmfVugnA5tvA"
  },
  "stability": 0.7,
  "similarity_boost": 0.75,
  "speed": 1,
  "description": "Agent responsible for booking meetings with customers",
  "action_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-06-16T12:05:00.000Z",
  "updated_at": "2026-06-16T12:05:00.000Z"
}

Save the returned id. You will use it as voice_agent_id when dispatching calls.

List All Voice Agents

GET /v1/voice-agent → 200 OK

curl -X GET https://api.liguelead.com.br/v1/voice-agent \
  -H "api-token: YOUR_TOKEN" \
  -H "app-id: YOUR_APP_ID"

Get a Voice Agent by ID

GET /v1/voice-agent/:id → 200 OK

curl -X GET https://api.liguelead.com.br/v1/voice-agent/f9e8d7c6-b5a4-4321-8fed-cba987654321 \
  -H "api-token: YOUR_TOKEN" \
  -H "app-id: YOUR_APP_ID"

Update a Voice Agent

PUT /v1/voice-agent/:id → 200 OK

PUT replaces the agent in full — the payload must carry the complete, valid state of the agent, the same required/forbidden fields per engine as POST. A field omitted from the payload does not fall back to whatever the agent had before: an omitted greetings, description or action_id is absent from the resulting agent, and on lumen-mini/lumen-1 an omitted stability, similarity_boost or speed is reset to its default (0.7, 0.75 and 1.0). Sending null for an optional field is treated exactly like omitting it. Fetch the current agent first if you only want to change one field:

# 1. Fetch the current agent
curl -X GET https://api.liguelead.com.br/v1/voice-agent/f9e8d7c6-b5a4-4321-8fed-cba987654321 \
  -H "api-token: YOUR_TOKEN" \
  -H "app-id: YOUR_APP_ID"

# 2. Send the full agent back, with the fields you want changed
curl -X PUT https://api.liguelead.com.br/v1/voice-agent/f9e8d7c6-b5a4-4321-8fed-cba987654321 \
  -H "Content-Type: application/json" \
  -H "api-token: YOUR_TOKEN" \
  -H "app-id: YOUR_APP_ID" \
  -d '{
    "name": "Scheduling Agent",
    "prompt": "Updated prompt with more detailed instructions...",
    "greetings": "Good morning! This is the assistant of company XYZ.",
    "engine": {
      "version": "lumen-1",
      "voice_id": "RGymW84CSmfVugnA5tvA"
    },
    "action_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

action_id is validated on both create and update. If the ID does not exist for the client, the API returns 422 Unknown action_id: <id>. Omit it from the PUT body to leave the agent without an attached action.

Converting an agent's engine

Sending a different engine object in the PUT body converts the agent's engine in place, in the same request — no need to delete and recreate it. Each engine has its own required/forbidden fields (see Agent Fields), so the rest of the payload must match the engine you're switching to:

# Convert an existing lumen-1 agent to a realtime engine — pick a voice from that
# engine's catalog (prisma-1 below; horizon-1 works the same way) and
# omit stability/similarity_boost/speed (forbidden for this engine)
curl -X PUT https://api.liguelead.com.br/v1/voice-agent/f9e8d7c6-b5a4-4321-8fed-cba987654321 \
  -H "Content-Type: application/json" \
  -H "api-token: YOUR_TOKEN" \
  -H "app-id: YOUR_APP_ID" \
  -d '{
    "name": "Scheduling Agent",
    "prompt": "You are a scheduling assistant for company XYZ.",
    "engine": {
      "version": "prisma-1",
      "voice_id": "helena"
    }
  }'

There is no DELETE endpoint for Voice Agents.

Relationship: Agent ↔ Action

Voice Agent ──── action_id (optional) ────▶ Voice Action
 prompt, greetings,                          type / provider,
 engine, voice                               credentials, config

A Voice Agent references zero or one Voice Action (action_id is optional).
A Voice Action may be referenced by multiple agents.
Deleting an Action does not remove the action_id from referencing agents — clean those up manually.

Limits

Resource	Limit
`prompt` length	2000 characters (`lumen-mini`) / 25000 (`lumen-1`) / 35000 (`prisma-1`, `horizon-1`)
`greetings` length	600 characters
`name` length	1–100 characters
`description` length	500 characters
`stability` / `similarity_boost`	0–1 (`lumen-mini`, `lumen-1`)
`speed`	0.7–1.2 (`lumen-mini`, `lumen-1`)

Common Errors

Code	Message	Cause
`401`	`Authorization token missing`, `Authorization app id missing`, `Authorization failed`, …	Missing, invalid or blocked `api-token`/`app-id`, or an inactive app.
`404`	`Voice agent not found`	The `id` does not exist for this client.
`422`	`Unknown action_id: <id>`	The `action_id` does not exist for this client.
`422`	validation error (e.g. missing `name`/`prompt`/`engine`)	`PUT` body is not a complete, valid agent — same as `POST`.
`422`	validation error on `engine.voice_id`	The voice is not available for the chosen `engine.version` — pick one from `GET /v1/voice-agent/voices`.
`422`	validation error on `stability`/`similarity_boost`/`speed`	A value outside its range, or a voice tuning field sent with a realtime engine (`prisma-1`, `horizon-1`), where they are forbidden.

Next Steps

How to Manage Voice Actions — define what your agent can do during a call.
How to Send Voice Calls with AI — dispatch calls with this agent and receive transcripts.