Skip to main content

​
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.com/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.com/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.com/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.com/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.com/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.com/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.com/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.com/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