Hangup cause

A hangup cause is a small code that explains why a call ended. Every time a call stops, Asterisk writes down a reason in the form of a number with a short label. "Normal clearing" means someone simply hung up. Other codes mean the line was busy, the number did not exist, or the network refused the call. For troubleshooting, this code is gold, because it turns a vague "the call dropped" into a specific story you can actually act on instead of guessing.

Some hangup causes you will run into often. A busy code means the far end was on another call. A CONGESTION code usually means the carrier could not complete the call, often a routing or capacity problem on their side rather than yours. A CHANUNAVAILABLE result means the Channel could not even be set up in the first place, which can point at a registration or trunk issue. Learning to recognize three or four of these on sight will save you a lot of time.

Reading the codes

Hangup causes come from a long-standing telephone standard, so the same numbers show up across many systems, not just VICIdial. They are related to but not the same as a SIP response code, which is what the SIP protocol itself returns over the wire. Asterisk maps SIP responses to hangup causes, so a single failed call may show both, and reading them side by side often tells the full story. When you watch live events over AMI (Asterisk Manager Interface), the hangup cause is one of the most useful fields to log and chart over time.

The practical habit to build: when calls fail in clusters, group them by hangup cause first. If most are "normal clearing," people are just hanging up and your routing is fine. If you see a wave of congestion or unavailable channels, the problem is almost certainly your carrier or trunk, not your agents, and you can take it up with the right party armed with evidence.