> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eigi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Initiate Outbound Call

> Initiate one or more outbound calls to phone numbers using AI voice agents

## 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

<ParamField header="X-API-Key" type="string" required>
  Your eigi.ai API key. Must be prefixed with `vk_`.
</ParamField>

## Request Body

<ParamField body="agent_id" type="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`
</ParamField>

<ParamField body="params" type="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.
</ParamField>

<ParamField body="telephony_provider" type="string" default="PLIVO">
  Telephony provider to use for the call. Options: `PLIVO` or `TWILIO`

  Defaults to `PLIVO` if not specified.
</ParamField>

## Response

<ResponseField name="status" type="string">
  Status of the request: `success`
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable message describing the result: `Outbound calls initiated
      successfully`
</ResponseField>

<Note>
  The API initiates calls asynchronously. Use webhooks or poll the [Get
  Conversation](/api-reference/public/get-conversation) endpoint with the
  conversation ID to track call status and retrieve transcripts after
  completion.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript Node.js theme={null}
  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);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "status": "success",
    "message": "Outbound calls initiated successfully"
  }
  ```

  ```json 400 - Missing Agent ID theme={null}
  {
    "detail": "agent_id is required"
  }
  ```

  ```json 400 - Missing Params theme={null}
  {
    "detail": "Parameters are required for the outbound call"
  }
  ```

  ```json 400 - Agent Not Configured theme={null}
  {
    "detail": "Agent has no mobile numbers configured for outbound calls"
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "detail": "Invalid API key"
  }
  ```

  ```json 403 - Forbidden theme={null}
  {
    "detail": "You are not authorized to access this agent"
  }
  ```

  ```json 403 - Quota Exceeded theme={null}
  {
    "detail": "Call quota exceeded"
  }
  ```

  ```json 404 - Agent Not Found theme={null}
  {
    "detail": "Agent with id xxx not found"
  }
  ```

  ```json 404 - User Not Found theme={null}
  {
    "detail": "User not found"
  }
  ```

  ```json 500 - Internal Server Error theme={null}
  {
    "detail": "Internal Server Error: [error details]"
  }
  ```
</ResponseExample>

## 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)

<Warning>
  **Invalid formats** will result in failed calls: - ❌ `9876543210` (missing
  country code) - ❌ `+91 98765 43210` (contains spaces) - ❌ `+91-9876543210`
  (contains dashes) - ✅ `+919876543210` (correct format)
</Warning>

## Use Cases

<AccordionGroup>
  <Accordion title="Customer Outreach Campaigns">
    Initiate bulk calls to customers for product updates, surveys, or
    promotional campaigns. Track results using conversation IDs.
  </Accordion>

  <Accordion title="Appointment Reminders">
    Automatically call customers to remind them of upcoming appointments,
    reducing no-shows and improving scheduling efficiency.
  </Accordion>

  <Accordion title="Lead Qualification">
    Call leads from your CRM to qualify them and schedule meetings with sales
    teams. Pass customer data via metadata for personalized conversations.
  </Accordion>

  <Accordion title="Payment Reminders">
    Initiate calls to customers with pending payments, providing personalized
    reminders and payment options.
  </Accordion>

  <Accordion title="Customer Satisfaction Surveys">
    Call customers after service interactions to gather feedback and measure
    satisfaction using AI-powered surveys.
  </Accordion>

  <Accordion title="Emergency Notifications">
    Quickly notify customers of urgent issues, service disruptions, or critical
    updates through automated voice calls.
  </Accordion>
</AccordionGroup>

## Best Practices

<Tip>
  **Use Metadata Effectively**: Include relevant customer information in the `metadata` field. Your agent can access this data during the conversation for personalization.

  ```json theme={null}
  "metadata": {
    "customer_name": "John Doe",
    "customer_id": "CUST-12345",
    "order_id": "ORD-67890",
    "appointment_date": "2025-12-15"
  }
  ```
</Tip>

<Tip>
  **Batch Processing**: For bulk calls, process in batches of 50-100 numbers to
  manage rate limits and monitor results effectively.
</Tip>

<Tip>
  **Error Handling**: Always check individual `status` in the results array, as
  some calls may succeed while others fail.
</Tip>

<Tip>
  **Track Conversation IDs**: Store the returned `conversation_id` for each call
  to later retrieve transcripts and analysis using the [Get
  Conversation](/api-reference/public/get-conversation) endpoint.
</Tip>

## 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](/api-reference/endpoint/webhook).

## 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


## OpenAPI

````yaml POST /v1/public/calls/outbound
openapi: 3.0.0
info:
  title: eigi.ai API
  description: REST API for managing AI voice agents and conversations
  version: 1.0.0
  contact:
    email: buddy@eigi.ai
    url: https://eigi.ai
servers:
  - url: https://api.eigi.ai
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /v1/public/calls/outbound:
    post:
      tags:
        - Conversations
      summary: Initiate Outbound Call
      description: >-
        Create and initiate one or more outbound calls to phone numbers using AI
        voice agents
      operationId: createOutboundCall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OutboundCallRequest'
            examples:
              single_call:
                summary: Single outbound call
                value:
                  agent_id: 68ea2517dbb84c09bae1ba0a
                  params:
                    - mobile_number: '+919876543210'
                      metadata:
                        customer_name: John Doe
                        customer_id: CUST-12345
                  telephony_provider: PLIVO
              multiple_calls:
                summary: Multiple outbound calls
                value:
                  agent_id: 68ea2517dbb84c09bae1ba0a
                  params:
                    - mobile_number: '+919876543210'
                      metadata:
                        customer_name: John Doe
                    - mobile_number: '+918765432109'
                      metadata:
                        customer_name: Jane Smith
      responses:
        '200':
          description: Calls initiated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: Outbound calls initiated successfully
        '400':
          description: Bad request - Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - Invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Not authorized or quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: User or agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    OutboundCallRequest:
      type: object
      required:
        - agent_id
        - params
      properties:
        agent_id:
          type: string
          description: The ID of the AI agent to use for the call
          example: 68ea2517dbb84c09bae1ba0a
        params:
          type: array
          description: Array of call parameter objects
          items:
            type: object
            required:
              - mobile_number
            properties:
              mobile_number:
                type: string
                description: Phone number to call in E.164 format
                example: '+919876543210'
              metadata:
                type: object
                description: Custom metadata to attach to the conversation
                example:
                  customer_name: John Doe
                  customer_id: CUST-12345
        telephony_provider:
          type: string
          enum:
            - PLIVO
            - TWILIO
          default: PLIVO
          description: Telephony provider to use
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Error message
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        API key for authentication. Get your API key from the eigi.ai Dashboard
        under Settings → API Keys.

````