Start Batch Calls

POSThttps://api.trillet.ai/v1/api/batch-calls

Headers

x-api-keystringrequired

API key used for authenticating requests to the API.

x-workspace-idstringrequired

Workspace identifier for the API.

Request Body

This endpoint accepts multipart/form-data with the following fields:

filefilerequired

CSV file containing the batch call data. Maximum file size: 20MB.

agentIdstringrequired

The ID of the agent that will be used to make the batch calls.

scheduledAtstring

UTC datetime string in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ) to schedule the batch for future execution. If not provided, batch starts immediately.

smartCallbackConfigstring

JSON string containing smart callback configuration. Format: {"enabled": boolean, "maxAttempts": number, "gaps": [{"days": number, "hours": number}]}

Testing Note: The "Try Now" button in this documentation doesn't support file uploads. Use the cURL example below or a tool like Postman to test this endpoint.

CSV File Format

The CSV file should contain the following columns:

phone_number - The phone number to call (required)
first_name - First name for personalization
last_name - Last name for personalization
email - Email address
Additional custom fields for dynamic variables

Response

batchIdstring

Unique identifier for the batch call operation

totalCallsnumber

Total number of calls that will be made in this batch

statusstring

Current status of the batch operation (e.g., "queued", "processing")

messagestring

Success message confirming the batch initiation

Example Usage

# Basic batch call
curl -X POST "https://api.trillet.ai/v1/api/batch-calls" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -F "file=@batch-calls.csv" \
  -F "agentId=agent_123456"

# Scheduled batch call with smart callback
curl -X POST "https://api.trillet.ai/v1/api/batch-calls" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -F "file=@batch-calls.csv" \
  -F "agentId=agent_123456" \
  -F "scheduledAt=2024-01-15T14:30:00Z" \
  -F "smartCallbackConfig={\"enabled\": true, \"maxAttempts\": 3, \"gaps\": [{\"days\": 1, \"hours\": 0}]}"

Example Response

{
  "batchId": "batch_7891011121314",
  "totalCalls": 150,
  "status": "queued",
  "message": "Batch calls initiated successfully"
}

Testing with Different Tools

# Basic usage
curl -X POST "https://api.trillet.ai/v1/api/batch-calls" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -F "file=@batch-calls.csv" \
  -F "agentId=agent_123456"

# With verbose output for debugging
curl -v -X POST "https://api.trillet.ai/v1/api/batch-calls" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -F "file=@batch-calls.csv" \
  -F "agentId=agent_123456"

# With scheduled time and smart callback
curl -X POST "https://api.trillet.ai/v1/api/batch-calls" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -F "file=@batch-calls.csv" \
  -F "agentId=agent_123456" \
  -F "scheduledAt=2024-01-15T14:30:00Z" \
  -F "smartCallbackConfig={\"enabled\": true, \"maxAttempts\": 5, \"gaps\": [{\"days\": 1, \"hours\": 0}, {\"days\": 2, \"hours\": 0}]}"

Processing Flow

File Upload: The CSV file is uploaded and validated
Record Validation: Each record in the CSV is validated for required fields
Batch Preparation: A batch configuration is created with the specified agent
Queue Initialization: Individual call jobs are queued for processing
Execution: Calls are made according to your account's rate limits (or at scheduled time)

Error Responses

errorstring

Error message describing what went wrong

Common Error Codes:

400 - No file uploaded, no agent ID provided, or CSV validation failed
413 - File size exceeds 20MB limit
500 - Failed to prepare batch or start batch execution

Rate Limits

Batch calls are subject to your account's rate limits. The system will automatically manage the call queue to respect these limits while maximizing throughput.