Introduction
In every Bolna Voice AI conversation, the system records metadata about how and why a call was terminated. This information is critical for debugging, analytics, compliance, and improving user experience across various industries, geographies, and use cases. Each call termination is associated with:hangup_by: Identifies the party or system that initiated the hangup (e.g., caller, callee, system).hangup_code: A numeric code indicating the specific reason for the hangup, typically provided by the telecom provider or API response.hangup_reason: A descriptive reason for the call termination, provided by either Bolna or the telephony provider.
Why Hangup Codes Matter
Understanding hangup statuses and codes helps:- Improve call handling workflows and automation
- Identify systemic or geographic call issues
- Monitor telecom partner reliability (e.g., Plivo, Twilio)
- Pinpoint user-initiated hangups vs system or error-based disconnects
- Enhance regional support (United States, India, Southeast Asia, MENA, etc.)
List of Hangup Statuses and Codes
Below is a detailed list of common call hangup reasons and their associated codes used in Bolna’s Voice AI system:| Hangup by | Hangup Description | Hangup provider code |
|---|---|---|
| API Request | Call was ended by the Bolna agent via an API request | 4000, 4020 |
| Callee | The recipient of the call hung up (applies to outbound calls) | 3020, 4000 |
| Caller | The caller ended the call (applies to inbound calls) | 4000 |
| Carrier | Call was terminated by the telecom carrier | 2000, 3000, 3010, 3020, 3040, 3050, 3070 |
| Error | Call ended due to an unexpected error | 3080, 3090, 3110, 5010, 5020, 7011, 8011 |
| Plivo | The telephony provider (Plivo) disconnected the call | 1010, 4010, 5020, 6000, 6010, 6020 |
| Unknown | Reason for call termination is unknown | 0 |
| (empty) | No hangup reason was recorded | (empty) |
Hangup Reasons
Bolna-Side Hangup Reasons
Bolna provides specific hangup reasons based on agent configuration:inactivity_timeout: Call ended due to silence time threshold being exceededllm_prompted_hangup: Call ended based on custom prompt evaluation
Telephony Provider Hangup Reasons
Hangup reasons may also be provided by the telephony provider. The availability and detail of these reasons depend on the specific telephony provider being used.| Hangup Reason | Description |
|---|---|
Call recipient was busy | Called party was busy |
Call unanswered | Called party did not answer |
Call recipient number invalid | Invalid or unreachable phone number |
Call recipient hungup | Call recipient ended the call |
Carrier declined | Call declined by carrier |
Call recipient rejected | Call was rejected by the called party |
failed | Call could not be initiated |
Carrier ended because call limit exceeded | Call terminated due to duration limits |
Bolna Error | Error from Bolna system |
Carrier unable to receive media | Media connection issues |
Network Congestion From Carrier | Network congestion from carrier |
End of inputs from Bolna | Call ended after a complete conversation (without prompt) |
Carrier unable to reach bolna | Carrier connectivity issue to Bolna |
Carrier ended call because MPC duration limit exceeded | Multi-party call duration limit reached |
Telephony Internal Error | Internal telephony system error |
Carrier Internal Error | Internal carrier error |
Call completed | Call completed successfully |
Call canceled | Call was canceled |
Call ended | Call terminated |
Call timed out | Call exceeded timeout limit |
Unknown | Unknown reason |
Notes on Code Interpretation
- Multiple codes may map to a single
hangup_bystatus depending on the network or device behavior. - Codes like
4000appear in multiple categories (API, caller, callee) - interpretation depends on context and direction of the call (inbound vs outbound). - Carrier-related hangups are often location-sensitive. If you’re noticing frequent
3010or3050codes in a specific region, consider checking local routing or carrier coverage.