Import and manage Twilio phone numbers for XUNA AI

To route phone calls to a voice agent, you first import a phone number from your Twilio account into XUNA AI. Once imported, you can assign any agent to that number — the agent answers every inbound call automatically.

XUNA AI does not provision phone numbers. You must own the number in Twilio before importing it here.

List phone numbers

Return all phone numbers imported into your XUNA AI account.

GET https://api.xuna.ai/v1/convai/phone-numbers

result = client.conversational_ai.phone_numbers.list()
for number in result:
    print(number.phone_number_id, number.phone_number, number.label)

const result = await client.conversationalAi.phoneNumbers.list();
for (const number of result) {
    console.log(number.phoneNumberId, number.phoneNumber, number.label);
}

curl https://api.xuna.ai/v1/convai/phone-numbers \
  -H "x-api-key: YOUR_API_KEY"

Response fields:

string

The unique identifier for the imported phone number. Use this ID when assigning an agent or initiating batch calls.

string

The E.164-formatted phone number (e.g., +15551234567).

string

The human-readable label you assigned when importing the number.

string

The ID of the agent currently assigned to this number, if any.

Import a phone number

Connect a Twilio phone number to your XUNA AI account by providing your Twilio credentials. XUNA AI configures the number’s webhook automatically.

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

string

required

A descriptive name for this number in your XUNA AI dashboard.

string

required

The phone number in E.164 format (e.g., +15551234567).

string

required

Your Twilio Account SID. Found in the Twilio Console.

string

required

Your Twilio Auth Token. Found in the Twilio Console.

phone_number = client.conversational_ai.phone_numbers.create(
    label="Customer Support Line",
    phone_number="+15551234567",
    twilio_account_sid="ACxxxxxxxxxx",
    twilio_auth_token="your_auth_token",
)
print("Phone number ID:", phone_number.phone_number_id)

const phoneNumber = await client.conversationalAi.phoneNumbers.create({
    label: "Customer Support Line",
    phoneNumber: "+15551234567",
    twilioAccountSid: "ACxxxxxxxxxx",
    twilioAuthToken: "your_auth_token",
});
console.log("Phone number ID:", phoneNumber.phoneNumberId);

curl -X POST https://api.xuna.ai/v1/convai/phone-numbers \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Customer Support Line",
    "phone_number": "+15551234567",
    "twilio_account_sid": "ACxxxxxxxxxx",
    "twilio_auth_token": "your_auth_token"
  }'

Your Twilio Auth Token is sensitive. Store it securely and never log it. XUNA AI stores it encrypted to configure your Twilio webhook.

Assign an agent to a phone number

Update an imported phone number to route inbound calls to a specific agent.

PATCH https://api.xuna.ai/v1/convai/phone-numbers/{phone_number_id}

string

required

The ID of the phone number to update.

string

required

The ID of the agent that should handle inbound calls on this number.

client.conversational_ai.phone_numbers.update(
    phone_number_id="pn_xxxxxxxx",
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
)
print("Agent assigned.")

await client.conversationalAi.phoneNumbers.update(
    "pn_xxxxxxxx",
    {
        agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
    }
);
console.log("Agent assigned.");

curl -X PATCH https://api.xuna.ai/v1/convai/phone-numbers/pn_xxxxxxxx \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6"}'

You can reassign a phone number to a different agent at any time. The change takes effect immediately for new calls.

Once assigned, every inbound call to that number starts a conversation with the specified agent. To launch outbound calls, see Batch calls.

Overview

Agents

Telephony

Import and manage Twilio phone numbers for XUNA AI

List phone numbers

Import a phone number

Assign an agent to a phone number

​List phone numbers

​Import a phone number

​Assign an agent to a phone number

List phone numbers

Import a phone number

Assign an agent to a phone number