Core Concepts

Agents

Agents are the core of Levrage.AI. Each agent is a fully configured AI voice assistant that can make and receive calls, follow conversation flows, collect data, and transfer calls.

Creating an Agent

$curl -X POST https://api.levrage.ai/v1/agents \
>  -H "Authorization: Bearer $API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "name": "Acme Sales Agent",
>    "agent_type": "finance_lead_qualifier",
>    "language": "Hindi",
>    "voice": "female",
>    "start_flow": "नमस्ते! मैं Acme Finance से बात कर रही हूँ।",
>    "end_flow": "धन्यवाद, आपका दिन शुभ हो!",
>    "brand_name": "Acme Finance",
>    "description": "Qualifies leads for personal loan products"
>  }'

Required Fields

FieldTypeDescription
namestringUnique agent name (max 100 chars)
start_flowstringOpening greeting message
end_flowstringClosing/goodbye message

Agent Type

The agent_type determines the base behavior and auto-generated prompt for your agent.

General types (work across any industry):

TypeDescription
salesOutbound/inbound sales calls
supportCustomer support and issue resolution
cold_callingOutbound cold prospecting
collectionDebt collection and payment reminders
retentionCustomer retention and save offers
complianceCompliance verification calls
appointment_bookingSchedule appointments
customFully custom agent (requires custom_description)

Industry-specific types — Use GET /v1/industries and GET /v1/industries/{industry}/agent-types to discover 200+ specialized types like:

  • real_estate_lead_qualifier
  • finance_account_opening
  • healthcare_appointment_scheduler
  • ecommerce_cart_recovery
  • insurance_claim_intake

When you use an industry-specific agent type, the sector field is automatically populated. For general types like sales, you can optionally pass sector to categorize the agent.

Language Options

LanguageCodeNotes
EnglishEnglish or enDefault
HindiHindiUses Hinglish (Devanagari script)
BengaliBengali
TamilTamil
TeluguTelugu
KannadaKannada
MalayalamMalayalam
GujaratiGujarati

Set other_languages array for multilingual agents that can switch languages.

Voice Options

FieldValuesDescription
voicemale, femaleVoice gender
voice_idstringSpecific voice ID (get from GET /v1/voices)

List available voices:

$# All voices
$curl https://api.levrage.ai/v1/voices
$
$# Supported languages
$curl https://api.levrage.ai/v1/voices/languages

AI Models

ModelDescription
lai-premium-2Default. Best quality, optimized for voice
lai-premium-1Previous generation

Configuring Agent Behavior

Voice Response Settings

Fine-tune how the agent listens and responds:

1{
2  "voice_response_settings": {
3    "allow_user_to_interrupt": true,
4    "words_to_interrupt": 2,
5    "silence_before_reminder": 8,
6    "max_reminders": 5,
7    "max_call_duration_minutes": 60,
8    "call_analysis_enabled": true,
9    "response_creativity": 0.8,
10    "detect_ivr_systems": true,
11    "leave_voicemail": false
12  }
13}

Data Collection

Configure what information the agent should collect during calls:

1{
2  "details_to_collect": [
3    {
4      "key": "full_name",
5      "type": "text",
6      "description": "Customer's full name"
7    },
8    {
9      "key": "email",
10      "type": "email",
11      "description": "Email address for follow-up"
12    },
13    {
14      "key": "interested",
15      "type": "boolean",
16      "description": "Whether customer is interested in the product"
17    }
18  ]
19}

Collected data appears in call history and webhook payloads.

Webhooks

Receive real-time notifications when calls end:

1{
2  "webhook_config": {
3    "url": "https://your-server.com/webhook",
4    "events": ["CALL_ENDED"],
5    "secret": "your_webhook_secret"
6  }
7}

Call Transfers

Configure when and where the agent should transfer calls:

1{
2  "transfer_map": [
3    {
4      "condition": "customer wants to speak to a manager",
5      "phone_number": "+919876543210",
6      "description": "Transfer to manager"
7    }
8  ]
9}

Managing Agents

List All Agents

$curl -H "Authorization: Bearer $API_KEY" \
>     "https://api.levrage.ai/v1/agents?page=1&page_size=20"

Get Agent Details

$curl -H "Authorization: Bearer $API_KEY" \
>     "https://api.levrage.ai/v1/agents/{agent_id}"

Update an Agent

Only send the fields you want to change:

$curl -X PATCH https://api.levrage.ai/v1/agents/{agent_id} \
>  -H "Authorization: Bearer $API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "description": "Updated description",
>    "voice": "male"
>  }'

Delete an Agent

$curl -X DELETE -H "Authorization: Bearer $API_KEY" \
>     "https://api.levrage.ai/v1/agents/{agent_id}"

Managing Prompts

Get Current Prompt

$curl -H "Authorization: Bearer $API_KEY" \
>     "https://api.levrage.ai/v1/agents/{agent_id}/prompt"

Update Prompt

$curl -X PUT https://api.levrage.ai/v1/agents/{agent_id}/prompt \
>  -H "Authorization: Bearer $API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "instructions": "You are a helpful sales agent for Acme Corp..."
>  }'

Prompt Versioning

Every prompt change creates a new version. You can list, restore, and delete versions:

$# List versions
$curl -H "Authorization: Bearer $API_KEY" \
>     "https://api.levrage.ai/v1/agents/{agent_id}/prompt/versions"
$
$# Restore a version
$curl -X POST -H "Authorization: Bearer $API_KEY" \
>     "https://api.levrage.ai/v1/agents/{agent_id}/prompt/versions/1/restore"
$
$# Delete a version
$curl -X DELETE -H "Authorization: Bearer $API_KEY" \
>     "https://api.levrage.ai/v1/agents/{agent_id}/prompt/versions/2"