Voice Reminder App

A Python Flask application that sends voice reminder calls using Twilio.

Features

• Make voice reminder calls via Twilio API
• RESTful API endpoints for scheduling reminders
• Webhook support for call status updates
• Test script for direct call testing

Prerequisites

• Python 3.7 or higher
• A Twilio account (sign up at https://www.twilio.com/)
• A Twilio phone number with voice capabilities

Setup Instructions

1. Install Dependencies

pip install -r requirements.txt

2. Configure Environment Variables

1. Copy the example environment file:

   cp .env.example .env

2. Edit .env and add your Twilio credentials:

   • TWILIO_ACCOUNT_SID: Found in your Twilio Console dashboard
   • TWILIO_AUTH_TOKEN: Found in your Twilio Console dashboard
   • TWILIO_PHONE_NUMBER: Your Twilio phone number (E.164 format, e.g., +1234567890)

3. Run the Flask Application

python app.py

The server will start on http://localhost:5000 by default.

4. Expose Your Local Server (for Webhooks)

Since Twilio needs to send webhooks to your server, you'll need to expose your local server to the internet. Use one of these options:

Option A: Using ngrok (Recommended for testing)

# Install ngrok: https://ngrok.com/download
ngrok http 5000

Copy the HTTPS URL provided by ngrok (e.g., https://abc123.ngrok.io) and use it in your Twilio webhook URLs.

Option B: Deploy to a cloud service Deploy your Flask app to Heroku, AWS, or another cloud platform.

Usage

Making a Call via API

Send a POST request to /make-call:

curl -X POST http://localhost:5000/make-call \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+1234567890",
    "message": "Don't forget your meeting at 3 PM today!"
  }'

Testing with the Script

Run the test script:

python make_call.py +1234567890 "Your reminder message here"

Or run it interactively:

python make_call.py

API Endpoints

• GET / - API information and available endpoints
• POST /make-call - Make a voice reminder call
  • Required JSON fields: to (phone number), message (optional, defaults to "This is your reminder.")
• POST /voice - Twilio webhook for handling voice calls (TwiML response)
• POST /call-status - Twilio webhook for call status updates

Project Structure

.
├── app.py              # Main Flask web server with API endpoints
├── make_call.py        # Test script for making phone calls
├── requirements.txt    # Python dependencies
├── .env.example        # Template for environment variables
├── .env                # Your actual environment variables (create this)
└── README.md           # This file

File Descriptions

app.py

The main Flask application that provides REST API endpoints for making voice calls. It handles:

• Making calls via Twilio API
• Generating TwiML responses for voice calls
• Receiving call status webhooks from Twilio

make_call.py

A standalone test script that demonstrates how to make a phone call using the Twilio Python SDK. Useful for testing your Twilio credentials and setup.

requirements.txt

Lists all Python package dependencies needed for the project:

• twilio: Twilio SDK for making calls
• flask: Web framework for the API server
• python-dotenv: For loading environment variables from .env file

.env.example

Template file showing what environment variables are needed. Copy this to .env and fill in your actual Twilio credentials.

README.md

This documentation file with setup and usage instructions.

Security Notes

• Never commit your .env file to version control
• Keep your Twilio Auth Token secret
• Use environment variables for all sensitive credentials
• Consider adding .env to your .gitignore file

Troubleshooting

• "Twilio client not initialized": Check that your .env file exists and contains valid credentials
• Call fails: Verify your Twilio phone number has voice capabilities and you have sufficient account balance
• Webhook not working: Ensure your server is publicly accessible (use ngrok or deploy to cloud)

License

This project is provided as-is for educational purposes.