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.

Read this firstPayment calls are regulated. Rules on who you may call, when, how often and what you must say depend on your country, your state and whether you collect your own invoices or someone else's. Have your counsel approve the script and your calling schedule before the first live call. The API enforces none of these rules for you.

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_due the 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

PartExample content
OpeningSay 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.
ReminderOnce identity is confirmed: the invoice number, the amount, the due date, and how to pay. Ask if they can take care of it.
Will payConfirm where the payment link is, thank them, close.
Needs timeAsk when they expect to pay, note the date, say the billing team will be in touch if needed, close.
Disputes or hardshipDo not argue or try to resolve it. Say the billing team will contact them, escalate, close.
Asks not to be calledConfirm the request, close. Your system must stop further calls.
VoicemailA 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 rulesNo 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 factscustomer_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.status and data.outcome.summary: whether the reminder was delivered and what Bobby said, for the invoice record. outcome can be null when 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 firstMessage or the script's opening.
  • Opt-outs. Record "do not call" requests from the transcript or outcome and honour them.

Which call should your agent take first?

Tell us which requests your team handles most often. We'll suggest a practical place to start.

Tell us about your calls