> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xuna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Launch outbound batch calls with XUNA AI agents

> Use POST /v1/convai/phone-numbers/batch-calls to dial multiple numbers at once, with per-call message overrides and a shared agent and caller ID.

Batch calling lets your agent dial a list of phone numbers in a single API request. Each call in the batch uses the same agent and caller phone number, but you can override the agent's first message or any other conversation config on a per-call basis — making it straightforward to personalise outbound campaigns at scale.

## Endpoint

```
POST https://api.xuna.ai/v1/convai/phone-numbers/batch-calls
```

## Request parameters

<ParamField body="agent_id" type="string" required>
  The ID of the agent that will conduct each call in the batch.
</ParamField>

<ParamField body="from_phone_number_id" type="string" required>
  The ID of the imported phone number to use as the caller ID. The number must already be imported into your account — see [Phone numbers](/api-reference/telephony/phone-numbers).
</ParamField>

<ParamField body="calls" type="object[]" required>
  An array of call targets. Each entry specifies the destination number and any per-call overrides.

  <Expandable title="calls item properties">
    <ParamField body="calls[].to_phone_number" type="string" required>
      The E.164-formatted number to dial (e.g., `+15559876543`).
    </ParamField>

    <ParamField body="calls[].conversation_config_override" type="object">
      Optional overrides applied to this call only. Any field in `conversation_config` can be overridden here.

      <Expandable title="conversation_config_override properties">
        <ParamField body="calls[].conversation_config_override.agent" type="object">
          Agent-level overrides for this call.

          <Expandable title="agent properties">
            <ParamField body="calls[].conversation_config_override.agent.first_message" type="string">
              The opening line the agent speaks on this specific call. Use this to personalise the greeting with the recipient's name or context.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Example request

<CodeGroup>
  ```python Python theme={null}
  from xuna_ai.client import XunaAI

  client = XunaAI(api_key="YOUR_API_KEY")

  response = client.conversational_ai.phone_numbers.batch_calls(
      agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
      from_phone_number_id="pn_xxxxxxxx",
      calls=[
          {
              "to_phone_number": "+15559876543",
              "conversation_config_override": {
                  "agent": {
                      "first_message": "Hi, this is a follow-up call for John.",
                  }
              },
          },
          {
              "to_phone_number": "+15557654321",
              "conversation_config_override": {
                  "agent": {
                      "first_message": "Hi, this is a follow-up call for Maria.",
                  }
              },
          },
      ],
  )

  print("Batch ID:", response.batch_id)
  print("Calls initiated:", response.calls_initiated)
  ```

  ```typescript TypeScript theme={null}
  import { XunaAIClient } from "@xuna-ai/xuna-ai-js";

  const client = new XunaAIClient({ apiKey: "YOUR_API_KEY" });

  const response = await client.conversationalAi.phoneNumbers.batchCalls({
      agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
      fromPhoneNumberId: "pn_xxxxxxxx",
      calls: [
          {
              toPhoneNumber: "+15559876543",
              conversationConfigOverride: {
                  agent: {
                      firstMessage: "Hi, this is a follow-up call for John.",
                  },
              },
          },
          {
              toPhoneNumber: "+15557654321",
              conversationConfigOverride: {
                  agent: {
                      firstMessage: "Hi, this is a follow-up call for Maria.",
                  },
              },
          },
      ],
  });

  console.log("Batch ID:", response.batchId);
  console.log("Calls initiated:", response.callsInitiated);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.xuna.ai/v1/convai/phone-numbers/batch-calls \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6",
      "from_phone_number_id": "pn_xxxxxxxx",
      "calls": [
        {
          "to_phone_number": "+15559876543",
          "conversation_config_override": {
            "agent": {
              "first_message": "Hi, this is a follow-up call for John."
            }
          }
        },
        {
          "to_phone_number": "+15557654321",
          "conversation_config_override": {
            "agent": {
              "first_message": "Hi, this is a follow-up call for Maria."
            }
          }
        }
      ]
    }'
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "batch_id": "batch_xxxxxxxx",
  "calls_initiated": 2
}
```

<ResponseField name="batch_id" type="string" required>
  A unique identifier for the batch. Use this to track the batch in your logs or dashboard.
</ResponseField>

<ResponseField name="calls_initiated" type="number" required>
  The number of calls successfully queued in this batch.
</ResponseField>

## Notes

<Note>
  Each call in the batch generates a separate conversation record. Retrieve individual conversation transcripts and outcomes using the [conversations endpoint](/api-reference/agents/conversations).
</Note>

<Warning>
  Make sure the `from_phone_number_id` number is imported and verified in your account before initiating a batch. Calls will fail if the number is not available. See [Phone numbers](/api-reference/telephony/phone-numbers).
</Warning>

<Tip>
  Use `conversation_config_override` to inject the recipient's name, account number, or any other personalisation into the first message. This is fetched at call time — you do not need to create a separate agent per recipient.
</Tip>