Docs/Voice API/Payment reminders
Payment reminder calls
A polite, consistent reminder for invoices that slipped through. The agent confirms it is speaking to the right person, states the balance, points to a secure way to pay, and hands anything unusual to your billing team.
The scenario
A software company bills monthly. Bobby's invoice INV-2026-0547 for 154.56 US dollars was due on October 25 and is still open, and the reminder email went unanswered. The billing system places one reminder call. The agent's job is to remind, not to negotiate: it confirms the balance, makes paying easy, and records what Bobby says.
The request
See the Voice API overview for keys and headers.
curl -X POST https://api.talktomyagent.io/v1/voice/calls \
-H "Authorization: Bearer $TTMA_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: inv-2026-0547-reminder-1" \
-d '{
"from": "+16475550100",
"to": "+12025550199",
"targetName": "Bobby",
"triggeredBy": "billing-overdue-reminder",
"maxDurationSecs": 180,
"task": {
"goal": "After confirming you are speaking with Bobby, remind him that invoice INV-2026-0547 is past due, tell him how to pay, and note what he says.",
"script": "payment_reminder",
"facts": {
"customer_name": "Bobby",
"company_name": "Example Software",
"invoice_id": "INV-2026-0547",
"amount_due": "154.56 US dollars",
"due_date": "October 25",
"how_to_pay": "the secure payment link in the invoice email from billing@example.com",
"billing_email": "billing@example.com"
},
"escalation": "If he disputes the charge, asks for different terms, or mentions hardship, do not discuss it further: say the billing team will contact him, email them a one-line summary, and end the call politely."
}
}'
- Identity before details. The goal tells the agent to confirm the person first. The script repeats it. Nothing about the invoice is said until the right person is on the line.
- Amounts as words. Send
amount_duethe way it should be spoken, with the currency. - Payment happens through your link. The agent points to your existing secure payment page. It does not take card numbers on the call.
- escalation is acted on with the tools your agent has; emailing your billing team a summary is the usual choice.
What the script covers
| Part | Example content |
|---|---|
| Opening | Say who is calling and ask for the customer by name. If someone else answers, ask when is a good time to reach them and leave no details. |
| Reminder | Once identity is confirmed: the invoice number, the amount, the due date, and how to pay. Ask if they can take care of it. |
| Will pay | Confirm where the payment link is, thank them, close. |
| Needs time | Ask when they expect to pay, note the date, say the billing team will be in touch if needed, close. |
| Disputes or hardship | Do not argue or try to resolve it. Say the billing team will contact them, escalate, close. |
| Asks not to be called | Confirm the request, close. Your system must stop further calls. |
| Voicemail | A neutral message with no invoice details: the company name, a request to call back, and the billing contact. Answering machines and shared phones are heard by others. |
| Hard rules | No threats of any kind (legal action, credit reporting, service cut-off) unless counsel has approved that exact wording and it is true. No discounts or new terms. No card details over the phone. Stay courteous whatever the reply. |
| Required facts | customer_name, invoice_id, amount_due, due_date. With published scripts, a call missing one is refused with 400 before dialing. |
Reading the result
From the call.ended webhook or GET /v1/voice/calls/{callControlId}:
data.outcome.statusanddata.outcome.summary: whether the reminder was delivered and what Bobby said, for the invoice record.outcomecan benullwhen the webhook arrives; fetch the call later for it.data.transcript: the record of exactly what was said, useful if a dispute follows.data.task.facts.invoice_id: echoed back, so you can match the call to the invoice.
Compliance checklist
- Consent to call. In the US, the FCC treats AI-generated voices as artificial voices under the TCPA. Calls to mobile numbers generally need the customer's prior express consent, which your terms of service may or may not provide.
- Collecting for someone else. If you collect debts owed to another company, US federal rules (the FDCPA and Regulation F) apply, including calling hours of 8 AM to 9 PM in the consumer's local time, limits on how often you call, required disclosures, and a ban on discussing the debt with third parties. Many states add their own rules, some of which also cover companies collecting their own invoices.
- Frequency. Decide a maximum, for example one reminder call per invoice per week, and enforce it in your system. The API only limits you to 5 calls per hour to one number.
- Recording notice. Calls are recorded by default. Where a notice is required, put it in
firstMessageor the script's opening. - Opt-outs. Record "do not call" requests from the transcript or outcome and honour them.