-
-
How it works: from an overdue invoice to a payment, with the freelancer in the loop
-
The freelancer’s dashboard: every overdue invoice, call outcome and promise in one view
-
Create and send real PayPal sandbox invoices from the app
-
Live PayPal sandbox invoices: green when paid, amber when disputed, with a one-line summary of each call
-
The client’s side: an incoming call from the payment assistant
-
The assistant asks the client to hold while the freelancer decides; Anything outside freelancer’s limits pauses the call for human decision
-
Dispute Handling: Disputes stop collection until the freelancer resolves them
-
Missed calls retry on their own, then fall back to a PayPal reminder
-
Call monitor: the live transcript and summary, here a client disputing the work
-
Recovery analytics: recovery rate, time to pay, and promises kept vs broken
-
Deployed on Render: a Python API and a static dashboard, defined in render.yaml
Inspiration
Freelancers lose time and money to late invoices, and the follow-up is the part nobody wants to do. It feels awkward, it is easy to put off, and an unpaid invoice quietly turns into a bad month.
I wanted an assistant that does the chasing politely and consistently, but never makes decisions the freelancer has not agreed to.
What it does
FreeVoice works through a freelancer's overdue PayPal invoices. For each one, it picks a tone based on how late the invoice is, then calls the client (a browser call with voice or typing).
The assistant:
- Says it is an AI.
- Asks for payment or a firm date.
- Negotiates within limits set by the freelancer in a policy file: maximum extension days and maximum discount.
If a client asks for something outside those limits, the assistant asks them to hold and pauses the call for the freelancer, who approves or denies the request through a dashboard.
It also:
- Retries missed calls, then sends a PayPal payment reminder when it gives up.
- Follows up with a new call when a promised date passes unpaid.
- Stops collecting and flags the invoice when a client disputes the work.
- Writes a one-sentence summary of every call for the freelancer.
- Shows recovery analytics: recovery rate, time to pay, promises kept vs. broken.
- Closes the loop when PayPal's
INVOICING.INVOICE.PAIDwebhook arrives, so the chasing stops the moment money lands.
How PayPal and AI are used
PayPal:
- Invoicing API (create, send, list, fetch, remind).
- PayPal Agent Toolkit for the agent's own tools.
- Webhooks (
INVOICING.INVOICE.PAID) with signature verification.
The agent is only given the reminder and QR tools. It cannot create or cancel invoices.
AI:
Gemini 3.5 Flash runs the conversation and judgment calls, such as distinguishing a client who is unhappy with the work (a dispute) from one who needs to ask their manager (a delay).
LangGraph runs the agent as a stateful graph with a human-in-the-loop interrupt() for freelancer approval, checkpointed in SQLite.
How we built it
- Backend: Python, FastAPI, LangGraph and LangChain, with a small background scheduler for retries and follow-up calls.
- Frontend: React and Vite, with an AG Grid table for invoices, a live call monitor, an approval queue, and a separate client call page.
- Voice: The browser's built-in speech recognition and speech synthesis, so it needs no extra keys.
- Hosting: Render, with a Python web service for the API and a static site for the dashboard.
Guardrails are enforced in code, not only in the prompt:
- Policy limits.
- Date validation (past dates are rejected).
- A restricted tool list.
- A hard pause on disputed invoices.
Challenges we ran into
1. Making sure the model can't skip its own guardrail
My first design relied on the model calling a policy-check tool before escalating. In testing, it often turned down out-of-policy requests straight from the prompt without calling the tool, so the freelancer was never asked and the call just ended.
Stricter prompting didn't fully fix it. What worked was taking the decision away from the model's discretion: a call can only escalate by ending with a needs_approval outcome, and the graph routes that outcome to the approval step in code.
2. Gemini 3 thought signatures
Replaying tool calls back to the model caused 400 errors, so the history is now sent as plain text while the real messages stay in state.
3. Human approval inside a live conversation
Pausing a LangGraph run for the freelancer and resuming it with the client still on the line took careful state design.
4. Getting real sandbox money moving, and then deploying it
PayPal returned permission errors until the Invoicing feature was enabled on the app and the sandbox accounts were moved to a supported country.
After that came deployment challenges:
- Build-time environment variables.
- CORS between two services.
- A Python version mismatch between my machine and the host.
- A webhook that needs a public URL and signature verification.
Accomplishments that we're proud of
A full loop that ends with real sandbox money: a late invoice, a negotiated call, a freelancer decision, a payment through PayPal, and a verified webhook that closes it out, with guardrails the freelancer controls.
What we learned
How to design an agent where the model is allowed to talk but not to decide, and how much of "agentic" is state management and guardrails rather than prompting.
What's next for FreeVoice
- A telephony provider behind the call link, with the retry logic already in place.
- Applying approved discounts to the PayPal invoice.
- Ending the call at the hold and calling back with the freelancer's answer.
- Multilingual calls.
- Moving retry and follow-up scheduling to Render Workflows.