> ## Documentation Index
> Fetch the complete documentation index at: https://docs.threetone.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone Integration Setup

> Set up phone integration to connect voice agents with telephony systems

## Prerequisites

* ThreeTone API key with phone integration permissions
* Phone number or SIP trunk access
* Webhook endpoint for call notifications (optional)

## Phone Number Management

### Import Phone Numbers

Add phone numbers to your ThreeTone account:

```bash cURL theme={null}
curl --request POST \
  --url https://api.threetone.in/v1/voiceai/phone-numbers \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "phone_number": "+1234567890",
    "country_code": "US",
    "provider": "twilio",
    "provider_config": {
      "account_sid": "your_twilio_sid",
      "auth_token": "your_twilio_token"
    }
  }'
```

### List Available Numbers

Retrieve all phone numbers in your account:

```bash cURL theme={null}
curl --request GET \
  --url https://api.threetone.in/v1/voiceai/phone-numbers \
  --header 'x-api-key: YOUR_API_KEY'
```

### Assign Agent to Phone Number

Connect a voice agent to a specific phone number:

```bash cURL theme={null}
curl --request PUT \
  --url https://api.threetone.in/v1/voiceai/phone-numbers/{phone_number_id} \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "agent_id": "agent_123",
    "call_routing": {
      "mode": "direct",
      "business_hours": {
        "enabled": true,
        "timezone": "America/New_York",
        "schedule": {
          "monday": {"start": "09:00", "end": "17:00"},
          "tuesday": {"start": "09:00", "end": "17:00"},
          "wednesday": {"start": "09:00", "end": "17:00"},
          "thursday": {"start": "09:00", "end": "17:00"},
          "friday": {"start": "09:00", "end": "17:00"}
        }
      }
    }
  }'
```

## SIP Trunk Integration

### Configure SIP Settings

Set up SIP trunk for enterprise integration:

```json theme={null}
{
  "sip_config": {
    "sip_domain": "sip.your-provider.com",
    "username": "your_sip_username",
    "password": "your_sip_password",
    "proxy": "proxy.your-provider.com",
    "port": 5060,
    "transport": "UDP",
    "codec_preferences": ["G.711", "G.722", "G.729"]
  }
}
```

### Authentication Setup

Configure SIP authentication:

```bash cURL theme={null}
curl --request POST \
  --url https://api.threetone.in/v1/voiceai/sip-trunks \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Main SIP Trunk",
    "sip_domain": "sip.example.com",
    "auth_username": "threetone_user",
    "auth_password": "secure_password",
    "registration_required": true
  }'
```

## Call Routing Configuration

### Basic Routing

Set up simple call routing:

```json theme={null}
{
  "routing_config": {
    "default_agent": "agent_123",
    "fallback_behavior": "voicemail",
    "max_queue_time": 300,
    "queue_music": "default"
  }
}
```

### Advanced Routing Rules

Configure complex routing logic:

```json theme={null}
{
  "routing_rules": [
    {
      "condition": "caller_id_matches",
      "pattern": "+1800*",
      "action": "route_to_agent",
      "agent_id": "vip_agent_456"
    },
    {
      "condition": "time_of_day",
      "start_time": "18:00",
      "end_time": "09:00",
      "action": "route_to_agent",
      "agent_id": "after_hours_agent_789"
    },
    {
      "condition": "queue_length",
      "threshold": 5,
      "action": "overflow_to_voicemail"
    }
  ]
}
```

## Webhook Configuration

### Call Event Webhooks

Receive real-time call notifications:

```bash cURL theme={null}
curl --request POST \
  --url https://api.threetone.in/v1/voiceai/webhooks \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://your-api.com/webhooks/call-events",
    "events": [
      "call_started",
      "call_ended",
      "call_transferred",
      "agent_unavailable"
    ],
    "secret": "your_webhook_secret"
  }'
```

### Webhook Payload Example

Typical webhook payload structure:

```json theme={null}
{
  "event": "call_started",
  "timestamp": "2024-01-15T10:30:00Z",
  "call_id": "call_abc123",
  "phone_number": "+1234567890",
  "caller_id": "+1987654321",
  "agent_id": "agent_123",
  "metadata": {
    "call_direction": "inbound",
    "call_source": "phone_system"
  }
}
```

## Testing and Validation

### Test Call Setup

Verify your phone integration:

```bash cURL theme={null}
curl --request POST \
  --url https://api.threetone.in/v1/voiceai/test-call \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "phone_number": "+1234567890",
    "test_type": "inbound_routing",
    "duration_seconds": 30
  }'
```

### Integration Health Check

Monitor integration status:

```bash cURL theme={null}
curl --request GET \
  --url https://api.threetone.in/v1/voiceai/phone-integration/health \
  --header 'x-api-key: YOUR_API_KEY'
```

## Troubleshooting

### Common Issues

#### SIP Registration Failures

* Verify SIP credentials and domain settings
* Check firewall and NAT configuration
* Ensure proper codec support

#### Call Routing Problems

* Validate agent availability and status
* Check routing rule configuration
* Verify phone number assignments

#### Audio Quality Issues

* Review codec preferences and bandwidth
* Check network latency and jitter
* Validate audio device configuration

### Diagnostic Tools

Use built-in diagnostic capabilities:

```bash cURL theme={null}
curl --request POST \
  --url https://api.threetone.in/v1/voiceai/diagnostics/network-test \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{
    "target_endpoint": "sip.your-provider.com",
    "test_type": "connectivity"
  }'
```

## Security Considerations

### Network Security

* Use encrypted SIP (SIPS) when possible
* Implement proper firewall rules
* Regular security audits and updates

### Access Control

* Restrict API access to authorized systems
* Use strong authentication credentials
* Monitor and log all phone system access

## Next Steps

* [Call Handling](/guides/phone-integration/call-handling)
* [Webhooks Configuration](/guides/phone-integration/webhooks)
* [Advanced Configuration](/guides/voice-agents/advanced-configuration)