Debug Call Issues - DialNexa Documentation

When a call doesn’t go the way you expected, the call detail page is your primary debugging surface. This guide walks through how to use it systematically, what each section tells you, and how to distinguish between the different categories of failure.

Opening the Call Detail Page

Navigate to Call History

In the dashboard, go to Monitoring → Call History. You can filter by agent, phone number, date range, and call status.

Find the call

Use the search bar to find a call by phone number, or sort by date to find recent calls. Click the call row to open its detail page.

Review the summary header

The header shows: call direction (inbound/outbound), duration, start time, phone number, agent name, status, and end reason. Start here to get oriented before diving into the transcript.

Reading the Call Status

The status field tells you the high-level outcome of the call:

Status	What it means
`completed`	Call connected and ended normally (either the caller hung up or the agent ended it)
`failed`	Call connected but an unrecoverable error terminated it early
`no_answer`	Outbound call was not picked up within the ring timeout
`busy`	Destination number returned a busy signal
`voicemail`	Voicemail was detected and the call was not connected to a live human
`transferred`	Call was transferred via the Transfer Call tool; duration reflects time before transfer
`rejected`	Carrier or destination rejected the call before it rang

A completed status does not mean the agent performed correctly - it only means the call connected and ended without a platform error. Always read the transcript for quality assessment.

Reading the Transcript

The transcript is the most important debugging tool. Each turn is labelled with its speaker (agent or caller) and includes:

The raw text spoken or synthesized
The timestamp relative to call start
For agent turns: the LLM response latency and TTS latency
For caller turns: the transcription confidence score and detected language

What to look for:

Agent says nothing (silent turn)

A silent agent turn usually indicates a TTS failure or an LLM response that was empty. Check whether the turn has a tts_error or llm_empty_response tag. If the LLM returned content but TTS failed, the text is still visible in the transcript - you’ll see the agent’s intended response but hear silence on the recording.

Agent gives an unexpected response

This typically indicates a prompt issue rather than a platform error. Look at what the caller said immediately before, what the LLM received as context, and what it returned. If the LLM response looks correct but the agent said something different, there may be a tool call that modified the response.

Agent repeats itself

Repetition can happen when the transcriber returns an empty result (so the agent re-prompts) or when the conversation flow’s transition conditions are not being met (causing the agent to stay on the same node and re-execute its prompt). Check the transcription confidence on the caller’s turns.

Call ends abruptly

Look for the end_reason field on the call. Common values include user_disconnected, agent_disconnected, user_did_not_pick_up, user_busy, network_failure, system_failure, and insufficient_balance. Each points to a different fix.

Caller complains of echo or audio quality

Audio quality issues are telephony or network related, not agent related. Check if the caller was on a mobile network, and whether other calls from the same region show the same issue. This is not visible in the transcript - you need to listen to the recording.

Diagnosing Transcription Errors

Transcription errors are one of the most common sources of call quality problems. They cause the agent to misunderstand the caller or receive an empty input. How to identify transcription errors:

Low confidence score on a caller turn (below 0.7 is suspect; below 0.5 is likely wrong)
Transcribed text that looks phonetically similar to what was intended but semantically wrong (e.g., “book a table” transcribed as “book a day bill”)
Empty transcription on a turn where the caller clearly spoke (visible from call duration vs. transcript length)

What to do:

Switch transcriber model

Try Deepgram Nova 3 if you’re on Nova 2, or switch to Soniox for accented Indian English. Different models have different strengths for accent and domain vocabulary.

Check audio quality

Listen to the call recording. If the audio is genuinely noisy or garbled at the carrier level, transcription accuracy will suffer regardless of model.

Set the language hint

If your callers speak a specific language or dialect, set the language parameter on the transcriber config to hint the model. This significantly reduces errors.

Add vocabulary hints

Deepgram supports custom vocabulary and keyword boosting. Add domain-specific terms (product names, proper nouns) that the transcriber frequently gets wrong.

Diagnosing LLM Errors

LLM errors occur when the language model fails to return a valid response. They appear as llm_error or llm_timeout tags on agent turns in the transcript. Common LLM error types:

Error	Cause	Fix
`llm_timeout`	LLM did not respond within the timeout window	Use GPT-4o Mini for faster inference; check if prompt is unusually long
`llm_context_overflow`	Conversation history exceeded the model’s context window	Shorten system prompt; summarize conversation history in long calls
`llm_invalid_tool_call`	LLM returned a malformed JSON tool call	Clarify tool descriptions in the agent config; use a more capable model
`llm_empty_response`	LLM returned an empty string	Check if system prompt has conflicting instructions; simplify prompt
`llm_content_filtered`	LLM provider’s safety filter blocked the response	Review conversation context; add explicit handling for edge-case inputs

GPT-4o Mini is the default and fastest model. If you are seeing llm_timeout errors, switching from GPT-4o to GPT-4o Mini is usually the quickest fix. For complex reasoning tasks where accuracy matters more than speed, GPT-4o may produce better results.

Diagnosing Tool Errors

Tool errors occur when the agent invokes a tool (calendar booking, custom function, call transfer) and the tool returns an error or times out. How to inspect tool calls: In the transcript, each tool invocation is shown as an expandable entry between agent turns. Expand it to see:

Request payload: the exact JSON sent to the tool endpoint
Response received: the HTTP status code and response body
Latency: how long the tool call took
Error details: if the call failed, the error message from your endpoint

Common tool error scenarios:

Tool returns 500 or non-200 status

This is an error from your endpoint. DialNexa logs the full response body. Check your server logs for what caused the error. The agent will receive the error and should handle it gracefully if your prompt includes error handling instructions.

Tool times out

The default tool timeout is 10 seconds. If your endpoint regularly takes longer than this, either optimize the endpoint or increase the timeout in the tool configuration. During a timeout, the agent receives a synthetic error response and the conversation continues.

Tool called with wrong arguments

The LLM constructed the tool call arguments incorrectly. This usually means the tool description is ambiguous. Rewrite the tool description to be more explicit about expected argument types and formats. Include examples in the description if the LLM consistently misunderstands.

Transfer Call tool doesn't connect

If the transfer target number is invalid or not reachable, the transfer will fail and the call will return to the agent. Check that the transfer number is E.164 formatted and that the destination is reachable on your telephony provider.

Checking the Recording

Every call stores an audio recording (unless you have disabled recording in your agent settings). To access it:

Open the call detail page
Click the Recording tab
Use the audio player to listen to the full call
Optionally download the recording as an MP3 for offline analysis

Recordings are subject to your data retention settings. By default, recordings are stored for 90 days. After that, they are deleted automatically. Download recordings before this window if you need them for audit or training purposes.

Using Post-Call Analysis for Systematic Debugging

If you are seeing quality issues across many calls (not just one), post-call analysis can help you identify patterns at scale. Configure extraction fields to detect specific failure modes:

{
  "fields": [
    {
      "name": "caller_question_answered",
      "type": "boolean",
      "prompt": "Did the agent successfully answer the caller's primary question?"
    },
    {
      "name": "transfer_requested_but_failed",
      "type": "boolean",
      "prompt": "Did the caller ask to be transferred but the transfer did not happen?"
    },
    {
      "name": "agent_error_detected",
      "type": "boolean",
      "prompt": "Did the agent say something incorrect, irrelevant, or inappropriate?"
    }
  ]
}

Once configured, the dashboard aggregates these fields across all calls, letting you spot trends - for example, if 30% of calls have caller_question_answered = false, you know the agent’s prompt needs work.

Fix Agent Behavior - what to do once you’ve identified the issue
Reliability Overview - understanding the failure modes at the platform level
Latency - diagnosing and reducing call latency specifically

​Opening the Call Detail Page

​Reading the Call Status

​Reading the Transcript

​Diagnosing Transcription Errors

Switch transcriber model

Check audio quality

Set the language hint

Add vocabulary hints

​Diagnosing LLM Errors

​Diagnosing Tool Errors

​Checking the Recording

​Using Post-Call Analysis for Systematic Debugging

​Related Pages

Opening the Call Detail Page

Reading the Call Status

Reading the Transcript

Diagnosing Transcription Errors

Diagnosing LLM Errors

Diagnosing Tool Errors

Checking the Recording

Using Post-Call Analysis for Systematic Debugging

Related Pages