Autodialer is a powerful Ruby on Rails application that revolutionizes outbound calling by combining:

• 🤖 AI-Powered Commands - Natural language processing with Google Gemini
• 📞 Twilio Integration - Reliable voice call delivery
• ⚡ Background Processing - Async job handling with Sidekiq
• 📊 Real-Time Tracking - Live call status monitoring
• 🎯 Smart Scripting - AI-generated call scripts

⚠️ Important: This application is designed for testing with verified numbers only. Always obtain proper consent before calling real people.

• Multiple Input Methods: Paste numbers directly or upload .txt/.csv files
• Smart Validation: Automatic format checking and duplicate removal
• Batch Processing: Queue up to 100 numbers at once
• International Support: Handles country codes and various formats

Natural language interface powered by Google Gemini:

✅ "Call +1 800 555 0100"
✅ "Dial the last number"
✅ "Call the third number from history"
✅ "Dial the last 5 numbers"
✅ "Call the previous number again"

Smart Features:

• Intent recognition and phone number extraction
• Historical reference tracking (last, previous, nth number)
• Context-aware script generation
• Fallback to direct number parsing

• Automated Calling: Programmable voice calls via Twilio API
• Status Tracking: Real-time updates (queued, ringing, completed, failed)
• Custom Scripts: AI-generated or default voice messages
• Multiple Voices: Support for various Polly voices
• Webhook Processing: Async status callbacks

• Call Timeline: Chronological view of all attempts
• Status Details: Duration, timestamps, and outcomes
• Success Metrics: Track completion rates
• Filterable Records: Search by status, number, or date

• Sidekiq Workers: Async call processing
• Redis Integration: Job queue management
• Auto-retry Logic: Configurable retry attempts
• Development Mode: Inline processing for easy testing

• Live Updates: Automatic status polling every 2 seconds
• Visual Feedback: Color-coded status badges
• Progress Tracking: Per-number call status
• Non-blocking: Continue browsing while calls process

• Ruby: 3.4.7 or higher
• PostgreSQL: 12 or higher
• Redis: 6 or higher (for production Sidekiq)
• Twilio Account: For voice calling
• Google Gemini API Key: For AI features

git clone https://github.com/irkky/autodialer.git
cd autodialer

bundle install

# Create and migrate database
rails db:create
rails db:migrate

# Optional: Load seed data
rails db:seed

Create a .env file from the example:

cp .env.example .env

Edit .env with your credentials (see Configuration section).

Create a .env file in the project root with the following variables:

# ======================
# TWILIO CREDENTIALS
# Get these from: https://console.twilio.com
# ======================
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_PHONE_NUMBER=+18005551234

# ======================
# GEMINI API KEY
# Get from: https://ai.google.dev/
# ======================
GEMINI_API_KEY=AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXX

# ======================
# BASE URL
# Must be publicly accessible by Twilio
# Use ngrok for local development:
# ngrok http 3000
# ======================
BASE_URL=https://yourapp.ngrok-free.app

# ======================
# REDIS CONFIG
# For Sidekiq background jobs
# ======================
REDIS_URL=redis://localhost:6379/0

# ======================
# RAILS ENVIRONMENT
# ======================
RAILS_ENV=development

# ======================
# DATABASE (Optional)
# PostgreSQL password if required
# ======================
AUTODIALER_DATABASE_PASSWORD=your_password

# ======================
# SIDEKIQ (Optional)
# Set to false to use Redis in development
# ======================
SIDEKIQ_INLINE=true

1. Create a Twilio Account: Sign up at twilio.com

2. Get a Phone Number: Purchase or use a trial number

3. Configure Webhooks: In Twilio Console → Phone Numbers → Active Numbers → Configure

   Setting	URL
   Voice URL	https://your-domain.com/twilio/voice_response
   Status Callback	https://your-domain.com/twilio/status_callback
   HTTP Method	POST

4. Verify Numbers (Trial Account): Add test numbers to your Verified Caller IDs

1. Visit Google AI Studio
2. Create a new API key
3. Add the key to your .env file as GEMINI_API_KEY

To expose your local Rails server to Twilio:

# Install ngrok
brew install ngrok  # macOS
# or download from https://ngrok.com/download

# Start ngrok
ngrok http 3000

# Copy the HTTPS URL to your .env file as BASE_URL
# Example: https://abc123.ngrok-free.app

rails server

Visit: http://localhost:3000

# In development, jobs run inline by default
# To use Redis + Sidekiq:
SIDEKIQ_INLINE=false rails server

# In a separate terminal:
bundle exec sidekiq -C config/sidekiq.yml

ngrok http 3000

1. Navigate to Upload Numbers (/calls/new)
2. Choose your input method:
   • Paste: Enter numbers (one per line)
   • Upload: Select a .txt or .csv file
3. Click Start Dialing
4. View real-time status in the modal
5. Check Call Logs for detailed results

1. Navigate to AI Command Center (/ai)
2. Enter a natural language command:
   • Call +1 800 555 0100
   • Dial the previous number
   • Call the last 3 numbers
3. Gemini extracts the intent and number
4. System queues and processes the call
5. View results in Call Logs

Direct Number Calling:

Call +1 800 555 0100
Dial 9876543210
Ring +91 98765 43210 now

Historical References:

Call the previous number
Dial the last number again
Call the same number
Ring the second last number
Call the before last number

Ordinal References:

Call the first number
Dial the third entry
Ring the 5th number from the list

Bulk Historical:

Call the last two numbers
Dial the last 5 numbers
Ring last three numbers

Navigate to Call Logs (/logs) to see:

• 📊 Status: Completed, Failed, Busy, No-answer
• ⏱️ Duration: Call length in seconds
• 🕐 Timestamps: Start and end times
• 📞 Number: Called phone number
• 🔄 Updates: Real-time status changes

Useful commands for testing and maintenance:

rake autodialer:generate_test_logs

Creates 10 fake call records with random statuses.

rake autodialer:clear_logs

Deletes all call records from the database.

TEST_NUMBER=+18001234567 rake autodialer:simulate_call

Creates a simulated call record without actually calling.

autodialer/
├── app/
│   ├── controllers/
│   │   ├── ai_controller.rb          # AI command processing
│   │   ├── calls_controller.rb        # Bulk upload handling
│   │   ├── logs_controller.rb         # Call log display
│   │   └── twilio_controller.rb       # Webhook handlers
│   │
│   ├── models/
│   │   └── call_record.rb             # Call data model
│   │
│   ├── services/
│   │   ├── gemini_ai.rb               # AI integration
│   │   └── twilio_service.rb          # Twilio API wrapper
│   │
│   ├── workers/
│   │   ├── dialer_worker.rb           # Call processing job
│   │   └── twilio_status_sync_worker.rb  # Status polling
│   │
│   └── views/
│       ├── ai/                        # AI command interface
│       ├── calls/                     # Upload pages
│       └── logs/                      # Log display
│
├── config/
│   ├── initializers/
│   │   ├── sidekiq.rb                 # Redis config
│   │   ├── sidekiq_inline.rb          # Development mode
│   │   └── twilio.rb                  # Twilio setup
│   │
│   └── routes.rb                      # Application routes
│
├── db/
│   └── migrate/
│       └── create_call_records.rb     # Database schema
│
└── lib/
    └── tasks/
        └── autodialer.rake            # Custom rake tasks

• ✅ Render.com - Easy Rails deployment
• ✅ Railway.app - One-click deployment
• ✅ Fly.io - Global edge network
• ✅ Heroku - Classic PaaS

1. Set Environment Variables: All production credentials
2. Configure Redis: For Sidekiq job processing
3. Setup PostgreSQL: Production database
4. Compile Assets: rails assets:precompile
5. Run Migrations: rails db:migrate
6. Update BASE_URL: Point to production domain
7. Configure Twilio Webhooks: Use production URLs
8. Enable HTTPS: Required for Twilio webhooks

RAILS_ENV=production
SECRET_KEY_BASE=<generated_key>
TWILIO_ACCOUNT_SID=<your_sid>
TWILIO_AUTH_TOKEN=<your_token>
TWILIO_PHONE_NUMBER=<your_number>
GEMINI_API_KEY=<your_key>
BASE_URL=https://your-production-domain.com
REDIS_URL=redis://your-redis-url:6379/0
DATABASE_URL=postgresql://user:pass@host:5432/dbname

Generate SECRET_KEY_BASE:

rails secret

1. Connect your GitHub repository
2. Set environment as Web Service
3. Add environment variables
4. Set build command: bundle install && rails assets:precompile && rails db:migrate
5. Set start command: bundle exec puma -C config/puma.rb
6. Add Redis addon
7. Deploy!

• ✅ Use test/verified numbers only
• ✅ Store credentials in .env (never commit)
• ✅ Enable CSRF protection
• ✅ Validate phone number formats
• ✅ Rate limit API calls

• ✅ Enable HTTPS/SSL
• ✅ Secure environment variables
• ✅ Use strong SECRET_KEY_BASE
• ✅ Restrict Sidekiq dashboard access
• ✅ Monitor Twilio usage and costs
• ✅ Implement authentication for admin pages
• ✅ Add CAPTCHA for public-facing forms
• ✅ Set up request rate limiting

• Never call real people without explicit consent
• Comply with TCPA regulations (US) and local laws
• Respect Do Not Call lists
• Include opt-out mechanisms in scripts
• Monitor for abuse and suspicious patterns
• Secure webhook endpoints (verify Twilio signatures)

Problem: Calls fail with 403 or authorization errors

Solution:

• Verify TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN in .env
• Check that credentials match your Twilio console
• Ensure phone number format includes country code

Problem: Twilio can't reach your voice_response endpoint

Solution:

• Confirm BASE_URL is publicly accessible
• Check ngrok is running for local dev
• Verify webhook URLs in Twilio console
• Ensure Rails server is running

Problem: Status never updates from "queued"

Solution:

• Check Sidekiq is running (production)
• Verify Redis connection
• Check logs: tail -f log/development.log
• Ensure TwilioStatusSyncWorker is executing

Problem: AI commands don't trigger calls

Solution:

• Verify GEMINI_API_KEY is set correctly
• Check API quota/billing on Google Cloud
• Ensure number is in E.164 format
• Review GeminiAi.process_command logic

Problem: Can't connect to PostgreSQL

Solution:

• Start PostgreSQL: brew services start postgresql
• Check database exists: rails db:create
• Verify database.yml credentials
• Ensure PostgreSQL is running on port 5432

POST /twilio/voice_response

Receives initial call connection request from Twilio.

Parameters:

• CallSid - Unique call identifier

Response: TwiML voice instructions

POST /twilio/status_callback

Receives call status updates from Twilio.

Parameters:

• CallSid - Unique call identifier
• CallStatus - Current status (queued, ringing, in-progress, completed, failed)
• To - Destination phone number
• StartTime - Call start timestamp
• EndTime - Call end timestamp
• CallDuration - Duration in seconds

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

• Follow Ruby style guide
• Write meaningful commit messages
• Add tests for new features
• Update documentation
• Keep dependencies up to date

This project is licensed under the MIT License. See the LICENSE file for details.

Built with these amazing technologies:

• Ruby on Rails - Web framework
• Twilio - Voice API
• Google Gemini - AI/ML capabilities
• Sidekiq - Background processing
• PostgreSQL - Database
• Redis - Job queue
• Bootstrap - UI components