Blog · November 19, 2026 · 8 min read

Retell AI Disconnection Reasons: Why Your Voice AI Calls End and What Each One Means for Clients (2026)

By Nabeel Hassan — builder of VoiceDash

Retell AI Disconnection Reasons: Why Your Voice AI Calls End and What Each One Means for Clients (2026)

TL;DR: Every Retell AI call carries a disconnection reason, the field that says why the call ended. Most agencies never look at it, and that is a mistake. It tells you whether the caller hung up, the agent ended the call on purpose, the call was transferred, a voicemail was reached, the line went silent, a limit was hit, or something broke. Group the reasons into five buckets (normal, transfer, voicemail and dial outcomes, limits, errors), alert on the error and limit buckets, and translate the rest into plain outcomes your clients can read. I build production voice agents for US clients on Retell, n8n, GoHighLevel and Twilio, and we run VoiceDash, the white-label client portal agencies hand their clients. This is how I read the field and what I do with it.

A client rarely asks "what was the disconnection reason on call 4,312?" They ask "why did the AI hang up on my customer?" The disconnection reason is how you answer that question in thirty seconds instead of thirty minutes, and how you catch problems before the client ever notices them.

Where the disconnection reason lives

When a Retell call ends, the call object includes a disconnection_reason field alongside the transcript, timing and phone numbers. You can read it three ways:

  • In the Retell dashboard, on the call detail view.
  • In the call_ended and call_analyzed webhooks, which deliver the call object to your endpoint. The setup is covered in Retell AI webhooks.
  • Through the API, when you list or fetch calls.

Retell adds and renames values as the platform evolves, so treat the list below as a field guide, not a contract. Check the current API reference before you hard-code anything, and always write a fallback branch for values you have not seen yet.

The five buckets I sort every reason into

Raw reason codes are too granular for a client and too noisy for an alert. I map them into five buckets, then decide what to do with each bucket.

1. Normal endings

These are the ones you want to see most of the time.

  • user_hangup: the caller ended the call. On most inbound agents this is the single most common reason, and it is usually fine. The caller got what they needed and hung up.
  • agent_hangup: the agent ended the call, typically through an end call function after the conversation reached a natural close.

What to watch: the ratio and the timing. A healthy inbound agent shows mostly user hangups after a real conversation. A spike in user hangups within the first few seconds means callers are bailing on the greeting, which points at latency, a robotic opening line, or a bad voice choice. I covered the fixes in how to reduce voice AI latency and the best voice for an AI receptionist.

A spike in agent hangups mid-conversation is the opposite problem: the prompt is ending calls too eagerly. I have seen agents hang up on "thanks, that's helpful" when the caller still had a second question. Tighten the end call condition so the agent asks "is there anything else?" before it closes.

2. Transfers

  • call_transfer: the agent handed the call to a human or another number.

What to watch: transfers are a feature, not a failure, but the rate tells a story. A receptionist agent that transfers 60 percent of calls is a very expensive phone tree. A rising transfer rate after a prompt change usually means the agent lost confidence on a topic it used to handle. Pair this reason with the transcript to see which questions trigger it. My rules for when a transfer should happen are in voice AI call transfer to a human.

3. Voicemail and dial outcomes (outbound)

On outbound campaigns, many calls never reach a person at all.

  • voicemail_reached or a machine-detected value: the call hit an answering machine. What happens next depends on your voicemail setting.
  • Dial outcomes such as no answer, busy, or a failed dial: the call never connected to anything useful.

What to watch: these must never be counted as conversations. If a reactivation campaign shows 1,000 calls and 30 bookings, the client reads a 3 percent conversion rate and panics. If 600 of those calls were voicemails and no-answers, the real rate on connected calls is 7.5 percent, a very different story. The voicemail setup is in Retell AI voicemail detection.

4. Limits and timeouts

  • inactivity: nobody said anything for too long and the call was ended. Often a pocket dial, a dropped connection on the caller's side, or a caller who walked away.
  • max_duration_reached: the call hit the maximum length you configured.
  • Concurrency limit reached: more simultaneous calls came in than your account allows.
  • Payment or account issues: the account could not take the call.

What to watch: these are configuration problems wearing a disguise. Inactivity endings on inbound calls in clusters can mean audio is not reaching the agent at all, which is an error in practice. Max duration endings mean either your cap is too low for the use case or the agent is looping. And a concurrency limit ending is the worst kind of failure: a real customer called during a busy hour and got nothing. If you see even one, read Retell AI concurrent calls and raise the limit before the next Monday morning rush.

5. Errors

Retell has a family of error reasons, things like failures in the LLM connection, telephony provider errors, no audio received, speech recognition errors, inbound webhook errors, and unknown errors. If you run a custom LLM over websocket, there are several specific websocket error values too.

What to watch: all of them. A single error is noise. Three in an hour is an incident. Any error bucket ending should trigger an alert to the agency, not the client. The usual suspects, in the order I check them:

  1. Your own endpoints. If the agent calls a custom function or an inbound webhook and your server is slow or down, calls fail. Check n8n execution logs or your server logs first. Patterns for keeping those endpoints fast are in Retell AI custom functions.
  2. Phone number setup. Telephony errors after a number port or a SIP change usually trace back to configuration. See voice AI phone number setup.
  3. The platform. Check Retell's status page before you spend an hour debugging your own stack.

Turn reasons into alerts, not just logs

Reading the field once a month does nothing. Here is the minimum setup I run on every production agent:

Bucket Alert? Who sees it
Normal endings No, but track the early hangup rate weekly Agency
Transfers Weekly rate check Agency, and the client sees transfer counts
Voicemail and dial outcomes No Client sees them as outcomes, separated from conversations
Limits and timeouts Yes, any concurrency or payment ending Agency, immediately
Errors Yes, more than two per hour per agent Agency, immediately

In practice this is one n8n workflow: the call_ended webhook comes in, a switch node maps the reason to a bucket, a counter tracks errors per agent per hour, and anything over threshold posts to Slack or sends an SMS to whoever is on call. It takes an afternoon to build and it has saved me from finding out about outages from an angry client. The broader monitoring setup is in voice AI agent monitoring.

Translating reasons for clients

Clients should never see error_llm_websocket_runtime. They should see an outcome that makes sense to a business owner. My translation layer looks like this:

Raw reason bucket What the client sees
User hangup after a real conversation Completed
Agent hangup Completed
Call transfer Transferred to your team
Voicemail Voicemail left (or Voicemail, no message)
No answer, busy, failed dial Not reached
Very short user hangup Hung up early
Errors and limits Hidden from the client view, handled by the agency

The last row is a judgment call and you should be honest about it. I do not hide errors to look good. I hide raw error codes because the client cannot act on them, then I tell the client directly when something went wrong and what I fixed. If an outage cost them calls, they hear it from me first, with the count, before they spot it themselves. That conversation goes much better than the reverse, and it fits into the regular reporting I describe in voice AI client reporting.

Common patterns and what they usually mean

A few combinations I see over and over:

  • Lots of user hangups under ten seconds: greeting is too long, too slow, or too obviously robotic. Test the first five seconds of the call ten times in a row.
  • Agent hangups right after a question: the end call condition is too loose. Make the agent confirm there is nothing else before ending.
  • Inactivity clusters at night: often spam or robocalls hitting the line. See voice AI spam calls.
  • Max duration on a booking agent: the agent is stuck in a loop, usually re-asking for a date or a phone number it already has. Read the transcript, then fix the prompt or the function response.
  • Errors right after a deploy: roll back first, investigate second. My release process is in how to update a live voice AI agent.

Where VoiceDash fits

Disconnection reasons are only useful if the people who need them can see the calls behind them. Your team needs the raw detail. Your client needs recordings, transcripts and clean outcomes, on a page that does not say Retell anywhere.

That is why we run VoiceDash. It connects to your Retell account once, then syncs agents, calls, recordings and transcripts into a white-label portal with your logo, on your own domain. Each client is an isolated workspace with its own login and team access, so they only ever see their own calls, volume, outcomes and usage. When a client asks "why did the AI hang up on my customer?", they can open the recording and transcript themselves, and you can answer with the reason in hand. You can also bill clients through your own Stripe account, with VoiceDash taking no cut.

Setup takes under 10 minutes with no code. Plans are Starter, Growth and Ultimate, from $19/mo, and every plan starts with a 7-day free trial. Retell is supported today. VAPI and Bland support are coming soon.

The bottom line

The disconnection reason is the cheapest diagnostic you have. It is already on every call, it costs nothing to read, and it separates "the caller got what they needed" from "your server fell over" without listening to a single recording. Bucket the reasons, alert on errors and limits, keep voicemails and dial failures out of your conversion math, and translate the rest into outcomes your clients understand. Do that and you will catch problems first, explain them clearly, and keep clients who would otherwise quietly decide the AI does not work.

Want your clients to see every call, recording and outcome in a portal on your own domain? Start free on VoiceDash or book a demo and I will show you the setup I use with my own clients.

FAQ

What is the disconnection reason in Retell AI?

It is a field on every Retell call object that records why the call ended, such as the caller hanging up, the agent ending the call, a transfer, a voicemail, an inactivity timeout, a duration or concurrency limit, or an error. You can read it in the Retell dashboard, in the call_ended and call_analyzed webhooks, and through the API.

Which Retell disconnection reasons should an agency alert on?

Errors and limits. Any concurrency limit or payment-related ending means a real caller got nothing, so it should alert immediately. Error endings, such as LLM connection, telephony or webhook failures, should alert when they cluster, for example more than two per hour on one agent. Normal hangups and transfers only need weekly trend checks.

Should clients see raw Retell disconnection reasons?

No. Translate them into plain outcomes like Completed, Transferred to your team, Voicemail and Not reached, and keep raw error codes in the agency view. With VoiceDash, clients sign in to a branded portal on the agency's domain to see their own calls, recordings and transcripts, while the agency handles errors and tells the client directly when something went wrong.

Give your clients a dashboard with your name on it

VoiceDash turns your Retell agents into branded client portals. Live in under 10 minutes, no code.

Keep reading