Skip to main content
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

​
agent_id
string
required
The ID of the agent that will conduct each call in the batch.
​
from_phone_number_id
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.
​
calls
object[]
required
An array of call targets. Each entry specifies the destination number and any per-call overrides.

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

​
Response

{
  "batch_id": "batch_xxxxxxxx",
  "calls_initiated": 2
}
​
batch_id
string
required
A unique identifier for the batch. Use this to track the batch in your logs or dashboard.
​
calls_initiated
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.