📞 Twilio Phone 📞

Make real phone calls from the command line using Twilio. Talk like a normal phone call - Twilio calls your phone first, then connects you to whoever you want to call.

Features

• Real two-way phone calls — talk and listen like a normal phone
• Live call status tracking — see ringing, connected, completed in real-time
• Privacy protection — your personal number is hidden from recipients
• Call recording — record calls and download recordings
• Make automated announcement calls (text-to-speech)
• Play audio files during calls
• View call history

How It Works

Unlike typical Twilio apps that just play messages, this lets you have real conversations just like a normal Phone:

1. You run: python cli.py call +1234567890
2. Twilio calls YOUR phone first
3. When you answer, it dials out to the destination
4. You're connected in a real two-way call!
5. Live status updates show you the call progress in real-time

Benefit: Privacy: The person you call sees your Twilio number, not your personal number.

Prerequisites

• Python 3.8+
• A Twilio account
• A Twilio phone number (purchased from Twilio)

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/TwilioPhone.git
   cd PyTwilioPhone

2. Create a virtual environment:

   python -m venv venv
   
   # Windows
   venv\Scripts\activate
   
   # macOS/Linux
   source venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Configure your credentials:

   Copy env_example.txt to .env and fill in your values:

   TWILIO_ACCOUNT_SID=your_account_sid_here
   TWILIO_AUTH_TOKEN=your_auth_token_here
   TWILIO_PHONE_NUMBER=+1234567890
   MY_PHONE_NUMBER=+1987654321
   

   • TWILIO_ACCOUNT_SID / TWILIO_AUTH_TOKEN = From Twilio Console
   • TWILIO_PHONE_NUMBER = Your Twilio number (purchased from Twilio)
   • MY_PHONE_NUMBER = YOUR personal phone number (where Twilio calls you)

Usage

Make a Real Phone Call

# Call someone - Twilio calls you first, then connects you
# Live status tracking is enabled by default
python cli.py call +1234567890

# Specify your phone number explicitly
python cli.py call +1234567890 -f +1987654321

# Record the conversation
python cli.py call +1234567890 --record

# Disable live status tracking
python cli.py call +1234567890 --no-watch

Example output:

📱 Calling you at: +1987654321
📞 Then connecting to: +1234567890

Answer your phone to connect the call...

✅ Call Initiated Successfully
╭─────────────┬────────────────────────────────────╮
│ Property    │ Value                              │
├─────────────┼────────────────────────────────────┤
│ Call SID    │ CA1234567890abcdef...              │
│ Status      │ queued                             │
│ Your Phone  │ +1987654321                        │
│ Destination │ +1234567890                        │
│ Twilio #    │ +1555123456                        │
╰─────────────┴────────────────────────────────────╯

📱 Answer your phone to connect!

📊 Live Call Status
Call SID: CA1234567890abcdef...

14:32:01  ⏳  QUEUED
14:32:02  📡  INITIATED
14:32:03  🔔  RINGING
14:32:08  🗣️  IN-PROGRESS
14:35:42  ✅  COMPLETED

📞 Call Duration: 214 seconds
✅ Call completed successfully!

Watch an Existing Call

# Monitor a call's status in real-time
python cli.py watch CA1234567890abcdef

# Custom poll interval (seconds)
python cli.py watch CA1234567890abcdef -i 2

Make an Automated Announcement Call

For one-way calls with text-to-speech messages:

python cli.py announce +1234567890 -m "Your package has arrived!"

python cli.py announce +1234567890 -m "Meeting reminder: 3pm today"

Play Audio During a Call

python cli.py play +1234567890 https://example.com/audio.mp3

# Loop the audio 3 times
python cli.py play +1234567890 https://example.com/audio.mp3 --loop 3

Call Recordings

When you use --record, recordings are stored in Twilio's cloud.

# List all recordings
python cli.py recordings

# List last 20 recordings
python cli.py recordings -n 20

# Download a recording (auto-authenticates with your .env credentials)
python cli.py recording RE1234567890abcdef

# Download with custom filename
python cli.py recording RE1234567890abcdef -o my_call.mp3

# Download as WAV
python cli.py recording RE1234567890abcdef -f wav

# Just show the URL (don't download)
python cli.py recording RE1234567890abcdef --url-only

Check Call Status

python cli.py status CA1234567890abcdef1234567890abcdef

View Call History

# Show last 10 calls
python cli.py history

# Show last 20 calls
python cli.py history -n 20

View Configuration

python cli.py config

Command Reference

Command	Description
call <number>	Make a real two-way phone call (with live tracking)
watch <call_sid>	Watch a call's status in real-time
announce <number>	Make an automated TTS announcement call
play <number> <url>	Make a call that plays an audio file
status <call_sid>	Check the status of a call
history	View recent call history
recordings	List call recordings
recording <sid>	Download a recording
config	Show current configuration

Call Status Icons

Icon	Status	Description
⏳	queued	Call is waiting to be made
📡	initiated	Twilio is starting the call
🔔	ringing	Phone is ringing
🗣️	in-progress	Call is active
✅	completed	Call ended normally
🚫	busy	Line was busy
❌	failed	Call could not be completed
📵	no-answer	No one answered
🚪	canceled	Call was canceled

Python API Usage

You can also use the module directly in your Python code:

from phone import TwilioPhone

# Initialize the client (loads config from .env)
phone = TwilioPhone()

# Make a real two-way call (recommended)
result = phone.make_bridge_call(
    to_number="+1234567890",      # Who you want to call
    your_number="+1987654321",    # Your phone (Twilio calls you first)
    record=True,                  # Optional: record the call
)

if result.success:
    print(f"Call initiated! Answer your phone!")
    print(f"Call SID: {result.call_sid}")
else:
    print(f"Call failed: {result.error_message}")

# Or make an automated announcement call
result = phone.make_call(
    to_number="+1234567890",
    message="Hello! This is an automated message."
)

# Check call status
status = phone.get_call_status(result.call_sid)
print(status)

# List recent calls
calls = phone.list_recent_calls(limit=5)
for call in calls:
    print(f"{call['to']} - {call['status']}")

# List recordings
recordings = phone.list_recordings(limit=10)
for rec in recordings:
    print(f"{rec['sid']} - {rec['duration']}s")

# Get recording download URL
url = phone.get_recording_url("RE1234...", format="mp3")

Voice Options (for announcements)

The default voice is Polly.Amy (British English). You can modify this in phone.py.

Available Polly voices include:

• Polly.Amy - British English (Female)
• Polly.Brian - British English (Male)
• Polly.Joanna - US English (Female)
• Polly.Matthew - US English (Male)
• Polly.Camila - Portuguese Brazilian (Female)
• And many more at Twilio Voices

Troubleshooting

"Missing required environment variables"

Make sure you've created a .env file with your Twilio credentials. Copy from env_example.txt.

"Invalid phone number"

Phone numbers must be in E.164 format (+1234567890). The app will try to normalize numbers automatically.

"Geographic permission not enabled"

You may need to enable geographic permissions for the destination country in your Twilio Console.

Call stuck on "queued"

Make sure your Twilio account has sufficient balance and the destination number is valid.

License

MIT License - feel free to use and modify as needed.