> ## 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.

# Import and manage Twilio phone numbers for XUNA AI

> Import Twilio phone numbers into XUNA AI, list your imported numbers, and assign a voice agent to handle inbound calls on any number.

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.

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

## List phone numbers

Return all phone numbers imported into your XUNA AI account.

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

<CodeGroup>
  ```python Python theme={null}
  result = client.conversational_ai.phone_numbers.list()
  for number in result:
      print(number.phone_number_id, number.phone_number, number.label)
  ```

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

  ```bash cURL theme={null}
  curl https://api.xuna.ai/v1/convai/phone-numbers \
    -H "x-api-key: YOUR_API_KEY"
  ```
</CodeGroup>

**Response fields:**

<ResponseField name="phone_number_id" type="string">
  The unique identifier for the imported phone number. Use this ID when assigning an agent or initiating batch calls.
</ResponseField>

<ResponseField name="phone_number" type="string">
  The E.164-formatted phone number (e.g., `+15551234567`).
</ResponseField>

<ResponseField name="label" type="string">
  The human-readable label you assigned when importing the number.
</ResponseField>

<ResponseField name="agent_id" type="string">
  The ID of the agent currently assigned to this number, if any.
</ResponseField>

***

## 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
```

<ParamField body="label" type="string" required>
  A descriptive name for this number in your XUNA AI dashboard.
</ParamField>

<ParamField body="phone_number" type="string" required>
  The phone number in E.164 format (e.g., `+15551234567`).
</ParamField>

<ParamField body="twilio_account_sid" type="string" required>
  Your Twilio Account SID. Found in the [Twilio Console](https://console.twilio.com).
</ParamField>

<ParamField body="twilio_auth_token" type="string" required>
  Your Twilio Auth Token. Found in the [Twilio Console](https://console.twilio.com).
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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);
  ```

  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

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

***

## 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}
```

<ParamField path="phone_number_id" type="string" required>
  The ID of the phone number to update.
</ParamField>

<ParamField body="agent_id" type="string" required>
  The ID of the agent that should handle inbound calls on this number.
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  client.conversational_ai.phone_numbers.update(
      phone_number_id="pn_xxxxxxxx",
      agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
  )
  print("Agent assigned.")
  ```

  ```typescript TypeScript theme={null}
  await client.conversationalAi.phoneNumbers.update(
      "pn_xxxxxxxx",
      {
          agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
      }
  );
  console.log("Agent assigned.");
  ```

  ```bash cURL theme={null}
  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"}'
  ```
</CodeGroup>

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

Once assigned, every inbound call to that number starts a conversation with the specified agent. To launch outbound calls, see [Batch calls](/api-reference/telephony/batch-calls).