Skip to main content
POST
/
api
/
v1
/
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"
  }
}

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 AI-powered 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. You can find this in your dashboard under Voice Agents.

​
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

​
to
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

CodeDescriptionHTTP Status
INVALID_PHONE_NUMBERPhone number format is invalid400
MISSING_PHONE_NUMBERPhone number is required400
INVALID_TOKENAuthentication token is invalid or missing401
AGENT_NOT_FOUNDSpecified agent does not exist404
AGENT_INACTIVEAgent is not published400
INSUFFICIENT_CREDITSAccount has insufficient credits402
RATE_LIMIT_EXCEEDEDToo many requests in a short time429

​
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

​
Best Practices

  1. Always handle errors gracefully — check for error responses and implement retry logic with exponential backoff.
  2. Store call IDs — use the returned data.id to track call status and correlate with webhook events.
  3. Use context for tracking — pass internal IDs in context so webhook events can be linked back to your system records.
  4. Use is_testing during integration — keeps test traffic out of analytics and avoids billing.
  5. Validate phone numbers before calling — ensure E.164 format (+ followed by country code and number).