Updated SMS alert feature

[InzeeraZakariah]

Overview

This PR introduces an automated weather alert notification system that sends SMS alerts to subscribed users based on severe weather conditions detected from OpenWeatherMap forecast data.

Fix #107

Features Added

• SMS subscription endpoint (/subscribe-alert)
• Subscriber storage using subscribers.json
• Automated weather monitoring using APScheduler
• SMS notifications through Vonage API
• Severe weather detection logic
• Automatic periodic alert checks

Weather Alert Conditions

The system sends SMS alerts when any of the following conditions are detected:

Condition	Threshold
Heavy Rain Warning	Rainfall ≥ 10 mm
Strong Wind Warning	Wind Speed ≥ 30 km/h
Potential Flood Risk	Humidity ≥ 85% and Rainfall ≥ 5 mm
Heatwave Alert	Temperature ≥ 35°C
Thunderstorm Alert	Weather contains "Thunderstorm"

Subscriber Workflow

1. User enters city and phone number.
2. Frontend sends POST request to /subscribe-alert.
3. Backend validates and stores subscriber data.
4. APScheduler periodically checks weather forecasts.
5. If severe weather is detected, an SMS alert is sent automatically.

APScheduler Integration

Testing configuration:

scheduler.add_job(
    func=check_weather_and_send_alerts,
    trigger="interval",
    minutes=1
)

Recommended production configuration:

scheduler.add_job(
    func=check_weather_and_send_alerts,
    trigger="interval",
    hours=1
)

Vonage API Integration

Setup Steps

1. Create a Vonage account at [dashboard.nexmo.com](https://dashboard.nexmo.com/)
2. Obtain API Key and Secret from the dashboard
3. Add them to environment variables:

VONAGE_API_KEY=YOUR_API_KEY
VONAGE_API_SECRET=YOUR_API_SECRET

Install Vonage SDK

pip install vonage==2.5.5

SMS Sending Flow

response = vonage_sms.send_message({
    "from": "ClimateShield",
    "to": phone,
    "text": sms_text
})

Handling Low or Negative Vonage Balance

Vonage stops delivering SMS messages when account credit is insufficient or negative.

Symptoms:

• SMS not received even when API returns status: '0'
• remaining-balance shows a negative value
• Messages appear sent in logs but never arrive

Example log:

'remaining-balance': '-0.27940000'

Protection Example:

response = vonage_sms.send_message(payload)

message = response["messages"][0]
remaining_balance = float(message.get("remaining-balance", 0))

if message["status"] == "0" and remaining_balance >= 0:
    print("SMS Sent Successfully")
elif message["status"] == "0" and remaining_balance < 0:
    print("Warning: SMS may not deliver — Vonage balance is negative.")
    print(f"Remaining Balance: {remaining_balance}")
else:
    print("SMS Failed")
    print("Reason:", message.get("error-text"))

Testing

Manual Subscription Test

POST /subscribe-alert

Request body:

{
  "city": "Kanyakumari",
  "phone": "91XXXXXXXXXX"
}

Expected response:

{
  "success": true,
  "message": "SMS enabled successfully"
}

Scheduler Test

Logs:

Checking weather for 1 subscribers...

If severe weather exists:

SMS Response:
{
  ...
}

Future Improvements

• Prevent duplicate alerts within a configurable time window
• Store subscription data in a database instead of JSON
• Add unsubscribe functionality
• Add SMS delivery status tracking
• Add support for WhatsApp notifications
• Add daily weather summaries
• Add low-credit monitoring and admin alerts

Impact

This feature enables proactive weather alert notifications, helping users receive critical climate warnings directly on their mobile devices without needing to open the application.

[InzeeraZakariah]

hi @Vikrant0207 ,

I have opened the new pr, kindly check it
thanks

[prathmk85]

Hi @InzeeraZakariah ! New contributor here. Super amazing to see this SMS alert feature! Had a doubt though.
Why does the temperature in SMS show "?C" instead of "°C"? Is it because sms doesn't support degree symbol or is it a Vonage API issue?
Just curious. Thanks!

[Vikrant0207]

@InzeeraZakariah

its still same for me

[InzeeraZakariah]

@InzeeraZakariah its still same for me

@Vikrant0207
I will check and update the PR

[InzeeraZakariah]

@Vikrant0207 ,

Kindly check the updated PR, it works now.