WhatsApp expense assistant

Track spending by sending one message or a bill photo.

This dashboard is designed to help new users join the Twilio sandbox quickly, understand the number to message, and learn the exact commands they can use right away.

Setup checklist

A simple path for first-time users to connect WhatsApp to the bot and start logging expenses.

3 steps

1

Open WhatsApp on your phone
Use the WhatsApp app you want to connect. If you are using Twilio sandbox, keep this phone number ready for the join step.
2

Send the sandbox join code
Message join drove-lamp to the Twilio WhatsApp number shown on the right, then wait for Twilio to confirm the connection.
3

Start sending expenses
Try food 200, uber 150, or a bill photo. The bot will parse, store, and summarize the data for you.

What users can send

The bot accepts simple text commands or receipt images.

Examples

Input	Result
`food 200`	Logs a Food expense with the parsed amount.
`uber 150`	Stores the transaction under Transport.
`summary`	Shows category totals for the current month.
Receipt photo	Extracts the final amount and category from the image.

Operational notes

Small details that help users and maintainers understand the system at a glance.

Provider fallback is enabled

If the active AI provider fails, the app can fall back to the next configured provider automatically.

Designed for onboarding

The page focuses on the first two questions users usually have: what number to message and how to join the sandbox.

Onboarding timeline

What a good first-day rollout looks like for this bot from setup to live usage.

Step-by-step

0-15 min

Configure environment and credentials

Set Twilio keys, Supabase keys, and the AI provider in your env file, then start the server and confirm the dashboard is reachable.

15-30 min

Connect WhatsApp sandbox

Send the sandbox join message from your test phone, then verify that Twilio and your webhook receive and process messages end-to-end.

30-45 min

Validate commands and parsing

Test expense text parsing, image parsing, summary report, and delete-last behavior. Confirm data writes to Supabase as expected.

45-60 min

Production readiness check

Review logs, fallback behavior, and API quotas. If needed, swap provider priority and verify behavior under simulated provider failure.

Integration checklist

Use this before inviting real users or moving from sandbox to production sender.

Webhook URL configured: Twilio sandbox points to your live webhook endpoint with HTTPS.
Database healthy: Supabase table and summary RPC available with correct service role permissions.
Provider strategy set: Primary provider chosen and fallback providers configured with valid API keys.
Command UX verified: help, summary, report, and delete flow tested from a real WhatsApp device.
Operations baseline: cron job enabled and monitoring in place for webhook errors and provider failures.

Command and behavior reference

A fuller reference for support teams and first-time users so they know exactly what the bot does.

Command or input	Purpose	Expected bot response	Notes
`food 200`	Log a new expense	Saved confirmation with category, amount, and short note.	Natural phrases like paid 200 for lunch are also parsed.
`summary`	View monthly totals	Category-wise totals plus month total amount.	Uses monthly summary query in Supabase.
`report`	Detailed monthly ledger	Chronological expense list grouped by category.	Useful for audits and monthly reconciliation.
`delete last`	Undo most recent entry	Deletion confirmation of latest expense.	Removes only one latest transaction for that number.
Receipt image upload	Parse bill automatically	Extracted amount and category, then saved result.	Clear photos improve extraction reliability.
`help`	Show usage tips	Command menu with examples and supported actions.	Recommended for onboarding new users.

FAQ and troubleshooting

Answers to common issues users and operators usually hit during setup and day-to-day usage.

Messages are not reaching the bot. What should I check?

Confirm Twilio sandbox webhook URL, ensure your service is publicly reachable, and verify server logs for incoming webhook requests.

Join command not working in WhatsApp

Use the exact sandbox join phrase shown above, send it from the same number you plan to test with, and check Twilio sandbox status.

Why is AI parsing inconsistent for some receipts?

Low light, blur, and cropped totals reduce OCR quality. Ask users to send clear, front-facing images with visible total amount and date.

What happens if one provider quota is exhausted?

The provider fallback strategy attempts the next configured provider so requests can still be processed without manual intervention.

Why does summary not match expected totals?

Check timezone boundaries for monthly windows and verify entries were saved under the same WhatsApp number identifier.

How do we move from sandbox to production?

Get an approved WhatsApp sender in Twilio, update the sender number, switch webhook config, and update dashboard onboarding copy.