Outbound Call Limiter

💡 What Happens When Someone Calls:

If the number IS in your CSV:
• System checks how many times it's been called today
• If under the limit → Call goes through normally
• If at the limit → Caller hears: "Sorry, you've reached the maximum number of times you can call this number. Please try again tomorrow."

If the number is NOT in your CSV:
• Call goes through with no restrictions (unlimited calls allowed)

📋 Required Columns:

1. Phone - The phone number (10 digits, no dashes, spaces, or +1)
2. Limit - The daily call limit for that number (any whole number)

Example: A file with "Phone" as the first column header and "Limit" as the second column header, followed by rows of phone numbers and their corresponding limits.

💻 API Upload (For Automation)

Best for scheduled daily uploads and automation. Use cURL, Python, or any HTTP client to upload programmatically.

Daily Upload (Full Replace):
curl -X POST "https://outbound-fitness-international.telnyx-worker.dev/outbound/upload?type=daily" -F "file=@/path/to/members.csv"

Delta Upload (Update Only):
curl -X POST "https://outbound-fitness-international.telnyx-worker.dev/outbound/upload?type=delta" -F "file=@/path/to/updates.csv"

Perfect for: Cron jobs, scheduled tasks, CI/CD pipelines, automated workflows

Processing Times:
• Small files (under 1000 rows): 5-10 seconds
• Medium files (10,000-100,000 rows): 10-20 seconds
• Large files (1-3 million rows): 30-60 seconds

How It's So Fast: The system splits your CSV into ~4,000 record chunks and processes them in parallel using Cloudflare Queues. A 1.16M record file becomes 291 chunks that all process simultaneously!

Why It's Fast & Resource-Efficient:

Instead of processing your CSV file sequentially, we use sophisticated parallel processing with hash-based change detection:

1. Instant CSV Parsing - Your file is parsed and deduplicated in the main worker (takes ~7-10 seconds even for 15MB files)
2. Smart Chunking - Records are split into 4,000-record chunks (~120KB each)
3. Parallel Queue Processing - All chunks are sent to Cloudflare Queues and processed simultaneously by multiple workers
4. Hash-Based Change Detection - Each record gets a hash (phone + limit). Only records with changed hashes are written to the database
5. Database Batching - Changed records are written in 1,000-record batches for optimal performance

Optimization: For hourly 1M+ delta uploads where most records don't change, hash-based detection skips 90%+ of database writes, drastically reducing resource usage and cost!

Example: A 1.16M record file becomes 291 chunks that all process at the same time. If 95% of records are unchanged, only 58K records are actually written - reducing total processing time to 30-60 seconds!

Monitoring Your Upload:

When you upload a file, you receive an upload_history_id. Use this to check status:

GET /outbound/upload/status?id={upload_history_id}

Returns:
• status: "pending" (queued), "processing" (in progress), or "completed"
• records_processed: Total records in CSV
• records_added/updated: How many records were written
• Storage information and timestamps

Daily Upload (Full Replace):

What happens:
• First chunk: Deletes ALL existing records from database
• All chunks: Insert fresh records with counter = 0
• Last chunk: Marks upload as "completed"

Use case: Morning refresh to give everyone a clean slate for the new day

Delta Upload (Selective Update):

What happens:
• No purge! Existing data is preserved
• For each phone: Check if it exists in database
• If exists: Update limit only (preserve current counter)
• If new: Insert with counter = 0

Use case: Mid-day adjustments without affecting existing call counters