Debug Bolna Calls

Debug Bolna Calls

A symptom-to-fix runbook for Bolna voice agents. Most issues fall into a few well-known patterns; the tables below map the symptom to the exact field to change and the API call that verifies the fix.

Triage in 30 seconds

Ask the user (or pull from logs) for:

Then pull the two execution views:

# Full execution: status, costs, transcript, latency_data, telephony_data, extracted_data
curl "https://api.bolna.ai/executions/$EXECUTION_ID" \
  -H "Authorization: Bearer $BOLNA_API_KEY"

# Raw logs: every prompt/request/response, including LLM reasoning_content when available
curl "https://api.bolna.ai/executions/$EXECUTION_ID/log" \
  -H "Authorization: Bearer $BOLNA_API_KEY"

The execution payload has latency_data — the source of truth for "why is the call slow." See references/latency-metrics.md.

Symptom → fix

"Agent goes silent for ages before responding"

Look at latency_data in GET /executions/{id}:

Also tune on the agent side:

• task_config.incremental_delay — buffer time before agent commits to speaking. Default 400ms. Lower this for faster response (but you may interrupt yourself on partial transcripts). Higher for noisier audio.
• transcriber.endpointing — how long the STT waits in silence before "finalising" the user's turn. Default 250ms. Lower for quick conversational turns, higher for thoughtful users / long pauses.

"Agent interrupts me when I'm still talking"

task_config.number_of_words_for_interruption is too low (default 2).

• Bump to 4 or 5 for "let the user finish their sentence."
• Combine with transcriber.endpointing: 500-700 for users who pause mid-sentence.

"Agent never interrupts — keeps talking over me"

Opposite of above. Lower number_of_words_for_interruption (try 1 for very responsive agents). Also check that the transcriber is actually capturing the user — latency_data.transcriber.turns[] should grow with each user utterance. If transcripts are missing, the agent literally can't hear the interruption.

"Call hangs up after a silence on the user's side"

task_config.hangup_after_silence (default 10 seconds). Increase for callers who think before speaking, decrease for IVR-style flows.

For graph agents, prefer repeat_after_silence_seconds on individual nodes plus an expression edge on _silence_repeats — gracefully escalates instead of hanging up.

"Call ends too soon after the agent speaks"

Two likely settings:

• task_config.hangup_after_LLMCall: true — call ends immediately after the agent's first response. Use only for one-shot announcements.
• task_config.call_terminate — hard duration cap in seconds. Default 300 (5 min). Bump for longer use cases.
• LLM-prompted hangup in the system prompt ("if the user says goodbye, hang up"). Loosen the trigger if it's firing too eagerly.

"Agent sounds robotic / awkward / over-narrating"

• Cap response length in the system prompt: "Never speak more than two sentences per turn."
• Pick a higher-quality voice: ElevenLabs turbo_v2_5 / multilingual_v2; Sarvam for Indian languages.
• Enable backchanneling only if it fits (task_config.backchanneling: true) — "mhm" between user phrases. Excellent for support calls, weird in IVR-style flows.
• Lower temperature to 0.2-0.3 — long-tail creativity isn't worth the inconsistency.
• For Indian languages: write the prompt in native script (Devanagari), not phonetic English. See ../references/prompting-tips.md.

"Call stays in queued forever"

Status: balance-low

Top up the account wallet. Until then, every POST /call will land here. Verify with:

curl https://api.bolna.ai/user/me -H "Authorization: Bearer $BOLNA_API_KEY"

Look at wallet.

Status: failed / error

Check error_message on the execution. Common causes:

"No answer / busy"

These are normal outcomes, not agent failures. Use retry_config on POST /call to retry automatically:

{
  "retry_config": {
    "enabled": true,
    "max_retries": 2,
    "retry_on_statuses": ["no-answer", "busy"],
    "retry_intervals_minutes": [30, 60]
  }
}

Don't add failed / error to retry_on_statuses unless you've confirmed the cause is transient.

"Webhook never fires" / "Webhook fires but my server doesn't receive it"

Walk these in order:

1. agent_config.webhook_url set on the agent? (Inspect with GET /v2/agent/{id}.)
2. URL publicly reachable on HTTPS? Test with curl -X POST https://your-server/webhook -d '{}'.
3. Server returns 2xx to Bolna's POST? Non-2xx triggers Bolna's retry, but eventually stops.
4. Firewall whitelists Bolna's source IP 13.203.39.153?
5. Deduping by execution_id + status? Bolna POSTs on every status transition — multiple events per call is normal.
6. Receiver doesn't timeout (~10s)? If it does, return 2xx immediately and process async.

See ../references/execution-payload.md for the shape.

"Caller context ({customer_name} etc.) is wrong"

"Transcript looks wrong / has half-formed agent sentences"

Enable Precise Transcript Generation in the agent's Analytics Tab (beta). When the user interrupts the agent, Bolna trims the agent's unsaid words from the transcript so it reflects what was actually heard.

Without it, transcripts show what the LLM intended to say; with it, they show what the caller heard.

SIP trunk: "call connects but no audio"

Classic SRTP mismatch. See setup-sip-trunk/SKILL.md § Troubleshooting. Quick fixes:

• media_encryption: "no" for testing.
• media_encryption_optimistic: true to fall back to clear RTP automatically.
• Confirm carrier has SRTP enabled if you intend to keep sdes.

SIP trunk: "outbound INVITE silently fails"

Likely UDP fragmentation on large SIP headers. Switch transport: "transport-tcp".

Batch: "lots of calls failed / weren't placed"

Indian numbers: 140 / 160-series rejected

Compliance: the DLT registration, header registration, or template registration is incomplete. See ../references/india-compliance.md. Not a Bolna API failure — the carrier rejects before Bolna can dial.

Inspecting raw logs

GET /executions/{id}/log returns every prompt, request, and response in order. Each entry has:

Useful patterns:

• Find a wrong agent response → search for component: "llm" + type: "response" near the timestamp.
• Tool not called → grep for the tool name in component: "llm" entries; if absent, the LLM never picked it.
• Tool called with wrong params → component: "tool" + type: "request" shows the exact substituted payload.

The raw logs are the most powerful debugging tool Bolna provides. Use them before assuming there's a platform bug.

Going deeper

See also

• get-executions — full /executions/{id} and /executions/{id}/log reference.
• ../references/call-statuses.md — what each status means.
• ../references/hangup-codes.md — interpreting hangup_by + hangup_code + hangup_reason.
• setup-tools/references/tool-schemas.md — debugging tool-trigger problems.
• bolna-graph-agents/references/debugging.md — routing-log debugging for graph agents specifically.