Skip to navigation

Quickstart

This guide walks you through creating your first voice agent and making a call — all from the command line.

Prerequisites

  • A Levrage.AI account (sign up)
  • Your API key (Dashboard → Settings → Developers → API Keys)
  • A source phone number (available in Dashboard → Numbers)

Step 1: Verify Your API Key

Test that your API key works:

curl -H "Authorization: Bearer $API_KEY" \
https://api.levrage.ai/v1/health

Expected response:

{
"status": "ok"
}

Step 2: Browse Available Industries

Discover what agent types are available:

# List all industries
curl https://api.levrage.ai/v1/industries
# Get agent types for a specific industry
curl https://api.levrage.ai/v1/industries/Real%20Estate/agent-types

Step 3: Create a Voice Agent

curl -X POST https://api.levrage.ai/v1/agents \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Demo Sales Agent",
"agent_type": "sales",
"language": "English",
"voice": "female",
"ai_model": "lai-premium-2",
"start_flow": "Hello! This is Sarah from Demo Corp. How are you today?",
"end_flow": "Thank you so much for your time. Goodbye!",
"description": "Sales agent for demo purposes"
}'

Save the id from the response — you’ll need it for the next step.

The agent is automatically created with a production-ready prompt based on the agent_type and language you chose. You can also pass a custom prompt field to override it.

Step 4: Make a Call

curl -X POST https://api.levrage.ai/v1/call \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "YOUR_AGENT_ID",
"source_number": "+919240018601",
"phone_number": "+919876543210",
"metadata": {
"customer_name": "John",
"purpose": "demo"
}
}'

The call will be initiated immediately. You can track its status via the call history endpoint.

Calls go out between 9 AM and 9 PM in the called person’s own time. A call asked for outside those hours — say a “payment failed” event at 1 AM — is queued: the answer is 202 with status: "queued", the queued call’s id and scheduled_for, and the call is placed when the hours open. Another request for the same number on the same agent before then joins it (one call, the latest metadata). Follow it with GET /calls/queued/{id}, cancel it with DELETE /calls/queued/{id} (e.g. the customer paid in the meantime), or send "queue_outside_hours": false to be refused with 422 OUTSIDE_CALLING_HOURS instead. Once placed, its metadata carries queued_call_id, so your webhook can match the call to the request.

Call again if not answered. Add "retry": {"max_retries": 3, "interval_value": 30, "interval_unit": "minutes"} — the same settings as a campaign’s retries — and a call that gets no answer, a busy line or voicemail (on_statuses) is called again, up to max_retries times and always inside calling hours. Or switch it on once for every API call to an agent with voice_response_settings.api_call_retry (dashboard: the agent’s call settings), and leave your requests as they are; "retry": {"enabled": false} skips it for one call. A call that rang out answers status: "handled" with the queued call’s id and scheduled_for (the next try); each retry’s metadata carries queued_call_id and call_attempt. A newer call to the same person on the same agent replaces retries still to come, and DELETE /calls/queued/{id} stops them.

Step 5: Check Call History

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

Each call record includes:

  • status — completed, no_answer, failed, voicemail
  • duration — Call length in seconds
  • transcript — Full conversation transcript
  • recording_url — Link to the call recording
  • sentiment — AI-analyzed sentiment of the call
  • details_collection — Any data the agent collected

Step 6: Run a Batch Campaign (Optional)

Scale to multiple calls with a campaign:

curl -X POST https://api.levrage.ai/v1/campaigns \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "January Outreach",
"agent_id": "YOUR_AGENT_ID",
"phone_number": "+919240018601",
"phone_column": "phone",
"contacts": [
{"phone": "+919876543210", "name": "Alice"},
{"phone": "+919876543211", "name": "Bob"},
{"phone": "+919876543212", "name": "Charlie"}
],
"max_concurrent_calls": 2
}'

What’s Next?