Skip to main content
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)
Response fields:
​
phone_number_id
string
The unique identifier for the imported phone number. Use this ID when assigning an agent or initiating batch calls.
​
phone_number
string
The E.164-formatted phone number (e.g., +15551234567).
​
label
string
The human-readable label you assigned when importing the number.
​
agent_id
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
​
label
string
required
A descriptive name for this number in your XUNA AI dashboard.
​
phone_number
string
required
The phone number in E.164 format (e.g., +15551234567).
​
twilio_account_sid
string
required
Your Twilio Account SID. Found in the Twilio Console.
​
twilio_auth_token
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)
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}
​
phone_number_id
string
required
The ID of the phone number to update.
​
agent_id
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.")
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.