Diagnose a call

Get a plain-English explanation of what happened on any call to your voice agent (failed, cut short, or completed) and what to fix.

Find why a call failed, ended early, had one-way audio or dropped its stream. After logging in, find the call’s UUID (its unique identifier), then request an explanation:

plivo voice calls list --limit 5                 # find the UUID
plivo voice calls diagnose "<call_uuid>"           # usually about a minute; allow 30 to 120 s

Replace "<call_uuid>" with an ID from the list. The diagnosis reports a timeline and likely causes involving your server, Plivo or the carrier. For voice agents, check the answer URL, its XML and the WebSocket connection.

A typical answer:

What happened: This inbound call was terminated because Plivo could not fetch call instructions from your answer URL.
Likely cause: The answer URL https://api.example.com/plivo/answer returned 404. The call was hung up with
              cause 7011 (Error Reaching Answer URL).
Timeline: 07:48:40.600 call received · 07:48:40.630 answer URL responded 404 · 07:48:41.016 call hung up
Suggested next step: Make sure the answer URL is deployed and returns Plivo XML with HTTP 200; every inbound call will fail until it does.

The hangup causes you will see most often while building a voice agent:

Hangup cause	Meaning	Fix
7011 Error reaching answer URL	Plivo could not fetch your answer URL (down, not public, tunnel closed, 4xx/5xx)	Check the URL is reachable from the internet; while developing, use Forward calls to your voice agent
8011 Invalid answer XML	The answer URL returned something that is not Plivo XML (often JSON, or an HTML error page)	Return <Response><Stream …> with Content-Type: application/xml; check with curl -X POST "<answer_url>"
4010 End of XML instructions	Normal end; your voice agent closed the WebSocket, or the XML finished	Only a problem if the call ended earlier than you expected: check your voice agent’s logs for why it closed
USER_BUSY	A busy outcome; inspect the call record and XML to identify its source	Check whether your handler deliberately rejected the call before changing it

If the answer URL and XML are valid but the caller hears silence, test the voice agent and its audio format without a phone with Test your voice agent. For the raw record (hangup cause, source, duration) run plivo voice calls get <call_uuid> -o json, or plivo open call <call_uuid> to see the call and its Call Insights in the console. For a call over a SIP trunk, use plivo sip calls diagnose and plivo sip calls insights; see Check and diagnose a SIP call.

​

Read the result in a script

With -o json (or when output is piped), diagnose prints one JSON result when the analysis ends:

plivo voice calls diagnose "<call_uuid>" -o json

{
  "data": {
    "call_uuid": "…",
    "what_happened": "…",
    "likely_cause": "…",
    "timeline": [ { "at": "…", "event": "…", "source": "…" } ],
    "next_steps": [ "…" ],
    "hangup_cause_code": 7011,
    "hangup_source": "…",
    "confidence": "high",
    "answer": "…"
  }
}

Field	What it holds
what_happened, likely_cause	The assistant’s explanation, in short sentences
timeline[]	Events in order, each with at, event and source
next_steps[]	What to do next
hangup_cause_code, hangup_source	Taken from the call record, not from the assistant; null for a message
confidence	high, medium or low; null when the answer gives none
answer	The full prose answer

For a message the ID field is message_uuid instead of call_uuid. -o yaml, -o csv and --query work on this result, for example --query 'data.likely_cause'. -o jsonl streams the assistant’s raw events instead of one result.

If the analysis fails, escalates or stops early, diagnose exits with code 3, so a script can tell a finished analysis from one that didn’t finish. Pass --timeout <seconds> to put a limit on a script’s wait: an analysis still running at that point ends with UPSTREAM_TIMEOUT and exit code 3. An unknown UUID exits 1 without using a request from your limit.

The answer is written by Plivo’s AI assistant, so read the prose as an explanation; scripts should read the fields of the -o json result instead. diagnose and plivo ask share a limit of 5 requests per 60 seconds per account. Only calls on your own account can be diagnosed. For messages see Diagnose a message; for general questions see Get help.