RescueHacks Alert

A USSD code that looks like checking your airtime balance — but silently alerts security and can help track the caller's location when they're in danger.

Comment

Inspiration

Most emergency and safety apps assume you have privacy and time to use them. Open the app, tap through a menu, confirm a request. But in a real threat situation, someone following you, an unsafe domestic situation, a moment where you're not alone and not safe, that privacy doesn't exist. If a phone visibly shows a menu or an "alert sent" screen, it can escalate the exact danger the person is trying to escape.

We also wanted something that works everywhere, not just on smartphones with data. USSD does that. It works on any phone, needs no internet, and critically, dialing a USSD code looks completely ordinary. No one glancing at your screen can tell the difference between checking your airtime balance and silently calling for help.

That's the idea RescueHacks Alert is built on.

What It Does

RescueHacks Alert lets a user dial a discreet USSD code, with no interactive menu and no confirmation screen, that silently triggers a real time emergency alert to a trusted contact via WhatsApp, carrying the emergency type, the caller's phone number, and a timestamp.

The emergency type is encoded directly in the dialed digits:

Code Emergency Type
*384*23492*1# Medical Emergency
*384*23492*2# Safety Threat
*384*23492*3# Accident
*384*23492*4# Disaster (Fire/Flood)

Every dial, successful or not, returns the exact same neutral screen: "Service temporarily unavailable." There is no visible difference between a triggered alert and an unrecognized code, by design. Any visible difference would be a pattern a bystander could learn to recognize.

How We Built It

  • USSD gateway: Africa's Talking, using a shared sandbox service code, since a dedicated code requires telecom or regulator partnership beyond hackathon scope
  • Backend: AWS Lambda (Node.js 20.x) behind API Gateway, deployed via AWS SAM
  • Secrets: AWS Systems Manager Parameter Store
  • Alert delivery: Meta's WhatsApp Cloud API, sending a plain text alert directly to a pre-registered contact

The USSD handler reads the dialed digits on the very first callback (Africa's Talking passes anything typed after the base code as the initial session text), maps it to an emergency type, and critically awaits the WhatsApp send before returning the USSD response, since AWS Lambda freezes the execution environment the moment a response is returned, which would otherwise silently kill a "fire and forget" background call.

Challenges We Ran Into

  • CloudFormation rejected our WhatsApp access token as a deploy parameter due to special characters. Solved by moving secrets to SSM Parameter Store instead of CloudFormation parameters.
  • SSM SecureString references aren't supported inside Lambda environment variables, a genuine AWS limitation we didn't expect. We fell back to a plain String SSM parameter for the hackathon timeline, and documented the more correct runtime decryption approach as a near term fix.
  • We submitted an approved WhatsApp message template, but Meta silently reclassified it from Utility to Marketing category during review, which requires recipient opt in and didn't deliver to our test number. Rather than lose more time chasing template approval, we simplified to a direct plain text send, which has proven reliable in testing. The template fix is documented as a next step.
  • A permanent access token silently failed to deliver messages even though the API accepted every request, while Meta's own temporary test token worked immediately. We traced this to a permissions gap on the system user's assigned WhatsApp asset, fixed by granting full messaging scope and reissuing the token.
  • Silent failures were, well, silent. The very design goal, no visible confirmation, also meant our own early debugging attempts couldn't rely on the phone screen for feedback. We had to tail AWS Lambda logs directly and query Meta's API for ground truth to diagnose issues, a good reminder that "discreet by design" cuts both ways.

What We Learned

Designing for genuine discretion is harder than it sounds. Every default UX instinct, show a confirmation, show an error, show something, works against the actual safety goal here. The right answer was often to show nothing at all, and to trust the backend logs and the actual delivered alert as the only real signal of success. We also learned that "it returned success" and "it actually happened" are not the same thing, especially once approvals, permissions, and multiple third party systems are involved.

What's Next

This hackathon build proves the core mechanism. The long term vision is bigger: routing alerts not just to a personal contact but to registered security operatives, working in partnership with telecom providers who can, within their own lawful authority, assist in tracking the location of the phone that triggered the alert, similar to how emergency location services work in some countries. That requires real telecom and regulatory partnership beyond hackathon scope, but it's the direction this project is built toward. Full details are in our NEXT-STEPS.md, including plans for an automatic AI voice phone call escalation, multi-contact registration, and multi-language support.

Built With

Share this project:

Updates