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

{
  "success": true,
  "data": {
    "id": "call_789012",
    "agent_id": "agent_123456",
    "to": "+1234567890",
    "status": "initiated",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

POST

api

agents

{agent_id}

call

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

{
  "success": true,
  "data": {
    "id": "call_789012",
    "agent_id": "agent_123456",
    "to": "+1234567890",
    "status": "initiated",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

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.

Endpoint

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

Path parameters

agent_id

string

required

The unique identifier of the voice agent that will handle the call.

Request headers

Authorization

string

required

Bearer token for authentication. Format: Bearer talq_your_environment_token_here

Content-Type

string

required

Must be set to application/json

Request body

string

required

The phone number to call. Must be in international format (e.g., +1234567890).

payload

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.

context

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.

delay_seconds

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.

is_testing

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.

Examples

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

Response

Success Response (200 OK)

{
  "success": true,
  "data": {
    "id": "call_789012",
    "agent_id": "agent_123456",
    "to": "+1234567890",
    "status": "initiated",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Response fields

success

boolean

required

Indicates whether the request was processed successfully.

data.id

string

required

Unique identifier for the call. Use this ID to track the call status, retrieve call details, or correlate with webhook events.

data.agent_id

string

The ID of the voice agent handling the call.

data.to

string

required

The phone number that was called.

data.status

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

data.created_at

string

required

ISO 8601 timestamp when the call was created.

Error responses

400 Bad Request

{
  "error": {
    "code": "INVALID_PHONE_NUMBER",
    "message": "Phone number must be in international format (e.g., +1234567890)",
    "details": {
      "field": "to",
      "value": "1234567890"
    }
  }
}

401 Unauthorized

{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Invalid or missing authentication token"
  }
}

404 Not Found

{
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "Voice agent not found",
    "details": {
      "agent_id": "agent_999999"
    }
  }
}

402 Payment Required

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Account has insufficient credits to place this call"
  }
}

429 Too Many Requests

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please wait before making more requests.",
    "details": {
      "retry_after": 60
    }
  }
}

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

Make a Campaign Call — place calls scheduled by a campaign.
List Calls — retrieve historical calls.
Get Agent — fetch agent configuration.

List Agent Flow Versions Make Campaign Call

​Make a Call

​Endpoint

​Path parameters

​Request headers

​Request body

​Examples

​Response

​Success Response (200 OK)

​Response fields

​Error responses

​400 Bad Request

​401 Unauthorized

​404 Not Found

​402 Payment Required

​429 Too Many Requests

​Error codes

​Rate limits

​Related endpoints

Make a Call

Endpoint

Path parameters

Request headers

Request body

Examples

Response

Success Response (200 OK)

Response fields

Error responses

400 Bad Request

401 Unauthorized

404 Not Found

402 Payment Required

429 Too Many Requests

Error codes

Rate limits

Related endpoints