> ## 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.

# Start Batch Dialing

> Push a prepared batch into the outbound dialer queue.

## Overview

Use this endpoint to kick off automated dialing for a batch once all data checks pass. The call processing runs asynchronously—responses confirm that the batch moved to the queue while individual call events continue to arrive through webhooks and batch polling.

## Prerequisites

* Batch already exists and contains the final contact list.
* The authenticated user has Calling Management permissions.
* Plivo webhooks are configured if you need real-time updates.

## Request

<ParamField header="Authorization" type="string" required>
  Bearer token for an approved workspace administrator.
</ParamField>

<ParamField body="batchId" type="string" required>
  Identifier of the batch to start dialing.
</ParamField>

<ParamField body="userId" type="string" required>
  ID of the user who owns the batch.
</ParamField>

<ParamField body="callingNumbers" type="array[string]">
  Phone IDs the dialer should rotate through. Optional if batch already has calling numbers configured.
</ParamField>

<ParamField body="callData" type="array[object]">
  Call records to process. Optional if batch already contains calls. If provided, these calls will be processed instead of existing batch calls.
</ParamField>

<ParamField body="uuid" type="string">
  Optional UUID for tracking this calling session.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location '{{baseUrl}}/api/call/start-calling' \
    --header 'Authorization: Bearer {{authToken}}' \
    --header 'Content-Type: application/json' \
    --data '{
      "batchId": "6806382f98da85ec32fac955",
      "userId": "64e5f12345abcdef12345678"
    }'
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "message": "",
    "status": true,
    "code": 200,
    "errorMessage": "",
    "data": {
      "batchId": "6806382f98da85ec32fac955",
      "status": "started"
    }
  }
  ```
</ResponseExample>

<ResponseField name="status" type="boolean" required>
  Indicates whether the batch was successfully queued for dialing.
</ResponseField>

<ResponseField name="code" type="integer" required>
  HTTP status code (200 for success).
</ResponseField>

<ResponseField name="data" type="object">
  Additional information about the started batch.
</ResponseField>

## Error Handling

* **400 Bad Request** – Missing required parameters (`batchId` or `userId`).
* **401 Unauthorized** – Bearer token missing or expired.
* **404 Not Found** – Batch not found or user not found.
* **500 Internal Server Error** – Failed to start calling service; retry or contact support.

<Note>
  **Calling Behavior:**

  * If `callData` is provided, those calls will be processed (useful for immediate calling)
  * If `callData` is not provided, the system uses existing calls in the batch
  * The calling service runs asynchronously
  * Calls are queued and processed based on batch configuration (calling hours, allowed days, etc.)
  * Monitor progress using `GET /api/call/batch-details/{batchId}` or webhook callbacks
</Note>


## OpenAPI

````yaml POST /api/call/start-calling
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/start-calling:
    post:
      tags:
        - Call Management
      summary: Start calling batch
      description: Push a prepared batch into the outbound dialer queue
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - batchId
                - userId
              properties:
                batchId:
                  type: string
                  example: 6806382f98da85ec32fac955
                userId:
                  type: string
                  example: 64e5f12345abcdef12345678
                callingNumbers:
                  type: array
                  items:
                    type: string
                  example:
                    - 67d52be3f91fe7017efdb6f1
                callData:
                  type: array
                  items:
                    type: object
                uuid:
                  type: string
                  example: some-unique-uuid
      responses:
        '200':
          description: Calling service started successfully
        '400':
          description: Missing required parameters
        '401':
          description: Unauthorized
        '404':
          description: Batch or user not found
        '500':
          description: Internal Server Error
      security:
        - bearerAuth: []
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.

````