> ## Documentation Index
> Fetch the complete documentation index at: https://docs.weya.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Add Calls to Batch
> Queue one or more contacts in an existing batch before launching the dialer.
## Overview
After creating a batch you can enqueue contact records that the dialer should process. Each record can include any custom fields your agent definition expects. Validation runs against the agent’s variable schema so you catch missing data before the dialer starts.
## Prerequisites
* You created the batch and captured its `batchId`.
* All required agent variables are present in every contact.
* The API key you use owns the batch.
## Request
Workspace API key. Must match the owner of the target batch.
Identifier returned by `POST /api/call/createBatch`.
Array of call records to be added to the batch. Each object MUST include `phoneNumber`. All other fields are flexible and determined by your agent's configuration. The system automatically chunks large arrays (1000 records per chunk) for efficient processing.
```bash cURL theme={null}
curl -X POST '{{baseUrl}}/api/call/addCallsToBatch' \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"batchId": "64e5f12345abcdef98765432",
"callData": [
{
"phoneNumber": "+918800000000",
"name": "Hasan Ali",
"amount": "500.00",
},
{
"phoneNumber": "+919900000000",
"name": "Test User",
"amount": "100.00"
}
]
}'
```
## Response
```json 200 OK theme={null}
{
"message": "Calls enqueued successfully",
"status": true,
"code": 200,
"errorMessage": "",
"data": {
"added": 2,
"callIds": ["64e5f12345abcdef11111111", "64e5f12345abcdef22222222"]
}
}
```
```json 207 Partial Content theme={null}
{
"message": "Some calls failed to enqueue",
"status": false,
"code": 207,
"errorMessage": "Partial content, check failedChunks for details",
"data": {
"added": 1,
"callIds": ["64e5f12345abcdef11111111"],
"failedChunks": [
{
"chunkNum": 2,
"error": "Database connection error"
}
]
}
}
```
A human-readable message indicating the outcome.
Indicates whether the operation was entirely successful. If `false` and `code` is 207, check `data.failedChunks`.
The HTTP status code (200 for full success, 207 for partial success).
Error message, if any.
Contains details about the operation.
Total number of call records successfully added to the batch across all chunks.
Array of call record IDs that were inserted or updated.
Present when `status` is `false` and `code` is 207. Array of chunk processing failures, each containing `chunkNum` and `error` message.
## Error Handling
* **400 Bad Request** – Missing `batchId`, empty `callData` array, or validation failure.
* **403 Forbidden** – Invalid or missing API key, or API key doesn't own the batch.
* **404 Not Found** – Batch not found, or no agent found for the batch's calling numbers.
* **207 Partial Content** – Some chunks processed successfully while others failed. Check `failedChunks` for details.
* **500 Internal Server Error** – Server error during processing; retry with exponential backoff.
**Flexible Parameters:**
The `callData` array accepts any custom key-value pairs beyond the required `phoneNumber` field. You can include any parameters your agent needs:
* Customer identifiers (e.g., `account_id`, `customer_id`, `unique_id`)
* Custom data fields (e.g., `custom_field_1`, `custom_field_2`, `priority`)
* Business-specific data (e.g., `order_amount`, `subscription_tier`, `category`)
* Any other data your AI agent requires for the conversation
**Important:** Each object in `callData` MUST include `phoneNumber`. All other fields are flexible and determined by your agent's configuration.
**Processing Details:**
* Large arrays are automatically chunked into batches of 1000 records for efficient processing
* Each call record is validated against the agent's required variables
* Existing calls with the same phone number are updated if they have a "pending" status
* Completed calls create new phone log entries
* The system automatically starts the calling service after successful insertion
* Timezone information is applied to each call record if not provided
You can safely enqueue thousands of contacts in a single request. The system handles chunking automatically. Monitor the response for `status: false` and `code: 207` to identify any failed chunks that may need retry.
## OpenAPI
````yaml POST /api/call/addCallsToBatch
openapi: 3.1.0
info:
title: Weya AI Public API
description: >-
Public API documentation for Weya AI platform - Call Management and DNC (Do
Not Call) APIs
version: 1.0.0
servers:
- url: >-
https://nexusdev-wjs-api-dev.mangoforest-291de162.swedencentral.azurecontainerapps.io
description: Development server
security:
- bearerAuth: []
- apiKeyAuth: []
paths:
/api/call/addCallsToBatch:
post:
tags:
- Call Management
summary: Add calls to batch
description: >-
Queue one or more contacts in an existing batch before launching the
dialer
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- batchId
- callData
properties:
batchId:
type: string
example: 64e5f12345abcdef98765432
callData:
type: array
description: >-
Array of call records. Each object MUST include phoneNumber.
All other fields are flexible and determined by your agent
configuration.
items:
type: object
required:
- phoneNumber
properties:
phoneNumber:
type: string
example: '12125551001'
description: Phone number with country code (required)
name:
type: string
example: Sarah Johnson
description: Customer name
account_id:
type: string
example: ACC-1001
description: Account identifier
custom_field_1:
type: string
example: value1
description: Any custom field your agent needs
priority:
type: string
example: high
description: Priority level
category:
type: string
example: support
description: Category or type
additionalProperties: true
responses:
'200':
description: Calls enqueued
'207':
description: Partial content, some chunks failed
'400':
description: Missing required fields or validation failure
'403':
description: Invalid API key
'404':
description: Batch or agent not found
'500':
description: Internal Server Error
security:
- bearerAuth: []
- apiKeyAuth: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Bearer token authentication for workspace access
apiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
API key used for programmatic calling integrations. Find it under
Settings → API access in your workspace.
````