Skip to main content
POST
/
v1
/
public
/
calls
/
outbound
curl -X POST "https://api.eigi.ai/v1/public/calls/outbound" \
  -H "X-API-Key: vk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "68ea2517dbb84c09bae1ba0a",
    "params": [
      {
        "mobile_number": "+919876543210",
        "metadata": {
          "customer_name": "John Doe",
          "customer_id": "CUST-12345"
        }
      }
    ],
    "telephony_provider": "PLIVO"
  }'

{
  "status": "success",
  "message": "Outbound calls initiated successfully"
}

​
Overview

This endpoint creates conversations and initiates outbound calls via telephony provider (Plivo or Twilio) to specified phone numbers using your configured AI agent. You can initiate single calls or bulk calls by providing multiple phone numbers.

​
Authentication

​
X-API-Key
string
required
Your eigi.ai API key. Must be prefixed with vk_.

​
Request Body

​
agent_id
string
required
The ID of the AI agent to use for the call. The agent must be owned by the API key holder and properly configured with LLM, TTS, and STT providers.Example: 68ea2517dbb84c09bae1ba0a
​
params
array
required
Array of call parameter objects. Each object represents one outbound call to initiate. Each item should have mobile_number (string, required) in E.164 format and optional metadata object.
​
telephony_provider
string
default:"PLIVO"
Telephony provider to use for the call. Options: PLIVO or TWILIODefaults to PLIVO if not specified.

​
Response

​
status
string
Status of the request: success
​
message
string
Human-readable message describing the result: Outbound calls initiated successfully
The API initiates calls asynchronously. Use webhooks or poll the Get Conversation endpoint with the conversation ID to track call status and retrieve transcripts after completion.
curl -X POST "https://api.eigi.ai/v1/public/calls/outbound" \
  -H "X-API-Key: vk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "68ea2517dbb84c09bae1ba0a",
    "params": [
      {
        "mobile_number": "+919876543210",
        "metadata": {
          "customer_name": "John Doe",
          "customer_id": "CUST-12345"
        }
      }
    ],
    "telephony_provider": "PLIVO"
  }'

{
  "status": "success",
  "message": "Outbound calls initiated successfully"
}

​
Error Responses

​
Status Codes

Status CodeDescription
200Calls initiated (check individual result status)
400Missing parameters or agent not configured
401Missing, invalid, inactive, or expired API key
403User not authorized for agent or quota exceeded
404User or agent not found
500Internal server error

​
Phone Number Format

Phone numbers must be in E.164 format:
  • Start with + followed by country code
  • No spaces, dashes, or parentheses
  • Example: +919876543210 (India), +14155551234 (US)
Invalid formats will result in failed calls: - ❌ 9876543210 (missing country code) - ❌ +91 98765 43210 (contains spaces) - ❌ +91-9876543210 (contains dashes) - ✅ +919876543210 (correct format)

​
Use Cases

Initiate bulk calls to customers for product updates, surveys, or promotional campaigns. Track results using conversation IDs.
Automatically call customers to remind them of upcoming appointments, reducing no-shows and improving scheduling efficiency.
Call leads from your CRM to qualify them and schedule meetings with sales teams. Pass customer data via metadata for personalized conversations.
Initiate calls to customers with pending payments, providing personalized reminders and payment options.
Call customers after service interactions to gather feedback and measure satisfaction using AI-powered surveys.
Quickly notify customers of urgent issues, service disruptions, or critical updates through automated voice calls.

​
Best Practices

Use Metadata Effectively: Include relevant customer information in the metadata field. Your agent can access this data during the conversation for personalization.
"metadata": {
  "customer_name": "John Doe",
  "customer_id": "CUST-12345",
  "order_id": "ORD-67890",
  "appointment_date": "2025-12-15"
}
Batch Processing: For bulk calls, process in batches of 50-100 numbers to manage rate limits and monitor results effectively.
Error Handling: Always check individual status in the results array, as some calls may succeed while others fail.
Track Conversation IDs: Store the returned conversation_id for each call to later retrieve transcripts and analysis using the Get Conversation endpoint.

​
Webhooks for Call Events

Configure webhooks to receive real-time notifications about call events:
  • conversation.started - Call initiated
  • conversation.answered - Call answered by recipient
  • conversation.completed - Call completed successfully
  • conversation.failed - Call failed
  • conversation.disconnected - Call disconnected
Learn more in the Webhook Documentation.

​
Limitations

  • Rate Limits: API key tier determines maximum calls per minute
  • Daily Quota: Check your plan’s daily outbound call limit
  • Agent Configuration: Agent must have valid telephony settings (Plivo/Twilio credentials, phone number)
  • Phone Number Validation: Invalid phone numbers will fail individually without blocking other calls

​
Notes

  • Each call creates a unique conversation_id for tracking
  • Calls are initiated asynchronously; use webhooks or polling for status updates
  • Failed calls don’t count against your quota
  • Metadata is optional but highly recommended for personalized conversations
  • Call recording and transcription are automatic (if enabled in agent settings)
  • Default telephony provider is Plivo; specify TWILIO if using Twilio

Authorizations

​
X-API-Key
string
header
required

API key for authentication. Get your API key from the eigi.ai Dashboard under Settings → API Keys.

Body

application/json
​
agent_id
string
required

The ID of the AI agent to use for the call

Example:

"68ea2517dbb84c09bae1ba0a"

​
params
object[]
required

Array of call parameter objects

​
telephony_provider
enum<string>
default:PLIVO

Telephony provider to use

Available options:
PLIVO,
TWILIO

Response

Calls initiated successfully

​
status
string
Example:

"success"

​
message
string
Example:

"Outbound calls initiated successfully"