> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hubtalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting a call

> Provider failures, the caller speaking over a reply, glued replies, turn latency and the synthesis cache in the call card.

# Troubleshooting a call

Look here when a call did not go as expected: a speech or model provider failed, the agent did not answer what the caller said, a reply looks glued together, the answer took long or a phrase sounds wrong. All of it shows in the [call card](https://docs.hubtalk.ai/v4/platform/campaign-history/call-details) in the **full view**, with **Show system events** switched on — the checkbox administrators and developers have.

## Speech and model provider failures

When speech synthesis, speech recognition or the language model fails during a call, the card shows a **TTS error**, **ASR error** or **LLM error** event with a short line: provider · model · code · outcome · error text. The outcome says how the failure ended:

* **recovered by retry** — a repeated request went through;
* **spoken by the fallback voice** — the reply was spoken by the fallback voice instead of the main one;
* **recovered by the reserve recognition** — for a recognition error: the reserve recognition carried the call on;
* **not recovered** — the failure was final.

A switch of the call to a [reserve](https://docs.hubtalk.ai/v4/platform/agent-settings/prompt-and-models.md#reserve-services) is a separate event: **Reserve model**, **Reserve recognition** or **Reserve voice**. Its line says what replaced what and why, for example **Reserve voice · switch to the reserve · Dasha → Alena · an utterance of the primary voice failed**, or **the primary synthesis provider is unavailable** for a call that started on the reserve. Voices are labelled with their directory names. An expanded failure or switch event shows its fields as a list, the raw data is under the collapsed **Event JSON**.

Without **Show system events** administrators and developers see only **not recovered** failures. Everything a reserve served — failures recovered through a reserve, switch events and the reserve labels on replies — and failures recovered by retry are shown in the full view. A member and a manager do not see these events; that a reserve served the call is told to them and everyone else by **Reserve services were used** in the header.

If a reply could not be spoken by any voice, the call ends with the **Platform error** status: the caller would otherwise hear silence.

## The caller spoke where interruption was not allowed

When a node has interruption switched off and the caller speaks over the agent's reply anyway, their words are kept as a separate record. The conversation carries on unchanged: **there was no turn for it, and the agent did not reply to it** — the node did not allow itself to be interrupted.

The record is visible wherever the conversation is:

* in the call card — in both views, as an ordinary caller bubble; the **said during agent's reply** label appears only in the full view;
* in the transcript used for post-call analytics — as a `Client [during agent's reply]: …` line;
* in the [webhook](https://docs.hubtalk.ai/v4/webhooks.md) transcript — such a line carries `out_of_turn: true`;
* in report exports — as an ordinary caller utterance.

It is absent from the turn metrics (`GET /v1/calls/{call_id}/turns`): there was no turn, so there is nothing to measure. For the same reason it does not raise the turn count in History.

> [!WARNING]
>
> **These are exactly the words you can least afford to lose.** What a caller says over a disclaimer is most often "stop calling me" or "you have the wrong number". If you build automation on the transcript — opt-outs, the do-not-call registry, complaint triage — read the records with this label too, not only the utterances inside turns.

> [!WARNING]
>
> **A reply that was never heard does not count as said — and that changes the conversation**
>
> A reply labelled **not played** goes neither into the language model's prompt on the next turn, nor into the transcript used for post-call analytics, nor into the resolution of references like "yes, that's him". What the caller did not hear did not happen for the model either.
>
> Such a reply does not leave the platform either: it is not in the [webhook](https://docs.hubtalk.ai/v4/webhooks.md) transcript, in the call object of the [Web API](https://docs.hubtalk.ai/v4/web-api.md) or in the transcript columns of [report exports](https://docs.hubtalk.ai/v4/platform/campaign-history/report-columns.md). It can be seen only here, in the full view, with the **not played** label. A reply cut off mid-way by the caller is a different case: it stays everywhere, with the interrupted mark.
>
> A lost reply does stay lost, though: the agent does not replay it. If the opening was interrupted before its first sound, the caller never hears it — and the conversation carries on as if there had been no opening.

## A reply glued from fragments

A caller who pauses inside a sentence — "Yes… no, I don't want to" — is heard by the recogniser as two turns. When the agent had not yet made a sound, the platform [takes the unspoken transition back](https://docs.hubtalk.ai/v4/platform/agents/building.md) and joins the fragments into one reply. The history of such a call reads differently from what you hear on the recording, so three things are worth recognising:

* **One caller reply where the recording has two.** The record carries `merged_from: N` — the number of fragments glued — and a `fragments` list with the text, timestamp and recognition phases of each. The reply's own timestamp and its ASR and VAD phases are those of the **first** fragment: that is when the caller started speaking. The agent's language model never sees the split — it is given one ordinary reply.
* **The agent appears to repeat itself.** If the continuation turned out to be noise rather than speech, the transition stands and the node's reply is simply played again, under a new turn number and with no caller reply between the two. The `turn_rollback` event next to it has the status `redo` and the reason `noise`. Frequent noise interruptions are a matter for the agent's interruption settings, not for the history.
* **A transition into a node that never spoke.** The rollback event's detail carries `discarded_path` — the nodes the fragment took the dialogue to before it was taken back. That is the explanation for a transition in the transcript with no reply under it.

When the rollback did **not** happen, the same event says why with the status `committed`: the agent managed to speak in between (`agent_spoke`), the cancelled attempt had already called out to your systems (`external_side_effect`), the caller had heard the reply (`audio_started`), the four-fragment limit was reached (`limit`), the channel passed no sound flag (`no_signal`), or the rollback itself failed with an error (`rollback_error`) — the turn then goes on as it was. None of them affect the call's health verdict.

## Turn latency

In the full view an agent reply carries a **turn N ms** pill. A click opens the **Turn latency** card — the same one as in the test panel. A client reply has no latency line: its phases are part of the agent turn's card. All durations are whole milliseconds.

The card holds a bar of the turn made of segments, with a legend. For a voice call:

* **ASR** — end of the caller's speech → final transcript.
* **wait** — final transcript → end-of-utterance commit (with streaming recognition it is the remainder of the endpointing window, with batch recognition it is near zero).
* **start** — end-of-utterance commit → the agent's reply started.
* **handoff hold** — the turn waited for the continuation agent of a handoff.
* **wait check** — the model decided whether the caller asks to wait.
* **Jev** — the wait for the Jev transition decision, at every outcome.
* **classifier** — the LLM transition classifier.
* **rewrite** and **retrieval** — preparing the query and searching the knowledge bases.
* **LLM** — the reply model only: request → first phrase handed to synthesis.
* **synth** — first phrase handed to synthesis → first audio chunk.
* **playback** — first chunk sent → playback started, when the platform measured it.
* **other** — turn time not covered by the measured phases.

The bar shows only the segments this turn had. The segments add up to the number in the card header — the **turn**, from the end of the caller's speech to the agent's first audio. When the measured phases exceed the turn (the provider's timings out of sync), a **⚠** sits next to the total. A text call has other segments — **Jev**, **classifier**, **rewrite**, **retrieval** and **LLM** — and its total is their sum.

**All phases** opens the tree of the turn, one label per value:

* **VAD** — end of speech → the decision that the utterance is over; under it, **ASR** and **wait**. When a pause split the caller's phrase, a **discarded run** sits there too: the time of the dropped reply, not part of the turn sum.
* **start**.
* **to TTS** — end-of-utterance commit → first phrase handed to synthesis; under it, the holds, **Jev** with a **decided by** row (Jev, the LLM classifier or both), the classifier, rewrite, retrieval and **LLM**.
* **synth**, **playback**, **other** and the **turn**.
* The **SDK** group — the raw timings of the voice engine: **LLM TTFT** and **TTS TTFB**.
* **Mode** — how text reaches synthesis: a whole phrase per request or a stream from the first token.

The hint on each row explains the phase. When the turn searched the knowledge bases, a RAG line under the card shows the number of results, the top relevance and the time. Values marked `~` are a platform estimate: the provider or the voice engine did not report exact timings for this turn.

## Reply audio and the synthesis cache

Next to the ▶ button in the header of an agent reply sits the synthesis cache icon: the phrase is cached, not cached or on the denylist; the icon's tooltip names the status, and for a reply of several phrases — "N of M phrases cached". The **⋯** menu next to it holds the **Cache actions**: **Re-synthesize**, **Delete from cache** and **Add to denylist**. The last one asks for confirmation: the recording is removed from the cache, and the phrase is synthesized live until the mark is lifted. For a reply of several phrases the menu lists the phrases, each with the same actions and **Listen to phrase**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.