Phone Integration Setup

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:

cURL

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:

cURL

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:

cURL

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:

{
  "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:

cURL

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:

{
  "routing_config": {
    "default_agent": "agent_123",
    "fallback_behavior": "voicemail",
    "max_queue_time": 300,
    "queue_music": "default"
  }
}

Advanced Routing Rules

Configure complex routing logic:

{
  "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:

cURL

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:

{
  "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:

cURL

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:

cURL

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:

cURL

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"
  }'

Authentication

Voice Agents

Knowledge Base

Phone Integration

Prerequisites

Phone Number Management

Import Phone Numbers

List Available Numbers

Assign Agent to Phone Number

SIP Trunk Integration

Configure SIP Settings

Authentication Setup

Call Routing Configuration

Basic Routing

Advanced Routing Rules

Webhook Configuration

Call Event Webhooks

Webhook Payload Example

Testing and Validation

Test Call Setup

Integration Health Check

Troubleshooting

Common Issues

SIP Registration Failures

Call Routing Problems

Audio Quality Issues

Diagnostic Tools

Security Considerations

Network Security

Access Control

Next Steps

​Prerequisites

​Phone Number Management

​Import Phone Numbers

​List Available Numbers

​Assign Agent to Phone Number

​SIP Trunk Integration

​Configure SIP Settings

​Authentication Setup

​Call Routing Configuration

​Basic Routing

​Advanced Routing Rules

​Webhook Configuration

​Call Event Webhooks

​Webhook Payload Example

​Testing and Validation

​Test Call Setup

​Integration Health Check

​Troubleshooting

​Common Issues

​SIP Registration Failures

​Call Routing Problems

​Audio Quality Issues

​Diagnostic Tools

​Security Considerations

​Network Security

​Access Control

​Next Steps

Prerequisites

Phone Number Management

Import Phone Numbers

List Available Numbers

Assign Agent to Phone Number

SIP Trunk Integration

Configure SIP Settings

Authentication Setup

Call Routing Configuration

Basic Routing

Advanced Routing Rules

Webhook Configuration

Call Event Webhooks

Webhook Payload Example

Testing and Validation

Test Call Setup

Integration Health Check

Troubleshooting

Common Issues

SIP Registration Failures

Call Routing Problems

Audio Quality Issues

Diagnostic Tools

Security Considerations

Network Security

Access Control

Next Steps