Trigger Outbound Call via API

Use the Edesy Calls API to programmatically trigger outbound voice calls from your application, CRM, or automation workflow.

Prerequisites

Before you begin, make sure you have:

1. An API Key - Generate one from Settings > API Keys in the Edesy Dashboard
2. An Agent ID - The voice agent that will handle the call. Find it in Agents page in the dashboard
3. A Phone Number - Either a platform-provided number or your own (BYOP)

Quick Start

Make a single API call to trigger an outbound call:

curl -X POST https://voice-agent.edesy.in/api/v1/calls \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "agentId": 123,
    "phoneNumber": "9876543210"
  }'

That is it. The agent will call the number and start the conversation using its configured prompt, language, and voice.

API Reference

Endpoint

POST /api/v1/calls

Authentication

Include your API key in the Authorization header:

Authorization: Bearer vp_live_xxxxxxxxxxxxxxxx

Your API key starts with vp_live_ (production) or vp_test_ (testing). The workspace is automatically identified from your API key - you do not need to pass a workspace ID.

Request Body

Response

Success (200)

{
  "success": true,
  "data": {
    "conversationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "callSid": "edesy-sip-xxxxxxxx",
    "status": "initiated"
  }
}

Error Responses

Error response format:

{
  "success": false,
  "error": "Missing agentId",
  "code": "MISSING_AGENT_ID"
}

Examples

Basic Call

Trigger a call with just the agent and phone number:

curl -X POST https://voice-agent.edesy.in/api/v1/calls \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer vp_live_your_api_key_here" \
  -d '{
    "agentId": 123,
    "phoneNumber": "9876543210"
  }'

Call with Variables

Pass dynamic data that the agent can use during the conversation. Variables are injected into the agent's prompt context:

curl -X POST https://voice-agent.edesy.in/api/v1/calls \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer vp_live_your_api_key_here" \
  -d '{
    "agentId": 123,
    "phoneNumber": "9876543210",
    "variables": {
      "customer_name": "Rahul",
      "order_id": "ORD-12345",
      "amount_due": "2500"
    }
  }'

Tip: Reference variables in your agent's system prompt using the variable name. For example: "The customer's name is {customer_name} and their order ID is {order_id}."

Call with Specific From Number

Specify which phone number the call should come from:

curl -X POST https://voice-agent.edesy.in/api/v1/calls \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer vp_live_your_api_key_here" \
  -d '{
    "agentId": 123,
    "phoneNumber": "9876543210",
    "fromNumber": "8065934975",
    "provider": "edesy-sip"
  }'

Call with Webhook Callback

Get notified when the call ends by providing a callback URL:

curl -X POST https://voice-agent.edesy.in/api/v1/calls \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer vp_live_your_api_key_here" \
  -d '{
    "agentId": 123,
    "phoneNumber": "9876543210",
    "callbackUrl": "https://your-server.com/call-webhook",
    "variables": {
      "customer_name": "Priya"
    }
  }'

The callback URL will receive a POST request when the call ends with details like duration, transcript, and outcome.

Code Examples

Python

import requests

API_KEY = "vp_live_your_api_key_here"
BASE_URL = "https://voice-agent.edesy.in/api/v1"

response = requests.post(
    f"{BASE_URL}/calls",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {API_KEY}",
    },
    json={
        "agentId": 123,
        "phoneNumber": "9876543210",
        "variables": {
            "customer_name": "Rahul",
            "order_id": "ORD-12345",
        },
    },
)

data = response.json()

if data.get("success"):
    print(f"Call initiated: {data['data']['conversationId']}")
else:
    print(f"Error: {data.get('error')}")

Node.js

const API_KEY = "vp_live_your_api_key_here";
const BASE_URL = "https://voice-agent.edesy.in/api/v1";

const response = await fetch(`${BASE_URL}/calls`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${API_KEY}`,
  },
  body: JSON.stringify({
    agentId: 123,
    phoneNumber: "9876543210",
    variables: {
      customer_name: "Rahul",
      order_id: "ORD-12345",
    },
  }),
});

const data = await response.json();

if (data.success) {
  console.log(`Call initiated: ${data.data.conversationId}`);
} else {
  console.error(`Error: ${data.error}`);
}

PHP

$apiKey = "vp_live_your_api_key_here";
$baseUrl = "https://voice-agent.edesy.in/api/v1";

$ch = curl_init("$baseUrl/calls");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "Authorization: Bearer $apiKey",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "agentId" => 123,
        "phoneNumber" => "9876543210",
        "variables" => [
            "customer_name" => "Rahul",
            "order_id" => "ORD-12345",
        ],
    ]),
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

if ($data["success"]) {
    echo "Call initiated: " . $data["data"]["conversationId"];
} else {
    echo "Error: " . $data["error"];
}

List Calls

Retrieve call history for your workspace:

curl "https://voice-agent.edesy.in/api/v1/calls" \
  -H "Authorization: Bearer vp_live_your_api_key_here"

Query Parameters

Example: Get Recent Calls for an Agent

curl "https://voice-agent.edesy.in/api/v1/calls?agentId=123&limit=10" \
  -H "Authorization: Bearer vp_live_your_api_key_here"

Response

{
  "success": true,
  "data": {
    "calls": [
      {
        "conversationId": "a1b2c3d4-...",
        "callSid": "edesy-sip-xxxxxxxx",
        "agentId": 123,
        "agentName": "Sales Agent",
        "phoneNumber": "9876543210",
        "status": "completed",
        "duration": 120,
        "source": "api",
        "startTime": "2026-04-10T06:25:00.000Z",
        "endTime": "2026-04-10T06:27:00.000Z"
      }
    ],
    "total": 1,
    "limit": 10,
    "offset": 0
  }
}

Bulk Calls

To trigger calls to multiple numbers, make separate API requests for each number. For large-scale campaigns (100+ contacts), we recommend using the Campaigns feature in the dashboard instead.

import requests
import time

API_KEY = "vp_live_your_api_key_here"
BASE_URL = "https://voice-agent.edesy.in/api/v1"

contacts = [
    {"phone": "9876543210", "name": "Rahul", "order_id": "ORD-001"},
    {"phone": "9876543211", "name": "Priya", "order_id": "ORD-002"},
    {"phone": "9876543212", "name": "Amit", "order_id": "ORD-003"},
]

for contact in contacts:
    response = requests.post(
        f"{BASE_URL}/calls",
        headers={
            "Content-Type": "application/json",
            "Authorization": f"Bearer {API_KEY}",
        },
        json={
            "agentId": 123,
            "phoneNumber": contact["phone"],
            "variables": {
                "customer_name": contact["name"],
                "order_id": contact["order_id"],
            },
        },
    )

    data = response.json()
    status = "OK" if data.get("success") else data.get("error")
    print(f"{contact['name']}: {status}")

    # Add a small delay between calls to avoid rate limits
    time.sleep(1)

Finding Your Agent ID

1. Go to the Edesy Dashboard
2. Navigate to Agents
3. Click on the agent you want to use
4. The Agent ID is shown in the URL: voice-agent.edesy.in/agents/{AGENT_ID}

Generating an API Key

1. Go to Settings > API Keys in the dashboard
2. Click Generate API Key
3. Copy the key immediately - it will not be shown again
4. Store it securely (environment variable, secrets manager, etc.)

Security: Never expose your API key in client-side code or public repositories. Always call the API from your backend server.

Troubleshooting

"Invalid API key" error

• Make sure the key starts with vp_live_
• Check that you are using the Authorization: Bearer header format
• Verify the key has not been revoked in Settings > API Keys

"Insufficient credits" error

• Check your credit balance in Billing > Credits
• Purchase more credits or upgrade your plan

Call not connecting

• Verify the phone number is valid and reachable
• Check if the fromNumber is configured correctly for your provider
• Ensure your agent is set to Active in the dashboard

No response from API

• Check that you are using POST method (not GET)
• Verify the Content-Type: application/json header is included
• Make sure the request body is valid JSON

Next Steps

• Webhook Subscriptions - Get notified on call events
• Function Calling - Let your agent call external APIs during conversations
• Variables & Templates - Personalize conversations with dynamic data
• Campaigns - Run large-scale outbound calling campaigns