Introduction
Every Bolna Voice AI call records metadata about how and why it was terminated. This data is essential for debugging, analytics, and improving call completion rates. Each call termination includes three fields:| Field | Description |
|---|---|
hangup_by | Party or system that initiated the hangup (caller, callee, carrier, etc.) |
hangup_code | Numeric code from the telecom provider indicating the specific reason |
hangup_reason | Human-readable description of why the call ended |
Why Hangup Codes Matter
Debug Call Issues
Identify whether disconnections are user-initiated, carrier-caused, or system errors
Monitor Reliability
Track telecom partner performance across providers like Twilio and Plivo
Improve Workflows
Optimize call handling based on termination patterns and regional issues
Regional Insights
Pinpoint geographic routing problems (US, India, Southeast Asia, MENA, etc.)
Hangup Status and Provider Codes
| Hangup By | Description | Provider Codes |
|---|---|---|
| API Request | Call ended via Bolna API request | 4000, 4020 |
| Callee | Recipient hung up (outbound calls) | 3020, 4000 |
| Caller | Caller ended the call (inbound calls) | 4000 |
| Carrier | Terminated by telecom carrier | 2000, 3000, 3010, 3020, 3040, 3050, 3070 |
| Error | Ended due to unexpected error | 3080, 3090, 3110, 5010, 5020, 7011, 8011 |
| Plivo | Plivo provider disconnected the call | 1010, 4010, 5020, 6000, 6010, 6020 |
| Unknown | Termination reason unknown | 0 |
| (empty) | No hangup reason recorded | (empty) |
Hangup Reasons
- Bolna-Side Reasons
- Telephony Provider Reasons
Bolna provides specific hangup reasons based on your agent configuration:
| Reason | Description |
|---|---|
inactivity_timeout | Call ended because the silence threshold was exceeded |
llm_prompted_hangup | Call ended based on custom prompt evaluation |
Notes on Code Interpretation
Multiple codes per status
Multiple codes per status
Multiple provider codes may map to a single
hangup_by status depending on network or device behavior. Always check the hangup_reason field for additional context.Context-dependent codes
Context-dependent codes
Codes like
4000 appear in multiple categories. Interpretation depends on call direction (inbound vs outbound) and the hangup_by field.Regional carrier issues
Regional carrier issues
Frequent
3010 or 3050 codes in a specific region may indicate local routing or carrier coverage problems. Contact support if you notice persistent regional patterns.Related Pages
Call Status List
Track the full lifecycle of your calls
Call Latency Metrics
Analyze performance across the voice pipeline
Get Execution API
Retrieve full execution details programmatically