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

# Make a Call

> Initiate an call using a voice agent

# Make a Call

Initiate an call using a specific voice agent. This endpoint creates a new call and returns call details including a unique call ID.

For campaign-based calls, see [Make a Campaign Call](/api-reference/endpoints/make-campaign-call).

## Endpoint

```
POST /api/v1/agents/{agent_id}/call
```

## Path parameters

<ParamField path="agent_id" type="string" required>
  The unique identifier of the voice agent that will handle the call.
</ParamField>

## Request headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer talq_your_environment_token_here`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be set to `application/json`
</ParamField>

## Request body

<ParamField body="to" type="string" required>
  The phone number to call. Must be in international format (e.g., `+1234567890`).
</ParamField>

<ParamField body="payload" type="object">
  Replacement variables for the agent prompt. Use this to personalize the conversation with dynamic data. Keys should match placeholders in your agent's prompt.
</ParamField>

<ParamField body="context" type="object">
  Custom data to be sent back to your client via webhooks. This data is not used in the conversation but will be included in all webhook events related to this call, allowing you to track and associate calls with your internal records.
</ParamField>

<ParamField body="delay_seconds" type="integer" default="0">
  Number of seconds to delay before placing the call. Range: `0`–`3600` (1 hour). Useful for scheduling a call a few seconds or minutes after a triggering event.
</ParamField>

<ParamField body="is_testing" type="boolean" default="false">
  When `true`, the call is marked as a test. Test calls do not consume billing credits and are excluded from analytics aggregates.
</ParamField>

## Examples

<RequestExample>
  ```bash theme={null}
  curl -X POST "https://app.talkover.ai/api/v1/agents/agent_123456/call" \
    -H "Authorization: Bearer talq_your_environment_token_here" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "+1234567890",
      "payload": {
        "customer_name": "John Doe",
        "account_id": "ACC123"
      },
      "context": {
        "user_id": "user_123",
        "source": "web_app"
      },
      "delay_seconds": 0,
      "is_testing": false
    }'
  ```

  ```javascript theme={null}
  const response = await fetch('https://app.talkover.ai/api/v1/agents/agent_123456/call', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer talq_your_environment_token_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: '+1234567890',
      payload: {
        customer_name: 'John Doe',
        account_id: 'ACC123'
      },
      context: {
        user_id: 'user_123',
        source: 'web_app'
      },
      delay_seconds: 0,
      is_testing: false
    })
  });

  const result = await response.json();
  ```

  ```python theme={null}
  import requests

  url = "https://app.talkover.ai/api/v1/agents/agent_123456/call"
  headers = {
      "Authorization": "Bearer talq_your_environment_token_here",
      "Content-Type": "application/json"
  }
  data = {
      "to": "+1234567890",
      "payload": {
          "customer_name": "John Doe",
          "account_id": "ACC123"
      },
      "context": {
          "user_id": "user_123",
          "source": "web_app"
      },
      "delay_seconds": 0,
      "is_testing": False
  }

  response = requests.post(url, headers=headers, json=data)
  result = response.json()
  ```
</RequestExample>

## Response

### Success Response (200 OK)

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "id": "call_789012",
      "agent_id": "agent_123456",
      "to": "+1234567890",
      "status": "initiated",
      "created_at": "2024-01-15T10:30:00Z"
    }
  }
  ```
</ResponseExample>

### Response fields

<ResponseField name="success" type="boolean" required>
  Indicates whether the request was processed successfully.
</ResponseField>

<ResponseField name="data.id" type="string" required>
  Unique identifier for the call. Use this ID to track the call status, retrieve call details, or correlate with webhook events.
</ResponseField>

<ResponseField name="data.agent_id" type="string">
  The ID of the voice agent handling the call.
</ResponseField>

<ResponseField name="data.to" type="string" required>
  The phone number that was called.
</ResponseField>

<ResponseField name="data.status" type="string" required>
  Current status of the call. Possible values:

  * `initiated` - Call has been created and is being processed
  * `ringing` - Phone is ringing
  * `answered` - Call is active and conversation is happening
  * `completed` - Call has finished successfully
  * `failed` - Call failed
  * `busy` - Phone was busy
  * `no-answer` - Phone rang but was not answered
</ResponseField>

<ResponseField name="data.created_at" type="string" required>
  ISO 8601 timestamp when the call was created.
</ResponseField>

## Error responses

### 400 Bad Request

<ResponseExample>
  ```json theme={null}
  {
    "error": {
      "code": "INVALID_PHONE_NUMBER",
      "message": "Phone number must be in international format (e.g., +1234567890)",
      "details": {
        "field": "to",
        "value": "1234567890"
      }
    }
  }
  ```
</ResponseExample>

### 401 Unauthorized

<ResponseExample>
  ```json theme={null}
  {
    "error": {
      "code": "INVALID_TOKEN",
      "message": "Invalid or missing authentication token"
    }
  }
  ```
</ResponseExample>

### 404 Not Found

<ResponseExample>
  ```json theme={null}
  {
    "error": {
      "code": "AGENT_NOT_FOUND",
      "message": "Voice agent not found",
      "details": {
        "agent_id": "agent_999999"
      }
    }
  }
  ```
</ResponseExample>

### 402 Payment Required

<ResponseExample>
  ```json theme={null}
  {
    "error": {
      "code": "INSUFFICIENT_CREDITS",
      "message": "Account has insufficient credits to place this call"
    }
  }
  ```
</ResponseExample>

### 429 Too Many Requests

<ResponseExample>
  ```json theme={null}
  {
    "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "message": "Rate limit exceeded. Please wait before making more requests.",
      "details": {
        "retry_after": 60
      }
    }
  }
  ```
</ResponseExample>

## Error codes

| Code                   | Description                                | HTTP Status |
| ---------------------- | ------------------------------------------ | ----------- |
| `INVALID_PHONE_NUMBER` | Phone number format is invalid             | 400         |
| `MISSING_PHONE_NUMBER` | Phone number is required                   | 400         |
| `INVALID_TOKEN`        | Authentication token is invalid or missing | 401         |
| `AGENT_NOT_FOUND`      | Specified agent does not exist             | 404         |
| `AGENT_INACTIVE`       | Agent is not published                     | 400         |
| `INSUFFICIENT_CREDITS` | Account has insufficient credits           | 402         |
| `RATE_LIMIT_EXCEEDED`  | Too many requests in a short time          | 429         |

## Rate limits

Rate limit headers are included in all responses:

* `X-RateLimit-Limit`: Maximum requests per window
* `X-RateLimit-Remaining`: Remaining requests in current window
* `X-RateLimit-Reset`: Time when the rate limit resets

## Related endpoints

* [Make a Campaign Call](/api-reference/endpoints/make-campaign-call) — place calls scheduled by a campaign.
* [List Calls](/api-reference/endpoints/list-calls) — retrieve historical calls.
* [Get Agent](/api-reference/endpoints/get-agent) — fetch agent configuration.