Launch outbound batch calls with XUNA AI agents

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

string

required

The ID of the agent that will conduct each call in the batch.

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.

object[]

required

An array of call targets. Each entry specifies the destination number and any per-call overrides.

Show calls item properties

string

required

The E.164-formatted number to dial (e.g., +15559876543).

object

Optional overrides applied to this call only. Any field in conversation_config can be overridden here.

Show conversation_config_override properties

object

Agent-level overrides for this call.

Show agent properties

string

The opening line the agent speaks on this specific call. Use this to personalise the greeting with the recipient’s name or context.

Example request

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)

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);

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."
          }
        }
      }
    ]
  }'

Response

{
  "batch_id": "batch_xxxxxxxx",
  "calls_initiated": 2
}

string

required

A unique identifier for the batch. Use this to track the batch in your logs or dashboard.

number

required

The number of calls successfully queued in this batch.

Notes

Each call in the batch generates a separate conversation record. Retrieve individual conversation transcripts and outcomes using the conversations endpoint.

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.

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.

Overview

Agents

Telephony

Launch outbound batch calls with XUNA AI agents

Endpoint

Request parameters

Example request

Response

Notes

​Endpoint

​Request parameters

​Example request

​Response

​Notes

Endpoint

Request parameters

Example request

Response

Notes