Phone Numbers

Loquent manages phone numbers in its own phone_number table. Numbers can be bought directly through Loquent or imported from your existing Twilio account.

Buying a New Number

Buying a number through Loquent purchases it in your Twilio account and registers it in Loquent in one step.

Search for available numbers

POST /api/twilio/search-available-numbers
Input: area_code (3-digit string)

Queries Twilio for available local US numbers in that area code:

GET /Accounts/{sid}/AvailablePhoneNumbers/US/Local.json?AreaCode={code}

Returns numbers with their capabilities (voice, SMS). Read-only — no changes to your Twilio account.

Purchase a number

POST /api/twilio/buy-phone-number
Input: phone_number (E.164 format, e.g. +15551234567)

Flow:

1. Validates E.164 format
2. POSTs to Twilio to purchase the number:

   POST /Accounts/{sid}/IncomingPhoneNumbers.json
   Body: PhoneNumber=+15551234567

3. Saves to phone_number table with the Twilio SID (PN...)
4. Auto-assigns default analyzers to the number
5. Automatically sets the voice URL on the number (see Voice URL Setup)

Note

Buying a number immediately configures it for inbound calls in Loquent. The voice URL is set as part of the purchase flow — you don’t need a separate configuration step.

Importing Existing Numbers

If you already have phone numbers in your Twilio account, import them into Loquent without repurchasing.

How to import

1. Go to Settings → Telephony (or the Twilio section)
2. Click Fetch Numbers — Loquent lists numbers in your Twilio account not yet in Loquent
3. Select the numbers to import
4. Click Import Selected (N)

The result shows how many were imported and how many already existed.

What import does and doesn’t do

Import is read-only on Twilio. It only creates phone_number records in Loquent’s database — it does not purchase anything, modify any number configuration, or change the voice URL.

Imported numbers won’t receive calls in Loquent until you configure the voice URL. See Voice URL Setup for how to do this.

API endpoints

Method	Path	Description
POST	/api/twilio/get-unsynced-numbers	Lists Twilio numbers not yet in Loquent
POST	/api/twilio/sync-numbers	Imports selected numbers into Loquent

Phone Number Data Model

CREATE TABLE phone_number (
    id               UUID PRIMARY KEY,
    organization_id  UUID NOT NULL REFERENCES organization(id),
    number           TEXT NOT NULL,            -- E.164: +15551234567
    twilio_sid       TEXT NOT NULL,            -- Twilio IncomingPhoneNumber SID: PNxxx
    friendly_name    TEXT,                     -- Optional human label
    agent_id         UUID,                     -- AI agent assigned to handle calls
    previous_voice_url TEXT                    -- Saved before Loquent sets its Voice URL
);

The twilio_sid (e.g. PN...) is used for all future Twilio configuration updates on that number, including setting the voice URL.

Listing Phone Numbers

GET /api/phones

Returns all phone numbers for the organization with: id, number, friendly_name, agent_id.

Permission required: Phone:Collection:List

API Reference

Method	Path	Description
POST	/api/twilio/search-available-numbers	Search available numbers by area code
POST	/api/twilio/buy-phone-number	Purchase + register a number
POST	/api/twilio/get-unsynced-numbers	List importable Twilio numbers
POST	/api/twilio/sync-numbers	Import selected numbers
GET	/api/phones	List all registered phone numbers

Module Structure

src/mods/twilio/
├── api/
│   ├── buy_phone_number_api.rs
│   ├── search_available_numbers_api.rs
│   └── sync_twilio_numbers_api.rs
└── utils/
    ├── buy_twilio_phone_number_util.rs
    └── set_twilio_phone_number_twiml_util.rs   # Called automatically on buy

src/mods/phone/
└── api/
    └── get_phones_api.rs

src/mods/settings/components/
└── import_phone_numbers_section_component.rs