Initiate Outbound Call

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"
  }'

import requests

headers = {
    "X-API-Key": "vk_your_api_key_here",
    "Content-Type": "application/json"
}

payload = {
    "agent_id": "68ea2517dbb84c09bae1ba0a",
    "params": [
        {
            "mobile_number": "+919876543210",
            "metadata": {
                "customer_name": "John Doe"
            }
        }
    ],
    "telephony_provider": "PLIVO"
}

response = requests.post(
    "https://api.eigi.ai/v1/public/calls/outbound",
    headers=headers,
    json=payload
)

print(response.json())

const axios = require("axios");

const response = await axios.post(
  "https://api.eigi.ai/v1/public/calls/outbound",
  {
    agent_id: "68ea2517dbb84c09bae1ba0a",
    params: [
      {
        mobile_number: "+919876543210",
        metadata: { customer_name: "John Doe" },
      },
    ],
    telephony_provider: "PLIVO",
  },
  {
    headers: {
      "X-API-Key": "vk_your_api_key_here",
      "Content-Type": "application/json",
    },
  }
);

console.log(response.data);

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

{
  "detail": "agent_id is required"
}

{
  "detail": "Parameters are required for the outbound call"
}

{
  "detail": "Agent has no mobile numbers configured for outbound calls"
}

{
  "detail": "Invalid API key"
}

{
  "detail": "You are not authorized to access this agent"
}

{
  "detail": "Call quota exceeded"
}

{
  "detail": "Agent with id xxx not found"
}

{
  "detail": "User not found"
}

{
  "detail": "Internal Server Error: [error details]"
}

POST

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"
  }'

import requests

headers = {
    "X-API-Key": "vk_your_api_key_here",
    "Content-Type": "application/json"
}

payload = {
    "agent_id": "68ea2517dbb84c09bae1ba0a",
    "params": [
        {
            "mobile_number": "+919876543210",
            "metadata": {
                "customer_name": "John Doe"
            }
        }
    ],
    "telephony_provider": "PLIVO"
}

response = requests.post(
    "https://api.eigi.ai/v1/public/calls/outbound",
    headers=headers,
    json=payload
)

print(response.json())

const axios = require("axios");

const response = await axios.post(
  "https://api.eigi.ai/v1/public/calls/outbound",
  {
    agent_id: "68ea2517dbb84c09bae1ba0a",
    params: [
      {
        mobile_number: "+919876543210",
        metadata: { customer_name: "John Doe" },
      },
    ],
    telephony_provider: "PLIVO",
  },
  {
    headers: {
      "X-API-Key": "vk_your_api_key_here",
      "Content-Type": "application/json",
    },
  }
);

console.log(response.data);

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

{
  "detail": "agent_id is required"
}

{
  "detail": "Parameters are required for the outbound call"
}

{
  "detail": "Agent has no mobile numbers configured for outbound calls"
}

{
  "detail": "Invalid API key"
}

{
  "detail": "You are not authorized to access this agent"
}

{
  "detail": "Call quota exceeded"
}

{
  "detail": "Agent with id xxx not found"
}

{
  "detail": "User not found"
}

{
  "detail": "Internal Server Error: [error details]"
}

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

string

required

Your eigi.ai API key. Must be prefixed with vk_.

Request Body

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

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.

string

default:"PLIVO"

Telephony provider to use for the call. Options: PLIVO or TWILIODefaults to PLIVO if not specified.

Response

string

Status of the request: success

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"
  }'

import requests

headers = {
    "X-API-Key": "vk_your_api_key_here",
    "Content-Type": "application/json"
}

payload = {
    "agent_id": "68ea2517dbb84c09bae1ba0a",
    "params": [
        {
            "mobile_number": "+919876543210",
            "metadata": {
                "customer_name": "John Doe"
            }
        }
    ],
    "telephony_provider": "PLIVO"
}

response = requests.post(
    "https://api.eigi.ai/v1/public/calls/outbound",
    headers=headers,
    json=payload
)

print(response.json())

const axios = require("axios");

const response = await axios.post(
  "https://api.eigi.ai/v1/public/calls/outbound",
  {
    agent_id: "68ea2517dbb84c09bae1ba0a",
    params: [
      {
        mobile_number: "+919876543210",
        metadata: { customer_name: "John Doe" },
      },
    ],
    telephony_provider: "PLIVO",
  },
  {
    headers: {
      "X-API-Key": "vk_your_api_key_here",
      "Content-Type": "application/json",
    },
  }
);

console.log(response.data);

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

{
  "detail": "agent_id is required"
}

{
  "detail": "Parameters are required for the outbound call"
}

{
  "detail": "Agent has no mobile numbers configured for outbound calls"
}

{
  "detail": "Invalid API key"
}

{
  "detail": "You are not authorized to access this agent"
}

{
  "detail": "Call quota exceeded"
}

{
  "detail": "Agent with id xxx not found"
}

{
  "detail": "User not found"
}

{
  "detail": "Internal Server Error: [error details]"
}

Error Responses

Status Codes

Status Code	Description
200	Calls initiated (check individual result status)
400	Missing parameters or agent not configured
401	Missing, invalid, inactive, or expired API key
403	User not authorized for agent or quota exceeded
404	User or agent not found
500	Internal 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

Customer Outreach Campaigns

Initiate bulk calls to customers for product updates, surveys, or promotional campaigns. Track results using conversation IDs.

Appointment Reminders

Automatically call customers to remind them of upcoming appointments, reducing no-shows and improving scheduling efficiency.

Lead Qualification

Call leads from your CRM to qualify them and schedule meetings with sales teams. Pass customer data via metadata for personalized conversations.

Payment Reminders

Initiate calls to customers with pending payments, providing personalized reminders and payment options.

Customer Satisfaction Surveys

Call customers after service interactions to gather feedback and measure satisfaction using AI-powered surveys.

Emergency Notifications

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

Show child attributes

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"

Overview

Conversations

Chat

Prompts

Agents

Utilities

Overview

Authentication

Request Body

Response

Error Responses

Status Codes

Phone Number Format

Use Cases

Best Practices

Webhooks for Call Events

Limitations

Notes

Authorizations

Body

Response

​Overview

​Authentication

​Request Body

​Response

​Error Responses

​Status Codes

​Phone Number Format

​Use Cases

​Best Practices

​Webhooks for Call Events

​Limitations

​Notes

Authorizations

Body

Response

Overview

Authentication

Request Body

Response

Error Responses

Status Codes

Phone Number Format

Use Cases

Best Practices

Webhooks for Call Events

Limitations

Notes