DEV Community: Sonam Gupta

Build a Durable Chargeback Review Workflow on Telnyx Edge

Sonam Gupta — Fri, 02 Oct 2026 21:43:49 +0000

A chargeback is not a single API request. It is a case that can remain open for days while evidence arrives, deadlines approach, and a reviewer decides what should happen next.

That makes chargeback handling an interesting systems problem. The application needs to remember the case, wake up at the right time, evaluate evidence consistently, communicate with the customer, and preserve an audit trail even when the runtime restarts.

The chargeback-adjudication TypeScript example models each dispute as a durable actor running on Telnyx Edge Compute.

The sample combines:

One Stateful Actor per dispute
Telnyx Decision Models for structured evidence evaluation
Scheduled tasks for decision and response deadlines
SQL for evidence, review queues, and an append-only audit ledger
SMS for customer updates and reviewer escalation

The repository uses synthetic evidence and defaults to DEMO_MODE=true, so SMS messages are logged instead of sent while you explore the workflow.

The architecture

The central design choice is simple: the actor is the dispute case.

Chargeback webhook
        |
        v
DisputeCase actor, keyed by disputeId
        |
        +-- SQL evidence and audit rows
        +-- Scheduled decision task
        +-- Telnyx Decision Models request
        +-- Policy and human-review routing
        +-- Customer or reviewer SMS

Because the actor is keyed by disputeId, later evidence is routed back to the same durable case instead of being reconstructed from a stateless webhook request.

Create a case from a webhook

The Edge handler accepts a chargeback event at POST /webhook/chargeback:

if (path === "/webhook/chargeback" && req.method === "POST") {
  const payload = parseJson<ChargebackPayload>(await req.text());

  if (!payload || !payload.disputeId || !payload.customer || !payload.orderId) {
    return new Response(
      JSON.stringify({
        error: "disputeId, customer, and orderId required",
      }),
      { status: 400 },
    );
  }

  const stub = e.DISPUTES.idFromName(payload.disputeId);
  const result = await stub.onChargeback(payload);

  return new Response(JSON.stringify(result), { status: 200 });
}

idFromName() gives every dispute a stable actor identity. Inside onChargeback(), the actor stores the case state, seeds the sample evidence tables, calculates the response window, and schedules a decision task with a stable ID:

this.schedule(0, "decide", {}, {
  id: `decide:${disputeId}`,
});

Stable task IDs are useful when webhook delivery or application logic retries. Repeated work can converge on the same scheduled operation instead of creating a new timer every time.

Evaluate several questions in one Decision Models request

The actor assembles the order, delivery record, contact history, and any newly submitted evidence into one shared state object.

It sends that context to:

POST /v2/ai/typesafe/v1/systemone

One request asks three named questions:

const body = {
  state: JSON.stringify(evidence),
  questions: {
    decision: {
      type: "choice",
      instructions: "Rule on the chargeback.",
      criteria: {
        approve_rebate: "Delivery evidence supports the customer's order.",
        request_evidence: "Evidence is inconclusive; more proof is needed.",
        deny: "Evidence supports the merchant; deny the dispute.",
      },
    },
    loseProb: {
      type: "score",
      instructions: "Rate the merchant's risk of losing.",
      criteria: [
        "Clearly likely to win",
        "Uncertain",
        "Clearly likely to lose",
      ],
    },
    fraud: {
      type: "noul",
      instructions: "Does this look like a fraud attempt?",
    },
  },
};

These question types serve different purposes:

choice selects one supplied category.
noul produces a signal between zero and one.
score returns an expected position on the ordered rubric.

A Decision Models score should not automatically be treated as a calibrated probability. With three rubric entries, the result falls along the rubric’s zero-to-two range and can be fractional.

Production policy should be tested against representative, labeled cases rather than treating the result as certainty.

The endpoint defaults to telnyx/decision-flash when model is omitted. You can also set the model explicitly based on the context requirements of your workflow.

Keep model output separate from business policy

The model produces structured evidence signals. Application code still owns the business action.

The sample’s policy layer can:

Approve a rebate and notify the customer
Request additional evidence
Deny the claim
Route a suspected-fraud case to a human review queue

if (noul > FRAUD_THRESHOLD) {
  await db
    .prepare("INSERT INTO reviewQueue VALUES (?, ?, ?)")
    .bind(disputeId, new Date().toISOString(), "fraud_hold")
    .all();

  await sendSms(
    reviewerOnCall,
    `Review required for ${disputeId}`,
  );

  return;
}

The threshold in this sample is illustrative. Before using a similar rule in production, evaluate it against your own data, add authorization and reviewer controls, and clearly define which outcomes may be automated.

Decision Models help determine what deserves attention. They do not remove the human reviewer from high-risk decisions.

Re-evaluate when new evidence arrives

A dispute can change after its initial review.

The second webhook route, POST /webhook/inbound-message, sends an SMS or MMS response back to the existing actor:

async onNewEvidence(
  text: string,
  mediaUrl?: string,
): Promise<void> {
  const evidence = await this.assembleEvidence(mediaUrl);

  const result = await this.judgeWithDecisionModel({
    ...evidence,
    newEvidence: text,
  });

  await this.appendAudit("re-evaluated", result);
  await this.applyPolicy(result);
}

The case keeps its identity and previous state. New evidence becomes another event in the same lifecycle, and the resulting evaluation is appended to the ledger.

Preserve an audit trail in SQL

Every material event is written as a new row rather than overwriting the previous decision:

await db
  .prepare("INSERT INTO audit VALUES (?, ?, ?, ?)")
  .bind(
    disputeId,
    new Date().toISOString(),
    event,
    JSON.stringify(payload),
  )
  .all();

This append-only pattern makes it possible to reconstruct:

What evidence the application had
Which model output it received
Which policy branch was selected
When the state changed
Whether new evidence caused a re-evaluation

For a real financial or healthcare workflow, this example is only a starting point.

Add authentication, webhook verification, encryption, retention controls, idempotency around external actions, reviewer permissions, monitoring, and a domain-specific compliance review before processing sensitive data.

Run the sample

Clone the examples repository and install the dependencies:

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/chargeback-adjudication

npm install
cp .env.example .env

The sample configuration includes:

TELNYX_API_KEY=your_telnyx_api_key_here
RESPONSE_DEADLINE_DAYS=7
REVIEWER_ONCALL_E164=+1555XXXXXXXX
DEMO_MODE=true

Authenticate the Edge CLI, run the smoke test, and deploy:

telnyx-edge auth api-key set <your_telnyx_api_key>
npx tsx smoke_test.ts
telnyx-edge ship

DEMO_MODE=true suppresses real SMS delivery and uses synthetic evidence. The deployed adjudication path still requires a Telnyx API key to call Decision Models.

Where else this pattern fits

The reusable idea is larger than chargebacks: assign one durable actor to every long-running case, keep its evidence and history nearby, request structured model outputs, and let explicit application policy determine what happens next.

The same architecture could support:

Insurance claim review
Returns and refund exceptions
Account-verification cases
Compliance investigations
Support escalations with deadlines

Resources

Build Automated Post-Call QA Scoring with Telnyx Decision Models

Sonam Gupta — Fri, 02 Oct 2026 20:36:24 +0000

Support teams have a math problem.

Thousands of customer calls happen every week, but supervisors can manually review only a small fraction of them. Even when a call is graded, that score often ends up isolated in a spreadsheet. It cannot tell you whether an agent had one difficult conversation or is developing a pattern.

That creates two distinct engineering problems:

Coverage: evaluate more completed calls without requiring someone to listen to each recording.
Memory: preserve each agent's results long enough to identify trends and make better coaching decisions.

The open-source post-call-qa-scoring example addresses both. It uses Telnyx Decision Models to grade transcripts and a durable QAAgent actor to maintain the quality history for each support agent.

The result is not an autonomous disciplinary system. It is a way to surface calls and trends that deserve human attention.

What the application does

When a support call ends, the application:

receives the transcript from a call-conversation-ended webhook
uses transcription-saved as a fallback when the transcript is not embedded
routes the transcript to a durable actor keyed by the support agent ID
asks a Telnyx Decision Model for three structured grading signals
stores the result in private per-actor SQL
recomputes a five-call rolling average
flags or clears a coaching recommendation based on that trend
escalates potential compliance breaches to a manager over SMS
sends the team lead a daily per-agent digest

Each call ID is stored as a SQL primary key before grading is scheduled. The scheduled task also uses a stable ID, grade:<callId>, so webhook retries do not create duplicate grades.

Why use one actor per support agent?

The central design decision is this:

The actor is the agent's quality profile.

The worker resolves an actor with idFromName(agentId). Every later transcript for that support agent reaches the same durable actor.

const actorId = env.QA_AGENT.idFromName(agentId);
const qaAgent = env.QA_AGENT.get(actorId);

await qaAgent.recordCallEnded(
  callId,
  transcript,
  agentId,
  digestEnabled,
);

That actor owns the score history, rolling average, coaching state, breach records, and digest schedule. The application does not have to reconstruct the agent's history from a cache every time another call ends.

Grade the transcript into structured fields

Free-text model output is awkward for QA automation. If the model returns a paragraph, downstream code has to interpret that prose before it can calculate an average or apply an escalation threshold.

The example instead calls the Telnyx Decision Models endpoint:

POST /v2/ai/typesafe/v1/systemone

One request evaluates the transcript against three question types:

choice: pass or a specific failure category
noul: a 0–1 compliance-breach signal
score: an overall quality score from 0–5

The application can then apply ordinary program logic to typed values:

interface DecisionResult {
  choice: string;
  noul: number;
  score: number;
}

A call can pass its general quality evaluation and still carry a serious compliance signal. The sample therefore treats these fields independently. When noul > 0.8, it records the call in the breaches table and sends an immediate manager-review alert regardless of the pass/fail choice.

Decision Models do not replace the reviewer here. They decide which evidence should be placed in front of one.

Turn individual grades into a trend

After every successful grade, the actor queries its SQL history and recomputes a five-call rolling average.

SELECT ts, choice, noul, score, status, last_error
FROM scores
WHERE status = 'graded'
ORDER BY ts DESC
LIMIT 5;

If the average falls below QA_COACHING_FLOOR, the actor flags the agent for coaching. If later calls bring the average back above the threshold, it clears the flag automatically.

That distinction matters. One low score may be an isolated call. A declining rolling average is a stronger reason to investigate, coach, or review the underlying conversations.

Keep failures visible

The grading task uses bounded retries rather than retrying forever. Transient failures back off for 10, 30, and 60 seconds. If grading still cannot complete, the call is stored with status="ungraded" and a last_error value.

The daily digest can therefore distinguish between a low score and a transcript that was never successfully graded. Failed AI work does not quietly disappear from the reporting pipeline.

Try the complete pipeline without placing a call

The repository includes a synthetic demo endpoint. After deploying the example, call:

curl -X POST https://<edge-function-url>/demo/trigger \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "demo-agent",
    "callId": "demo-001",
    "transcript": "Agent: This call may be recorded for quality purposes..."
  }'

The endpoint routes the transcript through the same actor, Decision Models request, SQL history, trend calculation, and escalation logic used by the webhook flow. It is intended for demonstration and testing, so you can inspect the architecture before connecting a live call application.

Run the example

git clone https://github.com/team-telnyx/telnyx-code-examples.git
cd telnyx-code-examples/post-call-qa-scoring

npm install
cp .env.example .env
npm run typecheck
npm test
npm run deploy

For live Decision Models calls and SMS notifications, configure the Telnyx API key, a messaging-enabled Telnyx number, and the team lead's E.164 number as Edge secrets. The repository README documents every supported setting, including the coaching floor and digest hour.

Where to take this pattern next

The sample uses a regional-bank support scenario, but the architecture is useful anywhere conversations need consistent review over time:

contact-center coaching
healthcare communication audits
insurance disclosure checks
sales-call quality monitoring
customer-service escalation review

The important pattern is broader than call scoring: produce structured decisions, keep durable history around the entity being measured, and route high-stakes outcomes to a human.