Close reasons

close_reason is the most specific fact Talqing holds about how a run ended. It appears on the call record, in the session.completed webhook, as a filter on GET /v1/calls, and — grouped into buckets — on the observability endings chart. Every surface also serves close_reason_label, the plain sentence for that value. Read it rather than mapping the strings yourself: there are more than fifty of them, written from five places, and a second copy of the list goes stale the first time one is added.

user_initiated means the agent ended the call, not the caller. The name comes from the underlying media stack, where it identifies whoever asked for shutdown — and on this platform that is only ever the end_call operation. The caller hanging up is participant_disconnected. Reading user_initiated at face value gets the actor exactly backwards, and it is the single most common misreading of this field.

The buckets

A bucket answers “who owns the fix”. It never replaces the reason — every surface keeps the raw string beside it.

Bucket	Who owns it
`normal`	Nobody. Somebody chose to end the call: the caller, the agent, or the idle timer.
`transferred`	Nobody. Its own bucket rather than a kind of `normal`, because folding escalations into completions hides the rate at which your agent gives up.
`caller_unreachable`	The dial list. We reached the carrier and the carrier could not reach the person.
`carrier_fault`	The trunk. Your carrier configuration, or the carrier itself.
`configuration`	You. The call arrived and there was nothing valid to run.
`platform`	Us.
`other`	Anything this reference does not list. Shown raw rather than hidden, so a reason a future release adds is legible on arrival instead of invisible until somebody updates a table.

They are ordered as above on every chart: what went right, then outward through the parties who could fix what went wrong.

The fee column

waived means the platform fee was not charged for that call. Provider cost is still yours — the providers ran and billed your key regardless. See costs. Note that the bucket and the fee are not the same question. Three reasons in the platform bucket are still charged the fee, and they are marked below.

`normal`

Reason	What we show	Fee	What to do
`participant_disconnected`	The caller hung up	charged	Nothing. The caller ended the call.
`user_initiated`	The agent ended the call	charged	Nothing — the agent hung up, through an `end_call` operation. If it is happening too early, read debugging agents.
`end_call`	The agent ended the conversation	charged	Nothing. The text-channel counterpart of the above.
`task_completed`	The agent finished what it was doing and ended the call	charged	Nothing.
`idle_timeout`	Closed after going quiet, with nothing further said	charged	Nothing. A text conversation window closes after 60 seconds of quiet by design, and the next message opens a new one.

`transferred`

Reason	What we show	Fee	What to do
`transferred`	The caller was handed to a human	charged	Nothing. A successful escalation, still billed and still eligible for post-call analysis. Read `session.transfer` for the destination and the outcome. See transfers.

`caller_unreachable`

Every reason here is read off the carrier’s own SIP response to an outbound dial. None of them is a fault in your agent.

Reason	What we show	Fee	What to do
`sip_busy_failed`	The line was busy	waived	Try later. An outbound batch re-dials this when `max_attempts` is above 1 — the default is 1, so by default it does not.
`sip_no_answer_failed`	The phone rang and nobody picked up	waived	Try later. Re-dialled by a batch on the same terms as `sip_busy_failed`.
`sip_user_unavailable_failed`	Nobody answered	waived	Try later. Re-dialled by a batch on the same terms as `sip_busy_failed`.
`sip_connection_timeout_failed`	The call rang without ever connecting	waived	Try later. Re-dialled by a batch on the same terms as `sip_busy_failed`.
`sip_declined_failed`	The person declined the call	waived	Stop calling this number. A batch never re-dials it, whatever `max_attempts` says — somebody said no.
`sip_unallocated_failed`	That number is not in service	waived	Remove the number from your list. A batch never re-dials it, whatever `max_attempts` says.

`carrier_fault`

A run of these across different numbers is a trunk problem, not a phone list — which is why they count toward an outbound batch’s circuit breaker, and a run of busy signals does not. Ten consecutive failures from this bucket, configuration, platform or other stop the batch. See batch calling.

Reason	What we show	Fee	What to do
`sip_trunk_config_failed`	The trunk is not configured correctly	waived	Check the carrier account and, on Exotel, that the console setup step is done. See carrier accounts.
`sip_sip_trunk_failure_failed`	The phone trunk failed	waived	Check the carrier account’s credentials and status; then the carrier’s own status page.
`sip_dial_failed`	The outbound call could not be dialled	waived	The carrier refused before a leg existed, and gave no code we recognise. Check credentials and the caller ID on the number.
`sip_dispatch_failed`	No agent could be dispatched to the call	waived	Confirm a published voice agent is assigned to the number. See phone numbers.
`sip_media_failure_failed`	The audio path broke mid-call	waived	Usually transient. A pattern of it is worth raising with your carrier.
`sip_join_failure_failed`	The call could not join the room	waived	Transient. Retry.
`sip_signal_close_failed`	The carrier dropped its signalling connection	waived	Transient. A pattern of it is a carrier-side issue.
`sip_state_mismatch_failed`	The carrier and the platform disagreed about the call’s state	waived	Transient. Retry.
`sip_migration_failed`	The call failed while moving between servers	waived	Transient. Retry.
`sip_participant_disconnected_failed`	The phone leg dropped, and the carrier gave no reason	waived	Transient. This is also where an unrecognised carrier disconnect lands.
`sip_duplicate_identity_failed`	Two legs claimed the same identity on this call	waived	Raise it with support with the call id.
`sip_caller_unidentified_failed`	No caller number — the call was refused	waived	The inbound call arrived with no caller ID. Nothing to fix on your side.

`configuration`

These are yours to fix, and every one of them is fixable.

Reason	What we show	Fee	What to do
`missing_published_definition`	The agent has never been published	waived	Publish the agent. A draft cannot answer a call. See versions.
`unpublished_agent_failed`	The agent has never been published	waived	The same thing, from the telephony path. Publish the agent.
`insufficient_credits`	This workspace was out of credits, so the call was not answered	waived	Top up. Inbound calls resume immediately, and a paused batch resumes on its own. See pricing and credits.
`prepare_failed`	The agent could not start	waived	The definition would not compile for this call. Run `validate` on the agent. See validation.
`agent_start_failed`	The agent could not start - see the error below	waived	It compiled and then died before its first word — most often two attached tools presenting the same name to the model. Read `session.error` on the call, which says which.
`avatar_start_failed`	The avatar never joined, so the call was ended	waived	Check the Anam provider key and the avatar chosen on the agent. See video avatars.
`rejected`	The call was refused before the agent ran	waived	The call was turned away at the door. Check the number’s assignment and the agent’s channel.
`sip_account_missing_failed`	No telephony account was attached to the number	waived	Reattach the carrier account to the phone number.
`sip_outbound_config_failed`	The agent or phone number for this call is no longer usable	waived	Something the call depended on changed mid-run — the agent was unpublished or deleted, or the carrier account is no longer ready. This is the reason an outbound batch records when its own agent or number stops working.
`sip_outbound_missing_dial_failed`	The outbound call had no number to dial	waived	The request carried no destination. Check what created the call.
`invalid_sip_direction_failed`	The call’s direction did not match the number’s setup	waived	The number is not enabled for the direction the call used. Check its inbound and outbound flags.
`invalid_dispatch_metadata`	The call arrived with unusable routing data	waived	Raise it with support with the call id.
`missing_dispatch_metadata`	The call arrived with no routing data	waived	Raise it with support with the call id.
`unknown_tenant`	The call did not resolve to a workspace	waived	Raise it with support with the call id.

`platform`

Ours. Every one of these is a call you paid for in reputation, and the three marked charged are ones where the platform fee was still taken — the fee waiver list and this bucket are separate questions and not copies of each other.

Reason	What we show	Fee	What to do
`error`	The call ended on an error	waived	Read `session.error` on the call. Raise it with support if it repeats.
`stale`	The call was ended after the process running it stopped reporting	waived	Only outbound batch calls reach this, four hours after they started, so a dead worker cannot wedge a campaign. The call was never priced and emitted no `session.completed`.
`job_shutdown`	The worker shut down mid-call	waived	Transient, around a deploy.
`job crashed`	The worker crashed	waived	Raise it with support with the call id.
`worker_shutdown`	The worker shut down	charged	A text window closed because its worker went down, typically at a deploy. The conversation is intact; the next message opens a new window.
`session_replaced`	A newer session took over this conversation	charged	Nothing. A second session started on the same conversation and this one stood down.
`avatar_disconnected`	The avatar dropped out of the call	charged	Check the Anam provider key and quota. The call itself continued as far as it could.
`orphaned`	The worker handling this conversation stopped, and the next message opened a new window	waived	Nothing. The conversation continued in a new window.
`conversation_bind_failed`	The call could not be attached to a conversation	waived	Raise it with support with the call id.
`unknown`	The call ended for a reason nothing recorded	waived	Raise it with support with the call id.
`sip_agent_error_failed`	The agent errored on the phone leg	waived	Read `session.error`.
`sip_server_shutdown_failed`	The media server shut down mid-call	waived	Transient, around a deploy.
`sip_room_deleted_failed`	The call’s room was deleted underneath it	waived	Raise it with support with the call id.
`sip_room_closed_failed`	The call’s room closed underneath it	waived	Raise it with support with the call id.
`sip_participant_removed_failed`	The phone leg was removed from the call	waived	Raise it with support with the call id.
`sip_duplicate_call_failed`	The same call arrived twice	waived	Nothing — the duplicate was refused and the real call ran.

`other`

Not a list. other is what a reason this reference does not name buckets as, and the raw string is shown beside it rather than being folded into a generic label. That is deliberate: a default that absorbed a new failure would make it invisible until somebody remembered to update the mapping. A reason with no sentence of its own is de-underscored and capitalized — so an unrecognised some_new_reason reads as Some new reason. A terminal call that recorded no reason at all reads as No ending was recorded.

Text conversations

A text session is a window rather than a call, and three reasons are its normal endings:

Reason	When
`idle_timeout`	The window went quiet for 60 seconds and closed. This is how most text sessions end, and it is not a failure. The conversation is not over — the next message opens a new window on the same thread.
`end_call`	A tool ran an `end_call` operation, so the agent closed the window itself.
`worker_shutdown`	The worker shut down while the window was open, typically at a deploy. The next message opens a new window.

orphaned and session_replaced also occur on text. See text conversations.

Filtering by reason

GET /v1/calls?close_reason=… takes the exact string.

curl -G https://api.in.talqing.com/v1/calls \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  --data-urlencode "close_reason=sip_busy_failed" \
  --data-urlencode "limit=50"

const page = await talqing.calls.list({
  close_reason: "sip_busy_failed",
  limit: 50,
});

for (const call of page.items) {
  console.log(call.to_e164, call.close_reason_label);
}

from talqing import paginate

for call in paginate(talqing.calls.list, close_reason="sip_busy_failed"):
    print(call["to_e164"], call["close_reason_label"])

To see them ranked rather than filtered, read endings from GET /v1/observability — every distinct reason in the range with its bucket, its session count and how many of those failed. See observability.

Get started

Agents

Tools

Knowledge

Agent teams

Agent tasks

Telephony

Web & chat

Integrations

Email outbound

Observability

Guides

Platform

The buckets

The fee column

`normal`

`transferred`

`caller_unreachable`

`carrier_fault`

`configuration`

`platform`

`other`

Text conversations

Filtering by reason

​The buckets

​The fee column

​normal

​transferred

​caller_unreachable

​carrier_fault

​configuration

​platform

​other

​Text conversations

​Filtering by reason

The buckets

The fee column

`normal`

`transferred`

`caller_unreachable`

`carrier_fault`

`configuration`

`platform`

`other`

Text conversations

Filtering by reason