Twilio Phone Numbers: Provisioning, Configuration, and Management

import os
from twilio.rest import Client

client = Client(
    os.environ["TWILIO_ACCOUNT_SID"],
    os.environ["TWILIO_AUTH_TOKEN"]
)

# Search local numbers
def search_numbers(country="US", area_code=None, limit=5):
    params = {"country": country, "limit": limit}
    if area_code:
        params["area_code"] = area_code
    available = client.available_phone_numbers(country).local.list(**params)
    print(f"Found {len(available)} numbers:")
    for num in available:
        print(f"  {num.phone_number} ({num.locality}, {num.region})")
    return available

numbers = search_numbers("US", area_code=415)
# Expected output:
# Found 3 numbers:
#   +14155551234 (San Francisco, CA)
#   +14155555678 (San Francisco, CA)
#   +14155559012 (San Francisco, CA)

# Purchase a number
def purchase_number(phone_number, friendly_name=None):
    params = {
        "phone_number": phone_number,
        "sms_url": "https://example.com/sms",
        "voice_url": "https://example.com/voice"
    }
    if friendly_name:
        params["friendly_name"] = friendly_name
    purchased = client.incoming_phone_numbers.create(**params)
    print(f"Purchased: {purchased.phone_number}")
    print(f"SID: {purchased.sid}")
    print(f"SMS URL: {purchased.sms_url}")
    print(f"Monthly cost: ${purchased.bundle_sid or 'Standard'}")
    return purchased

# number = purchase_number("+14155551234", "DodaTech Support US")
# Expected output:
# Purchased: +14155551234
# SID: PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# SMS URL: https://example.com/sms
# Monthly cost: Standard

# Update number capabilities after purchase
def configure_number(number_sid, sms_url, voice_url, friendly_name=None):
    params = {
        "sms_url": sms_url,
        "sms_method": "POST",
        "voice_url": voice_url,
        "voice_method": "POST"
    }
    if friendly_name:
        params["friendly_name"] = friendly_name
    updated = client.incoming_phone_numbers(number_sid).update(**params)
    print(f"Updated: {updated.phone_number}")
    print(f"  SMS: {updated.sms_url}")
    print(f"  Voice: {updated.voice_url}")
    return updated

# configure_number("PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
#                  "https://example.com/sms",
#                  "https://example.com/voice",
#                  "DodaTech Support Hotline")
# Expected output:
# Updated: +14155551234
#   SMS: https://example.com/sms
#   Voice: https://example.com/voice

# List all owned numbers
def list_owned_numbers():
    numbers = client.incoming_phone_numbers.list()
    print(f"Total numbers: {len(numbers)}")
    for num in numbers:
        print(f"  {num.phone_number} | {num.friendly_name}")
        print(f"    SMS: {num.sms_url or 'Not configured'}")
        print(f"    Voice: {num.voice_url or 'Not configured'}")
        print()

# list_owned_numbers()

def release_number(number_sid):
    """Release a phone number (stops billing)."""
    deleted = client.incoming_phone_numbers(number_sid).delete()
    if deleted:
        print(f"Released number SID: {number_sid}")
        print("Monthly billing stopped.")
    else:
        print("Failed to release number.")
    return deleted

# release_number("PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
# Expected output:
# Released number SID: PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Monthly billing stopped.

# Find numbers not used in 30+ days
def find_unused_numbers(days_unused=30):
    from datetime import datetime, timedelta
    cutoff = datetime.utcnow() - timedelta(days=days_unused)
    numbers = client.incoming_phone_numbers.list()
    unused = []
    for num in numbers:
        # Check if number was ever used
        calls = client.calls.list(to=num.phone_number, limit=1)
        messages = client.messages.list(to=num.phone_number, limit=1)
        if not calls and not messages:
            unused.append(num)
            print(f"Unused: {num.phone_number}")
    return unused

# Port an existing number from another carrier
def initiate_port(phone_number, carrier_info):
    """
    carrier_info = {
        "carrier_name": "Verizon Wireless",
        "account_number": "VZW123456",
        "account_pin": "1234",
        "billing_telephone": "+14155551234",
        "address": {
            "street": "123 Main St",
            "city": "San Francisco",
            "state": "CA",
            "postal_code": "94105"
        }
    }
    """
    porting = client.porting.ports.create(
        phone_number=phone_number,
        **carrier_info
    )
    print(f"Port request: {porting.sid}")
    print(f"Status: {porting.status}")
    print("Porting takes 5-10 business days.")
    return porting

# Expected output:
# Port request: POxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Status: pending
# Porting takes 5-10 business days.