# How do I use a voice agent for payment reminders and promise-to-pay capture?

A payment-reminder or EMI follow-up call placed through POST /v1/calls, with the promise-to-pay date spoken over the sessions API -- and recovered from the transcript, since /v1 publishes no structured slot map today. Written conservatively -- RBI's recovery-agent norms and DPDP consent requirements both bear on this use, and VARTA does not make that determination for you.


You trigger the call from your own billing or loan-management system when an account
is overdue, and the agent's job is to state the amount due, ask whether the customer
can commit to a date -- not to negotiate, threaten, or make a determination about the
account. Note that "capture" here means the agent elicits and confirms the date in
conversation; getting it back out as structured data is your work, not a field you
read (see step 3). Read the compliance
note below before wiring this up; it applies regardless of how the technical
integration is built.

## The call sequence

1. Your billing system identifies an overdue account and calls `POST /v1/calls`.

```bash
curl -X POST "$VARTA_BASE_URL/calls" \
  -H "Authorization: Bearer $VARTA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: emi-reminder-ACC-70019-2026-09" \
  -d '{
    "agent_id": "ag_412",
    "to": "+9198xxxxxxx",
    "customer_name": "Rahul",
    "context": {"account_id": "ACC-70019", "amount_due": 4200, "due_date": "2026-09-10"}
  }'
```

> **Agent ids are numeric and studio-assigned.** `ag_412` above is the shape the API
> actually issues: `/v1` strips the `ag_` prefix and parses the rest as an integer
> (`backend/app/api/v1/_ids.py:56-61`), so an author-chosen slug like
> `ag_cod_confirm` is rejected as malformed before any lookup happens. Use the id the
> studio gave your agent.

   Derive the `Idempotency-Key` from the account id and the billing cycle it's for, so
   a retry from your own scheduler can't place a second reminder call about the same
   due amount. See [Place a call](/docs/api/calls) for the full contract.
2. Poll `GET /v1/calls/{call_id}` or wait for your own end-of-call notification.
3. The conversation itself runs as a sequence of turns on the session underneath the
   call. **Do not plan to read the promise-to-pay date or amount out of
   `state.slots`** -- that field is published on every turn but is always `{}` on this
   build, and `GET /v1/sessions/{id}` returns no captured-slot key at all. See
   [Sessions](/docs/api/sessions), under "`state.slots` is currently always
   empty", for the derivation
   and the citations.
4. Recovering the promise-to-pay is therefore work you own today. What the API does
   give you: `state.step_progress.steps[<step_id>]` goes to `"done"` when the
   collecting step completed, the agent's own reply text usually restates the date or
   amount back to the customer, and the end-of-session `summary` object is where a
   structured outcome would arrive if the instance's summariser produced one (it can
   come back `{}`). Plan on parsing the transcript, or on asking the instance operator
   for the internal transcript export, rather than on a slot map that does not
   populate.

## Compliance -- this is not VARTA's determination to make

Two regulatory frameworks bear directly on an outbound payment-reminder call in India,
and neither is something the platform decides on your behalf:

- **RBI's Fair Practices Code and recovery-agent norms** govern *when* and *how* a
  lender or its agent may contact a borrower about a debt -- permitted calling hours,
  contact frequency, and conduct during the call. VARTA's telephony layer does not
  implement calling-window or contact-frequency enforcement; that scope is explicitly
  left to whatever sits above it, because it is a product and regulatory decision that
  differs by deployment and by lender, not a fixed rule the platform can bake in.
- **The DPDP Act, 2023** governs the consent basis for processing and calling a
  customer using their personal data. VARTA does not verify that you hold valid
  consent before a call is placed, and does not track consent state -- that is your
  system's responsibility, upstream of `POST /v1/calls`.

If you're building a collections use case on VARTA, both of these need to be handled
in the systems that trigger and gate the call, before the request ever reaches the
API. Treat the sample request above as illustrative of the integration mechanics only,
not as guidance on when it is lawful to make the call.

## What you still have to build

- **Calling-hours and frequency governance** -- deciding, and enforcing, when and how
  often a given account may be contacted, per the recovery-agent norms that apply to
  your business.
- **Consent capture and record-keeping** -- establishing and recording the DPDP consent
  basis for contacting this customer, before you trigger the call.
- **A grievance and opt-out path** -- a customer who disputes the amount or asks not to
  be contacted needs a route to a human and a way to have that request honoured.
- **Writing the outcome back into your loan-management system** -- the promise-to-pay
  date, or the lack of one, and any escalation the call surfaced.