> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magpipe.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Phone Numbers
> Provision, manage, and configure phone numbers for your AI agents
## Overview
Phone numbers are the gateway for your AI agents to communicate with the world. Magpipe supports provisioning new numbers, bringing your own carrier via SIP trunks, and managing multiple numbers across your organization.
## Number Types
### Local Numbers
* Area code specific to a region
* Lower per-minute costs
* Familiar to local callers
* Available in US and Canada
### Toll-Free Numbers
* 800, 888, 877, 866, 855, 844 prefixes
* Free for callers to dial
* Professional appearance
* Higher per-minute costs
## Provisioning Numbers
### Search for Numbers
1. Go to **Phone** → **Add Number** (or navigate to `/select-number`)
2. Default results load automatically (US numbers)
3. Search by area code, state/province, or city
4. Browse up to 3 pages of results (25 per page)
5. Select a number and click **Next** to provision
#### Search Options
* **Area Code**: Search by 3-digit area code (e.g., 604, 415, 212)
* **State / Province**: Type a full name (e.g., "California", "British Columbia") or 2-letter code (CA, BC) — autocomplete suggests matches as you type. Supports all 50 US states and Canadian provinces.
* **City**: Type a city name with autocomplete (40+ major US and Canadian cities)
* **Local / Toll Free**: Toggle between local and toll-free number types
### Provision a Number
1. Select a number from search results
2. Click **Next** to provision
3. Number is purchased, registered with the SIP trunk for voice routing, and saved to your account in seconds
4. Numbers are **unassigned by default** — assign to an agent from the Phone page or Agent Deploy tab
### Number Capabilities
Each number has specific capabilities:
| Capability | Description |
| ---------- | --------------------------------- |
| **Voice** | Make and receive phone calls |
| **SMS** | Send and receive text messages |
| **MMS** | Send and receive picture messages |
Most US/Canada numbers support all three capabilities. Some toll-free numbers may have limited MMS support.
## Number Management
### Assigning Agents
Each phone number has three independent agent slots:
| Slot | Description |
| ------------ | ---------------------------------------------------------------------------------------------- |
| **Inbound** | Agent that answers incoming calls |
| **Outbound** | Agent used when placing outbound calls from this number (defaults to inbound agent if not set) |
| **SMS** | Agent that responds to inbound SMS/text messages (defaults to inbound agent if not set) |
This lets you use specialized agents for each channel — for example, a friendly receptionist for inbound calls, a direct sales agent for outbound calls, and a concise text-reply agent for SMS, all on the same number.
#### From Agent Detail → Deploy
1. Open an agent and go to the **Deploy** tab
2. Click **Assign Number** to assign available numbers
3. The agent type determines which slot it fills (voice → inbound; outbound voice → outbound; text → SMS)
#### From Phone → Number Management
1. Go to **Phone** or **Manage Numbers**
2. Each number shows its Inbound / Outbound / SMS agent assignments with "In:" / "Out:" / "Text:" badges
3. Click the number to open the assignment modal with three separate dropdowns
If a number has no outbound agent assigned, outbound calls use the inbound agent's configuration. If no SMS agent is assigned, inbound SMS falls back to the inbound agent. Existing setups continue working without changes.
### Friendly Names
Give numbers meaningful names:
* "Main Office"
* "Sales Line"
* "Support Hotline"
* "After Hours"
### Active/Inactive Status
Temporarily disable a number without releasing it:
* **Active**: Calls and SMS are handled
* **Inactive**: Calls go to busy signal, SMS rejected
### Deleting Numbers
Every number has a delete button (trash icon). Clicking it shows a confirmation modal that tells you:
* Which agent will lose the number (if assigned)
* That the action cannot be undone
On delete:
1. The number is reassigned to the system agent (so any remaining calls get the unassigned response)
2. Removed from the LiveKit SIP trunk
3. Released from the carrier
Deleting a number is permanent. The number returns to the public pool and you may not be able to get it back. Numbers purchased within the last 30 days cannot be released from the carrier immediately — they are marked for future cleanup.
## External SIP Trunks
Bring your own carrier for more control and potentially lower costs.
### What is a SIP Trunk?
A SIP trunk connects your existing phone carrier to Magpipe, allowing:
* Use your existing phone numbers
* Keep your current carrier rates
* Maintain existing phone infrastructure
* Route calls through Magpipe AI
### Supported Carriers
Any SIP-compatible carrier works, including:
* Twilio
* Bandwidth
* Telnyx
* Vonage
* Plivo
* Your own PBX
### Configuration
#### Inbound Trunk (Receiving Calls)
Configure your carrier to send calls to Magpipe:
**IP-Based Authentication:**
1. Whitelist Magpipe's IP addresses in your carrier
2. Point your carrier's SIP destination to Magpipe
3. Add your phone numbers in Magpipe
**Registration-Based Authentication:**
1. Get SIP credentials from your carrier
2. Enter in Magpipe: username, password, domain
3. Magpipe registers with your carrier
#### Outbound Trunk (Making Calls)
Configure Magpipe to send calls through your carrier:
1. Enter your carrier's SIP URI
2. Add authentication credentials
3. Specify which numbers use this trunk
### Adding External Numbers
1. Go to **Phone** → **External Numbers**
2. Click **Add Number**
3. Enter the phone number in E.164 format
4. Select or create a SIP trunk configuration
5. Assign to an agent
## Call Routing
### Inbound Call Flow
```
Caller dials your number
↓
Magpipe receives call
↓
Check if number has assigned agent
↓
[Yes] → Agent answers call
[No] → Play "number not in service" or route to default agent
↓
AI handles conversation
↓
Call ends or transfers
```
### Transfer Destinations
Configure where calls transfer:
1. Go to **Agent** → **Settings**
2. Set **Transfer Number**
3. Optionally set **Transfer Passcode**
When callers request transfer:
* Agent says "I'll transfer you now"
* Call connects to transfer number
* If passcode set, transferred party enters it
### After-Hours Handling
When calls arrive outside business hours:
1. **Voicemail**: Play message, record voicemail
2. **Forward**: Route to after-hours number
3. **AI Response**: Agent answers with limited scope
4. **Closed Message**: Play recording and hang up
Configure in **Agent** → **Schedule**.
## Call Features
### Call Recording
All calls recorded by default:
* Secure cloud storage
* Available in inbox
* Downloadable via dashboard or API
* Configurable retention period
To disable recording:
1. Go to **Settings** → **Preferences**
2. Toggle off **Record Calls**
### Caller ID
Outbound calls show your Magpipe number:
* Number must be verified
* Consistent caller ID for callbacks
* Multiple numbers = choose which to show
### Call Transcription
Every call is transcribed:
* Real-time during call
* Full transcript after call ends
* Speaker identification (agent vs caller)
* Timestamps for each segment
### Call Analytics
Track metrics per number:
* Total calls (inbound/outbound)
* Average duration
* Sentiment distribution
* Busiest times
* Transfer rate
## Best Practices
### Number Selection
1. **Local presence**: Use area codes matching your customers
2. **Vanity numbers**: Easy-to-remember patterns for marketing
3. **Multiple numbers**: Different numbers for different purposes
### Capacity Planning
* Each number handles unlimited concurrent calls
* No per-number concurrency limits
* Plan for peak call volumes
### Number Portability
Currently, number porting (bringing existing numbers) is handled via:
1. External SIP trunk setup
2. Forward existing number to Magpipe number
Direct number porting coming soon.
Find available numbers programmatically
Provision numbers via API