Failed-Delivery (NDR) Recovery

Failed-Delivery (NDR) Recovery

Drain the failed-delivery queue same-day — decode the vague landmark address the rider couldn't find, and book a reattempt before the parcel is returned to origin.

Built on the Telenow App Platform as a pure declarative app: the data model, the agent tools, the courier NDR webhook, the rescue workflow, the vernacular agent, and the address-decoding knowledge base all run on-platform. No external server.

The problem (and the number)

In Indian e-commerce, first-attempt delivery fails on roughly 8–20% of shipments — and more than 45% of the resulting returns-to-origin (RTO) trace back to landmark-style addresses that geocoders and new riders simply can't decode: no house number, informal directions ("near Ganesh temple, second lane"), or a landmark that changed. Every failed attempt starts a clock — couriers hold the parcel for a limited reattempt window (commonly 24h) and then auto-return it. An RTO is pure loss: forward freight, reverse freight, and re-handling on a parcel that earned nothing.

The single biggest lever is a fast, same-day call in the customer's own language that turns the informal address into something a rider can actually follow and books a redelivery slot inside the window. Failed-Delivery (NDR) Recovery does exactly that, automatically.

How it works

Courier / aggregator  ──(NDR / failed-delivery webhook)──►  ndr_case object (status: open)
        │                                                          │
        │                                              fires object.ndr_case.created
        ▼                                                          ▼
   dedupe on AWB                                        call_ndr workflow
                                                          ├─ delay ~2 min
                                                          └─ outbound-call  {{settings.ndr_agent_id}}
                                                                → dials {{trigger.data.phone}}
                                                                → passes awb, address, landmark, reason
                                                                    │
                                                                    ▼
                                                Failed-Delivery (NDR) Recovery Agent (Sarvam, vernacular)
                                                find_case → confirm they want the parcel
                                                → decode landmark address (update_address)
                                                → book reattempt slot (book_reattempt)
                                                → already delivered? mark_resolved
                                                → refuse? mark_rto   · stuck? flag_review

Everything the agent does on the call updates the same ndr_case rows you see on the dashboard — and the dashboard's Call now button dials through the same agent and tools.

Agent tools (used mid-call — all declarative)

The bundled Failed-Delivery (NDR) Recovery Agent is a multi-context flow: a deterministic find_case tool node (looks the caller up in this app's data) → a conversation node that confirms intent, decodes the address, and books the reattempt. STT/TTS default to Sarvam (anushka) for Tier-2/3 vernacular customers.

Dashboard pages

• Failed-Delivery (NDR) Recovery (dashboard) — KPI tiles (open cases, at-risk on the RTO clock, reattempts booked, RTO prevented, rescue rate %), a live rescue clock ranking open cases by hours-left, and a case-status mix. Also powers the platform dashboard_widget slot in a compact form.
• Cases — the NDR queue sorted by age (oldest failed delivery first) with an hours-left countdown per open case, status filters, search, and Call now to trigger a rescue call for any case (passes the case's context variables to the agent).
• Review — the human_review queue: cases the agent escalated because the address still couldn't be decoded or the order was disputed. Mark each resolved once handled.
• Setup — a configuration checklist, a one-click Create NDR agent button, and the post-install wiring steps.

Knowledge base

ndr-playbook ships four real scripts the agent answers from: decoding a vague landmark address (ask for the nearest shop/temple/school, floor, gate colour, and a call-on-arrival number), handling "I wasn't home" and refusals, reattempt policy and the return-to-origin clock, and first-attempt-failure & landmark-address facts.

Install & post-install wiring

1. Install Failed-Delivery (NDR) Recovery into your org.
2. Open Setup → Create NDR agent (builds the bundled Sarvam agent, auto-wired to the tools + KB).
3. Copy the new agent's ID into the app's NDR agent ID setting (ndr_agent_id) so call_ndr can dial.
4. (Optional) Set Reattempt window (hours) (reattempt_window_hours, default 24) to match your courier's hold time, and Courier API key (courier_api_key) to push corrected addresses back to the courier.
5. Point your courier's non-delivery (NDR) webhook at the inbound hook courier_ndr (verified with x-courier-signature, deduped on AWB). Failed deliveries now flow in and auto-dial. Works with Delhivery, Shiprocket, Xpressbees, Ecom Express, or any courier that can POST an NDR webhook.

Settings

Bulk dialing your backlog

The real-time path (webhook → workflow → call) covers new failed deliveries. To sweep an existing backlog of open NDRs, use the app-key campaign API:

POST /api/app-campaigns
{ "agentId": "<ndr agent id>",
  "targetQuery": { "status": "open" },     // over the `ndr_case` object
  "result": { ... write-back ... } }

Monetization

Failed-Delivery (NDR) Recovery is billed on outcomes, not seats: a fee per resolved NDR — each failed delivery the agent rescues (address decoded, reattempt booked, and delivered) avoids a return-to-origin, so the fee comes straight out of freight that would otherwise have been burned. Suspect refusals turned to rto and cases sent to human review are surfaced on the dashboard so the ROI is obvious.

Changelog

1.1.0 — 2026-07-12

• Renamed to Failed-Delivery (NDR) Recovery (business-friendly) with a marketplace icon.
• Added real UI screenshots (dashboard + key pages).
• Added mark_resolved so the “RTO prevented” KPI can be reached from a live call.
• Verified end-to-end loop closure: trigger → workflow → call → agent tools → write-back → dashboard.

1.0.0

• Initial release.
• Data model: ndr_case object (AWB, phone, customer, address, landmark, reason, reattempt slot, status, created_at) with open_queue / reattempt_booked / rto / resolved saved views, plus a human_review object (AWB, note, resolved) with a open_reviews view.
• Agent tools (declarative): find_case, update_address, book_reattempt, mark_rto, flag_review.
• Bundled agent: NDR Rescue Agent — a Sarvam vernacular multi-context flow (deterministic find_case lookup → confirm intent → decode landmark address → book reattempt) auto-wired to the tools and the NDR rescue knowledge base.
• Knowledge base: ndr-playbook — decoding a vague landmark address, handling "I wasn't home" and refusals, reattempt policy and the RTO clock, and first-attempt-failure & landmark-address facts.
• Automation: courier_ndr inbound webhook (HMAC-SHA256 verified, dedupe on AWB); call_ndr workflow (delay ~2 min → outbound rescue call passing awb/address/landmark/reason).
• Dashboard UI: KPI tiles (open, at-risk, reattempts booked, RTO prevented, rescue rate), a live 24h rescue clock ranking open cases by hours-left, and a case-status mix; also renders into the dashboard_widget slot in compact form.
• Cases page: age-sorted NDR queue with per-case hours-left countdown, status filters, search, and per-case Call now (passes case context variables to the agent).
• Review page: the human-review queue with one-click Mark resolved.
• Setup page: configuration checklist + one-click Create NDR agent and post-install wiring steps.
• Self-seed: a fresh install auto-loads six realistic demo cases across every status (plus one human-review flag), so the dashboard and rescue clock are populated on first open.