DEV Community: VoiceDash

Monitoring Retell Voice Agents in Production: Alert Rules, Disconnection Reasons and the Failures Transcripts Hide

Nabeel Hassan — Fri, 30 Oct 2026 10:48:25 +0000

Disclosure: I'm Nabeel, founder of VoiceDash, a client portal for Retell agencies. This is an adapted republish of a guide from the VoiceDash blog, rewritten for developers. Nothing below needs VoiceDash; it uses Retell's own features plus a little glue code.

TL;DR: A voice agent that passed every test on launch day can quietly break a month later: a calendar token expires, a webhook starts failing, the business changes its hours, or a provider has a bad afternoon. The agent keeps answering and sounds fine, and books nothing. Monitoring in production means watching four layers (is the line answering, are tools working, is quality holding, is usage normal), wiring a failover before you need it, and routing alerts to one place. Retell now ships most of the primitives; this post maps each layer to the field or feature that covers it.

Why testing is not enough

Pre-launch testing proves the agent worked on the day you shipped it (my checklist for that is in How to Test a Voice AI Agent Before Go-Live). Production is different, because the world around the agent keeps moving:

Credentials expire. OAuth tokens for calendars and CRMs get revoked or rotated when someone at the client changes a password.
The business changes without telling you. New hours, a new service, a staff member who left. The prompt is now wrong and nothing errors.
Integrations fail silently. A workflow throws on a field that changed shape, and the agent still tells the caller "you are all booked."
Vendors have incidents. You sit on top of Retell, a telephony provider and a model provider.
Your own edits break things. A prompt change for one branch shifts behavior in another.

None of these stop the phone ringing. That is what makes them dangerous.

Layer 1: is the line answering at all?

The loud failure: calls ring out, drop on connect, or end in an error. Rare, and the one clients never forgive.

Heartbeat call. Once or a few times a day, place an automated test call to each production number from a separate number. Check that it connects, the agent greets within a normal window, and the call ends cleanly. A small scheduled workflow (n8n, a cron job, anything) plus a Twilio number does it. Alert after two consecutive failures, not one.

Volume floor. Every client has a rhythm. Compare today's call count against the same weekday's average and alert when it falls far below during business hours. Zero calls by noon at a busy office is usually a forwarding change on the client side, not an AI problem, but it is still yours to catch.

Disconnection reasons. Every Retell call records a disconnection_reason, available in Call History and on the Get Call API. Retell's disconnection table splits them roughly into three buckets:

expected (call_status = ended)
  user_hangup, agent_hangup, call_transfer, voicemail_reached,
  inactivity, max_duration_reached, user_requested_dnc ...

not connected (outbound)
  dial_busy, dial_no_answer, dial_failed, invalid_destination,
  marked_as_spam, network_blocked ...

errors (call_status = error)
  concurrency_limit_reached, error_llm_websocket_*, error_asr,
  error_no_audio_received, error_retell, error_unknown ...

Log the field for every call and alert on any spike in the error bucket. Two details worth knowing from the docs: dial_failed is also what you see when carriers have flagged your outbound number as spam after many short calls, and the error_llm_websocket_* family only appears when you run a custom LLM over Retell's websocket.

Layer 2: are tools and integrations working?

The quiet failure, and in my experience the most common one. The conversation sounds perfect; the booking, CRM update or follow-up text never happens.

Log every tool call and its result. Whether the agent calls your endpoint directly or goes through a workflow tool, record the request, response, status and latency, keyed by call_id. If tool results are not logged you cannot see this failure at all.

Give every workflow an error branch. Every workflow the agent depends on needs an error path that alerts with the client name, the workflow and the failing step.

Make the agent honest about failure. The prompt should say exactly what to do when a tool returns an error: apologise, take the caller's details, promise a callback, flag the call. It must never confirm a booking that did not go through. A caller who gets a callback is fine; a caller who shows up for an appointment that does not exist is a complaint.

Reconcile against the source of truth. Once a day, compare calls marked booked against bookings that actually landed in the client's calendar or CRM:

// nightly reconcile, per client
const booked = calls.filter(c => c.call_analysis?.custom_analysis_data?.outcome === "booked");
const landed = await calendar.listEventsCreatedBetween(start, end, { source: "voice-agent" });
if (booked.length !== landed.length) {
  alert(`${client.name}: ${booked.length} calls say booked, ${landed.length} bookings exist`);
}

The outcome field here is whatever you defined in post-call analysis; the calendar call is your own integration.

Layer 3: is conversation quality holding?

Some failures are not errors. The agent answers, the tools work, and it still handles callers badly because the business changed or an edge case became common.

Post-call analysis as the quality signal. Extract a structured outcome for every call (booked, answered question, transferred, message taken, spam) plus a flag for a frustrated caller or a request for a human. Track the rates per client week over week. A jump in transfers or frustrated callers means the prompt no longer matches reality.

A weekly transcript sample. Numbers tell you something changed; transcripts tell you what. Skim a handful of calls per client each week, weighted toward transfers, very short calls and anything flagged frustrated.

Latency, per component. After a call ends, Get Call returns a latency object with p50, p90, p95, p99, min, max for components such as e2e, llm, tts, asr and knowledge_base (not every field is present on every call). Store e2e.p90 per call and watch its trend. If it creeps up, the breakdown tells you whether it is the model, the voice or retrieval. Note that e2e excludes turns where the agent only ran a tool without speaking, so slow tools need their own timing from your logs.

Layer 4: is usage behaving normally?

Usage anomalies are both a cost problem and a symptom:

Average duration spiking often means the agent is stuck in a loop, or robocalls are getting long conversations.
Very short calls climbing can mean callers hang up on a bad greeting or a slow first response.
Minutes running past the client's bundle is a margin problem you want to see mid-month, not on the invoice.

Set a maximum call duration on every agent (it ends calls with max_duration_reached), then alert when a client's daily minutes run well above normal.

Retell alert rules: the built-in layer

Retell has alert rules that evaluate aggregate metrics on a schedule and send an email or a webhook when a threshold is crossed. Metrics include call_count, call_success_rate, negative_sentiment_rate, custom_function_latency, custom_function_failure_count, transfer_call_failure_count, concurrency_used, total_call_cost and api_error_count. Rules can be absolute ("success rate below 90% over the last hour") or relative to the previous cycle, and can be filtered by agent, environment tag, disconnection reason or post-call extraction field.

Two constraints shape how you use them:

Rules are dashboard-only. They are created in the dashboard, not through the public API, so if you manage many client workspaces, budget time to set them up per workspace and keep a written list of what exists where.
They are aggregate, not per call. For "this specific call failed a booking", use your own webhook handler. A sensible split: Retell rules for volume, success rate, function failures and cost; your own code for heartbeats, reconciliation and anything that needs client-specific logic.

Plan the failover before you need it

Monitoring tells you something broke; failover decides how much it costs.

Backup mode. In Retell, each phone number can have a fallback number. With Backup mode turned on, new inbound calls go straight to that fallback before an agent is selected, which is your kill switch while you investigate. Configure the fallback number at launch; Backup mode cannot be enabled until one exists, and if the fallback cannot be reached the call ends.
A human transfer path for when the agent is confused, tested as part of every release.
A written commitment in the client contract: you monitor and respond within a defined window, and upstream vendor outages are excluded from credits. Subscribe to Retell's status page so you know about their incidents as early as they do.

Route alerts so someone actually sees them

The fastest way to kill a monitoring setup is noise. If every short call pings your phone, you will mute the channel within a week and miss the one that mattered.

One channel, with the client name in every message.
Only alert on things you would act on: failed heartbeat, workflow error, volume far below normal, error disconnections, a booked count that does not reconcile, a Retell rule firing. Everything else goes into a daily digest.
Tell the client before they tell you: what happened, when it started, what you did and which calls were affected. Handled like that, an incident builds trust instead of eroding it.

The bottom line

The agent that worked on launch day is not the agent that is answering today, because everything around it changed. Watch the line, the tools, the quality and the usage; put disconnection_reason, latency and your post-call outcome on every call record; let Retell's alert rules cover the aggregates; and set the fallback number before the first incident, not during it.

Drafted with AI assistance and fact-checked against each vendor's docs.

Storing Retell Call Recordings for Client Portals: Expiring Links, Retention and Per-Tenant Access

Nabeel Hassan — Sun, 25 Oct 2026 10:43:20 +0000

Disclosure: I'm Nabeel, founder of VoiceDash, a client portal for Retell agencies. This post is about the plumbing, not the product, and every Retell behaviour below is taken from Retell's own docs (linked inline).

TL;DR: Retell recording URLs do not expire unless you opt in to secure URLs, and Retell keeps call data forever unless you set a retention period. If you show recordings to clients in your own portal, decide up front whether you proxy Retell's links or copy the audio into your own storage, scope every lookup by tenant, and make your retention match (or beat) the one you configured in Retell.

What Retell actually gives you

A finished call object (from the Get Call API or the call_ended / call_analyzed webhooks) carries up to four audio links:

recording_url: the mixed recording
recording_multi_channel_url: each party on its own channel
scrubbed_recording_url and scrubbed_recording_multi_channel_url: the same audio with PII intervals beeped out, when the agent uses the "Everything except PII" storage mode

There is also public_log_url, which deserves the same care as the audio.

Two agent-level settings decide how risky those links are: secure URLs and data retention. Both are off by default.

Problem 1: by default the links never expire

Retell's secure URL page is explicit: generated URLs for recordings and logs do not expire unless you opt in. If one of those links lands in a client's inbox, a CRM note or a support ticket, anyone holding it can play the call.

Opting in is per agent:

{
  "opt_in_signed_url": true,
  "signed_url_expiration_ms": 3600000
}

Leave signed_url_expiration_ms unset and you get 24 hours. The allowed range is 1 minute to 7 days.

Two details matter when you turn this on for an agent that already has history:

Files created before you opted in keep generating unsigned, non-expiring URLs.
If you later opt out, files created while the setting was on keep their signed behaviour; only new files go back to permanent links.

So "we enabled secure URLs" is not the same as "every recording link we have stored is now safe". Any URL you already persisted in a database or pushed to a CRM is still live. Treat stored Retell URLs as secrets, and plan to stop storing them at all (next section).

Problem 2: proxy or copy?

Once a client can log into your portal, you have two sane designs.

Proxy (store nothing, ask Retell each time). Your portal stores only call_id and tenant_id. When an authorised user presses play, your server calls Get Call, reads the fresh signed URL and redirects. With secure URLs on, Retell signs a new URL each time you request it, so a short expiry (5 to 15 minutes) works well. Upside: no audio storage, one source of truth. Downside: Retell's retention is now your retention, and every play is an API call.

Copy (own the audio). On call_analyzed, download the file and put it in your own bucket under a tenant prefix. Your portal mints its own short-lived links. Upside: you control retention, region and access logs, and Retell can be set to a short retention. Downside: you are now the one holding call audio, with everything that implies for consent and deletion requests.

You must copy if the agent uses "Everything except PII" or "Basic Attributes Only". The webhook docs say Retell deletes the raw recording, transcript and log files about 10 minutes after post-call processing ends, shortly after call_analyzed. The webhook still carries the full unscrubbed data, so it is your one window to grab it, and your one chance to decide whether you should keep the raw file or only the scrubbed one.

The ingestion handler

The copy design lives or dies in the webhook handler. Retell gives you three constraints worth designing around:

Verify X-Retell-Signature against the raw body, not re-serialised JSON (secure webhook docs). Only the API key with the webhook badge verifies.
The webhook times out after 10 seconds and is retried up to 3 times without a 2xx, so the same event can arrive more than once. Retell's own guidance is to key idempotency on event + call_id.
Acknowledge fast. Downloading a long WAV inside the request is how you earn duplicate deliveries.

import { Retell } from "retell-sdk";
import express from "express";

const app = express();
app.use(express.raw({ type: "application/json" }));

app.post("/retell/webhook", async (req, res) => {
  const raw = req.body.toString("utf-8");
  const sig = req.headers["x-retell-signature"];
  if (typeof sig !== "string" ||
      !(await Retell.verify(raw, process.env.RETELL_WEBHOOK_KEY!, sig))) {
    return res.status(401).end();
  }

  const { event, call } = JSON.parse(raw);
  if (event === "call_analyzed") {
    // Unique (event, call_id) row makes retries a no-op.
    const inserted = await db.webhookEvents.insertIfAbsent({
      event, call_id: call.call_id, received_at: new Date(),
    });
    if (inserted) {
      await queue.send("copy-recording", {
        call_id: call.call_id,
        agent_id: call.agent_id,
        url: call.scrubbed_recording_url ?? call.recording_url,
      });
    }
  }
  res.status(204).end();
});

The worker resolves agent_id to a tenant from your own table (never from anything the caller said), streams the file into s3://recordings/{tenant_id}/{call_id}.wav, and records the object key. Because of the 10-minute deletion window on the stricter storage modes, alert if the queue for this job backs up past a few minutes.

Choosing the scrubbed URL when it exists is a policy decision, not a technical one. For most client portals the scrubbed version is what a business owner should hear; keep the raw one only if the client has a documented reason and the consent to back it.

A schema that makes cross-tenant leaks hard

create table call_recordings (
  call_id       text primary key,
  tenant_id     uuid not null references tenants(id),
  agent_id      text not null,
  object_key    text,            -- null in the proxy design
  is_scrubbed   boolean not null,
  started_at    timestamptz not null,
  delete_after  timestamptz not null
);
create index on call_recordings (tenant_id, started_at desc);

Every read goes through one function that takes the session's tenant_id and the call_id and filters on both. If you use Postgres row-level security, put the policy on this table first: it holds the most sensitive rows in the system.

The playback endpoint then does three things in order: load the row with tenant_id from the session, write an access log line (who, which call, when), and return a link that expires in minutes. With the AWS SDK that last step is getSignedUrl(s3, new GetObjectCommand({ Bucket, Key }), { expiresIn: 600 }). Never put the object key or a Retell URL in the HTML that lists calls; mint the link only when someone presses play.

Retention: pick one number and make both systems obey it

Retell's data retention policy is per agent, set with data_storage_retention_days (1 to 730, or null for keep forever, the default). The dropdown offers 1, 3, 7, 30, 60, 90, 180, 365 and 730 days. Deletion runs daily and is permanent: recordings, transcripts, logs, dynamic variables and metadata go, and the call stops appearing in API responses.

That creates two failure modes:

Proxy design with retention on: the portal shows a call row whose recording silently 404s on day 91. Store delete_after and hide or label expired calls.
Copy design with retention on in Retell only: Retell deletes on day 30, your bucket keeps the file forever, and your client's "we keep recordings for 30 days" promise is false. Add a bucket lifecycle rule and a daily job that deletes rows past delete_after.

Which number to choose depends on the client's industry and the states their callers are in. That is a legal question, not an engineering one; I cover the consent side in Voice AI Call Recording Consent and AI Disclosure: The Compliance Checklist I Run for US Clients.

Checklist before a client sees a single recording

Secure URLs on for every client agent, with an expiry you can justify.
Old, unsigned URLs purged from your database, CRM notes and automations.
Proxy or copy decided per agent, and copy enforced for "Everything except PII" and "Basic Attributes Only" agents.
Webhook verified on the raw body, idempotent on event + call_id, acknowledged before the download.
agent_id to tenant_id mapping owned by you, checked on every read.
Playback links minted on click, expiring in minutes, with an access log.
One retention number per client, applied in Retell and in your own storage.

None of this is visible to the client when it works. It becomes very visible the first time a recording link travels further than it should.

Drafted with AI assistance and fact-checked against each vendor's docs.

Retell AI for Agencies: One Account or One Per Client? How to Structure Accounts, Keys and Phone Numbers

Nabeel Hassan — Tue, 20 Oct 2026 10:44:35 +0000

Disclosure: I'm Nabeel, founder of VoiceDash, a client portal for Retell agencies. This post is about account design, not the product.

If you build Retell AI agents for more than one business, you hit a design question long before you hit a scaling problem: does every client live in one Retell account, or does each client get their own? It looks like a billing choice. It is really a tenancy choice, and it decides how you attribute cost, how far a leaked API key can reach, who owns the phone numbers, and how messy offboarding gets.

TL;DR: run one agency account for clients on a managed retainer, where you carry the usage and bill a flat fee, and use a client-owned account only when the client insists on owning the vendor relationship, works in a regulated industry that wants its own agreements, or is big enough to want its own billing. Whichever you pick, decide four things up front: who pays Retell, who owns the numbers, how agents are named and tagged per client, and what the client gets to see. I build production voice agents for US clients on Retell, n8n, GoHighLevel and Twilio. Here is how I structure it.

Why account structure matters more than it looks

Nobody thinks about account structure on client one. You sign up for Retell, build an agent, buy a number, and ship. By client five you have a single account holding five businesses' agents, numbers, recordings and transcripts, all paid for on your card, all reachable with one API key.

That setup creates four real problems as you grow:

Cost attribution. Retell bills per minute, and the bill arrives as one number. If you cannot split minutes by client, you cannot tell which retainer is profitable.
Access and data isolation. Anyone with access to the account, a contractor or a new hire, can see every client's calls. Clients themselves can never be given that login.
Ownership disputes. When a client leaves, the question "whose phone number is this and who keeps the recordings" needs an answer you agreed in writing, not one you invent on the day.
Blast radius. A failed payment, a leaked key or a rate limit on one account touches every client at once.

None of this means one account is wrong. It means one account needs rules.

Option 1: One agency account for all clients

This is what most agencies run, and what I recommend for the managed retainer model.

How it works. You own the Retell account and the payment method. Every client's agents live in it. You pay Retell for all minutes and charge each client a flat monthly retainer that covers usage up to an agreed level.

Why it works.

One place to build, test and update every agent, which matters when you roll the same fix across ten clients.
One integration setup for n8n, GoHighLevel or your own middleware.
Your margin stays private. The client sees what their agent did, not what it cost you.
Onboarding is fast because nothing new has to be created on the client's side.

What it needs to stay sane.

A strict naming convention. I prefix every agent with the client code, for example ACME-receptionist-v3, so nothing is ambiguous in logs, webhooks or reports.
Per-client metadata on every call, passed in from the phone number or the agent, so post-call data can be split by client. Retell's call metadata and post-call analysis are what make this reliable; I wrote up the fields I use in Retell AI Post-Call Analysis: The Fields I Set Up on Every Client Agent.
Usage tracked per client every month, even if you bill flat, so you notice when one client's volume quietly eats the margin.
A client-facing layer that is not the Retell dashboard. Clients must never log into the shared account. More on that below.

Option 2: A separate Retell account per client

How it works. Each client has their own Retell account, usually with their own card on it. You get access to build and maintain the agent, and the client pays Retell directly for minutes. You charge a management fee on top.

When I use it.

The client wants to own the vendor relationship. Some owners, especially those who have been burned by an agency before, want the account, the card and the data in their own name.
Regulated industries. A medical practice or law firm may want its own agreements with each vendor rather than routing through yours.
High or unpredictable volume. Outbound campaigns and large multi-location groups can swing usage enough that carrying it on your card is a real cash flow risk.
The client plans to take it in-house eventually, and you are being paid to build and hand over.

The costs. Every client account means a separate setup, separate API keys to manage, separate webhook configuration and separate places to check when something breaks. Updates that take minutes across one account become a checklist across ten. You also lose the clean flat retainer, because the client now sees the raw per-minute bill and will compare it to your fee.

The hybrid I actually run

In practice I end up with a mix:

Managed retainer clients live in the agency account. That is the majority.
Clients who insist on ownership or need their own agreements get their own account, and I document my access in the contract.
Pilots always start in the agency account, so I can test fast without asking a prospect for a card. If the client converts and wants their own account, migrating the agent is a planned step, not a surprise.

The rule that makes the hybrid work is writing the choice down at onboarding, in the same intake where you collect hours, services and escalation contacts.

Phone numbers: decide ownership before you buy one

Phone numbers cause more offboarding fights than anything else, so I treat them separately from the account question.

Numbers bought inside the agency account belong to the agency account. If the client prints that number on their trucks, you have created a dependency they did not agree to.
The client's main business line should stay theirs. Forward to the agent or route through a carrier the client controls, rather than porting their main number into your account.
Tracking or campaign numbers you buy for a client should have a written rule: they port to the client on exit, or they are released.

Recordings, transcripts and offboarding

Call data lives where the account lives. In a single agency account, every client's recordings and transcripts sit in your account, which is good for support and bad if you have not agreed retention and export rules.

What I put in writing for every client, whichever structure:

How long recordings and transcripts are kept, and who decides.
What the client receives when they leave: an export of their call history, their prompt and configuration if the contract says so, and their numbers ported or released.
How quickly you delete their data from the agency account after exit.

Offboarding cleanly is also a sales point. Telling a prospect exactly how they can leave makes them more comfortable signing.

API keys and access hygiene

A shared account is only as safe as its access rules.

Keep the key server side. Never put a Retell API key in a client-facing tool, a shared spreadsheet or a no-code step that clients can open.
Limit who can log in. Contractors get access for the work they are doing, and lose it when they finish.
Rotate keys when someone leaves or a key may have been exposed, and know in advance which integrations will break when you do.
Monitor all clients, not just the loud ones. One account means one place to watch for failed calls.

What the client sees: never the raw account

Whichever structure you choose, the client should not be working inside Retell. Retell's dashboard is built for builders: agents, prompts, settings, and in a shared account, every other client's calls. Even in a client-owned account, the raw dashboard shows cost and configuration the owner does not need to see.

So the client-facing layer is a separate, tenant-scoped read model: calls synced from the API or webhooks, keyed by the client identifier you put in metadata or the agent prefix, and every query filtered by that tenant before anything renders. Whether you build that yourself or use an off-the-shelf portal, the account design above is what makes it possible. If agent names and call metadata are not consistent, no reporting layer can split the data cleanly afterwards.

The account structure checklist

Default structure chosen: agency account for managed retainers, client account by exception
Reason for any client-owned account written into the contract
Agent naming convention with a client prefix, applied to every agent
Client identifier passed into every call for usage and reporting splits
Monthly usage reviewed per client, even on flat pricing
Phone number ownership and exit rule agreed before buying any number
Recording retention, export and deletion terms in writing
API keys server side only, access limited, rotation plan known
Monitoring covering every client in the account
A scoped client view in place, so no client ever logs into Retell

The bottom line

Structure your Retell setup on purpose before client five forces it on you. One agency account is the right default for a managed voice AI agency because it keeps building fast and your margin private, as long as you name agents by client, split usage by client, agree ownership of numbers and data up front, and give every client their own scoped view instead of the raw account. Use client-owned accounts when ownership, regulation or volume genuinely call for it, and write that choice down.

Drafted with AI assistance and fact-checked against each vendor's docs.

Retell Post-Call Analysis: Designing Fields That Turn Calls Into Client KPIs

Nabeel Hassan — Fri, 16 Oct 2026 11:16:21 +0000

Disclosure: I'm Nabeel, founder of VoiceDash, a client portal for Retell AI agencies. This post is about the Retell API itself and works with any stack.

TL;DR: Retell's post-call analysis turns each transcript into structured data, but only if you design the fields like a schema, not a wish list. Listen for call_analyzed (not call_ended), give every custom field a narrow type and a precise description, and store the result in a table you can aggregate per client. Then the monthly numbers a client sees are just queries.

What Retell actually gives you after a call

When a call finishes, Retell sends webhook events in order. Two matter here:

call_ended: every field of the call object except call_analysis.
call_analyzed: the full call data including call_analysis.

If your pipeline writes KPIs on call_ended, it will see an empty analysis and count nothing. Write the raw call on call_ended if you want it early, then upsert the analysis on call_analyzed.

The call_analysis object (per the Get Call API reference) contains:

Field	Type	Notes
`call_summary`	string	A short summary of the call
`in_voicemail`	boolean	Whether the call reached voicemail
`user_sentiment`	enum	`Positive`, `Neutral`, `Negative`, `Unknown`
`call_successful`	boolean	Whether the agent appears to have finished its task
`custom_analysis_data`	object	Your own fields, extracted from the transcript. Can be empty.

Alongside it, the call object carries the fields you need for reporting: agent_id, start_timestamp and end_timestamp (ms since epoch), duration_ms, disconnection_reason, recording_url, metadata, retell_llm_dynamic_variables and call_cost.

Treat the built-in fields with care

The built-ins are useful, but they answer generic questions.

call_successful means "the agent seems to have completed its task". It does not know that your client counts success as "appointment booked". Do not show it to a client as a success rate.
user_sentiment is a model's read of tone. Fine as a filter for which calls a human should review, weak as a headline number.
in_voicemail is the one to use for outbound campaigns: exclude voicemail calls from any conversion rate, or the rate will look much worse than the conversations really were.
call_summary belongs in a call list, not in a KPI.

Client-facing KPIs should come from custom fields you define.

Designing custom fields as a schema

In the agent's post-call analysis settings, each custom field has a name, a description and a format example, and one of four types: Text, Selector, Boolean, Number. The description is effectively a prompt for extraction, so write it as a definition with an explicit rule for edge cases.

A set that covers most receptionist agents:

appointment_booked (Boolean)
  True only if the caller confirmed a specific date and time and the
  booking tool returned success during this call. False if the caller
  only asked about availability.

call_intent (Selector: new_booking, reschedule, cancel, question, sales_lead, spam, other)
  The single main reason for the call. If several apply, pick the one
  the caller raised first.

lead_quality (Selector: hot, warm, cold, not_a_lead)
  hot = asked for a booking or a quote for a service the business offers.

escalated_to_human (Boolean)
  True if the call was transferred or a callback by staff was promised.

callback_number (Text)
  The number the caller asked to be called back on, in E.164 format.
  Empty if none was given.

estimated_job_value (Number)
  Only if the caller stated a budget or a price was quoted from the
  approved price list. Otherwise leave empty. Never guess.

Rules that keep extraction reliable:

Prefer Selector and Boolean over Text. You can group by an enum; you cannot group by free text.
Define the negative case. "False if the caller only asked about availability" prevents the most common false positive.
One question per field. A field like outcome_and_next_step produces prose you cannot aggregate.
Allow empty. For numbers especially, an explicit "leave empty" beats a hallucinated value in a revenue chart.
Version the schema. When you change a description, record the date. KPI trends across a definition change are not comparable.

Receiving `call_analyzed` safely

Retell signs each webhook with the x-retell-signature header. Verify it against the raw request body with the SDK; a re-serialized JSON object will not match. Retell waits 10 seconds for a 2xx and retries up to 3 times, so acknowledge fast and make the write idempotent.

import express from "express";
import Retell from "retell-sdk";

const app = express();

app.post(
  "/webhooks/retell",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const raw = req.body.toString("utf8");
    const signature = req.header("x-retell-signature") ?? "";

    if (!Retell.verify(raw, process.env.RETELL_API_KEY!, signature)) {
      return res.status(401).end();
    }

    const { event, call } = JSON.parse(raw);
    res.status(204).end(); // acknowledge inside the 10s window

    if (event === "call_analyzed") {
      await upsertAnalysis(call); // idempotent on call.call_id
    }
  }
);

If you run several clients on one Retell account, decide how a call maps to a client before it happens. Two common options: a lookup table from agent_id to client, or a client_id you put in metadata when you create outbound calls. Never trust a client identifier taken from the transcript.

A table you can aggregate

Flatten the analysis into columns. JSON blobs are fine for the raw payload, but reporting queries should hit typed columns.

create table call_analysis (
  call_id            text primary key,
  client_id          text not null,
  agent_id           text not null,
  started_at         timestamptz not null,
  duration_ms        integer,
  disconnection_reason text,
  in_voicemail       boolean,
  user_sentiment     text,
  call_successful    boolean,
  appointment_booked boolean,
  call_intent        text,
  lead_quality       text,
  escalated_to_human boolean,
  estimated_job_value numeric,
  schema_version     integer not null,
  raw                jsonb not null
);

create index on call_analysis (client_id, started_at);

async function upsertAnalysis(call: any) {
  const a = call.call_analysis ?? {};
  const c = a.custom_analysis_data ?? {};
  await db.query(
    `insert into call_analysis (call_id, client_id, agent_id, started_at,
       duration_ms, disconnection_reason, in_voicemail, user_sentiment,
       call_successful, appointment_booked, call_intent, lead_quality,
       escalated_to_human, estimated_job_value, schema_version, raw)
     values ($1,$2,$3,to_timestamp($4/1000.0),$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16)
     on conflict (call_id) do update set
       appointment_booked = excluded.appointment_booked,
       call_intent = excluded.call_intent,
       lead_quality = excluded.lead_quality,
       raw = excluded.raw`,
    [call.call_id, clientFor(call), call.agent_id, call.start_timestamp,
     call.duration_ms, call.disconnection_reason, a.in_voicemail ?? null,
     a.user_sentiment ?? null, a.call_successful ?? null,
     c.appointment_booked ?? null, c.call_intent ?? null,
     c.lead_quality ?? null, c.escalated_to_human ?? null,
     c.estimated_job_value ?? null, SCHEMA_VERSION, call]
  );
}

The on conflict clause matters: a retried webhook must not create a second row.

From rows to client KPIs

Once the columns exist, a month of reporting is a handful of queries:

select
  count(*) filter (where call_intent <> 'spam')                    as real_calls,
  count(*) filter (where appointment_booked)                       as bookings,
  round(100.0 * count(*) filter (where appointment_booked)
        / nullif(count(*) filter (where call_intent in ('new_booking','reschedule')), 0), 1)
                                                                   as booking_rate_pct,
  count(*) filter (where escalated_to_human)                       as handed_to_staff,
  count(*) filter (where extract(hour from started_at at time zone 'America/New_York')
                   not between 9 and 16)                           as after_hours_calls
from call_analysis
where client_id = $1
  and started_at >= date_trunc('month', now() - interval '1 month')
  and started_at <  date_trunc('month', now());

Note the denominators: spam is excluded from call counts, and the booking rate divides by calls that wanted a booking, not by every call. Use the client's own time zone for anything hour based.

Test the extraction before a client relies on it

Analysis fields are model output, so test them like model output:

Make a set of 15 to 20 test calls that cover each call_intent value plus awkward cases: a caller who asks about times and hangs up, a reschedule that becomes a cancel, a spam call.
Write down the expected value of every field for each call before you look at the results.
Compare. Any field that is wrong more than once gets a sharper description, then re-run the set.
Spot check a few real calls each week after launch, sorted by user_sentiment = 'Negative' first.

Checklist

[ ] KPIs written on call_analyzed, not call_ended
[ ] Signature verified on the raw body
[ ] Idempotent upsert keyed on call_id
[ ] Every custom field has a type, a definition and a negative case
[ ] Client mapping from agent_id or metadata, never from the transcript
[ ] Spam and voicemail excluded from rates
[ ] Schema version stored with every row

References: Retell docs on post-call analysis, webhooks and the Get Call API.

Drafted with AI assistance and fact-checked against each vendor's docs.

DEV Community: VoiceDash

Monitoring Retell Voice Agents in Production: Alert Rules, Disconnection Reasons and the Failures Transcripts Hide

Why testing is not enough

Layer 1: is the line answering at all?

Layer 2: are tools and integrations working?

Layer 3: is conversation quality holding?

Layer 4: is usage behaving normally?

Retell alert rules: the built-in layer

Plan the failover before you need it

Route alerts so someone actually sees them

The bottom line

Storing Retell Call Recordings for Client Portals: Expiring Links, Retention and Per-Tenant Access

What Retell actually gives you

Problem 1: by default the links never expire

Problem 2: proxy or copy?

The ingestion handler

A schema that makes cross-tenant leaks hard

Retention: pick one number and make both systems obey it

Checklist before a client sees a single recording

Retell AI for Agencies: One Account or One Per Client? How to Structure Accounts, Keys and Phone Numbers

Why account structure matters more than it looks

Option 1: One agency account for all clients

Option 2: A separate Retell account per client

The hybrid I actually run

Phone numbers: decide ownership before you buy one

Recordings, transcripts and offboarding

API keys and access hygiene

What the client sees: never the raw account

The account structure checklist

The bottom line

Retell Post-Call Analysis: Designing Fields That Turn Calls Into Client KPIs

What Retell actually gives you after a call

Treat the built-in fields with care

Designing custom fields as a schema

Receiving call_analyzed safely

A table you can aggregate

From rows to client KPIs

Test the extraction before a client relies on it

Checklist

Receiving `call_analyzed` safely