Telephony troubleshooting

Find the symptom, apply the fix. Work outward from configuration to the single call:

readiness on the phone number — can it do the thing at all? A number that is not live cannot answer.
close_reason on the call — did a call happen, and who owns how it ended. Full list: close reasons.
The call detail (GET /v1/calls/{session_id}) — transcript, tool calls and outputs, per-stage latency, error, recording.

status_message on a number or carrier account carries its last problem.

The number is not live

`readiness`	Cause	Fix
`needs_agent`	No agent assigned, or its carrier account was disabled and re-enabled.	Assign a published `voice` agent, or `POST .../phone-numbers/{number_id}/provision`.
`needs_carrier_setup`	`can_inbound` is false — on Exotel, the region’s console Flow is not confirmed.	Finish the step and confirm it with `console_setup_confirmed` + `console_setup_region`. See carrier accounts.
`setting_up`	`pending` or `provisioning`.	Provision it; if it stays here, provision again.
`error`	Provisioning failed.	Read `status_message`, fix it, provision again.
`disabled`	Someone disabled the number.	`PATCH` `{"status": "pending"}`, then provision.

Assigning refused with '<name>' is required and has no default: the agent declares a variable an inbound call can never supply. Give it a default or make it optional (variables).

Inbound calls are not arriving

Check	Meaning
`GET /v1/calls?type=SIP_INBOUND` has a record	The call reached Talqing and was refused or ended — read its `close_reason`.
No record at all, number `live`	The carrier is not delivering the call. Check the number is still on your carrier account and pointed at Talqing; a manual change in the carrier console is not undone by re-importing.
`insufficient_credits` on every call	The workspace is out of credit; the number still reads `live`. Top up.
`sip_caller_unidentified_failed`	The caller withheld their number. Cannot be answered.
`unpublished_agent_failed`	The assigned agent has no published version. Publish it.
Exotel: number shows “Install an App” in ExoPhones	It is not attached to the region’s Flow, even if the region is confirmed. Also required after moving a number between regions.

Outbound calls refused at setup

Refused before anything is dialled, so nothing is billed.

Error	Fix
`this number is not enabled for outbound`	`PATCH` the number with `{"can_outbound": true}`.
`phone number must be active (provisioned) for outbound calls`	Provision the number.
`telephony account is not ready for outbound; provision it first`	Provision the carrier account, fixing its credentials first if it is in `error`.
`to: … is not a valid number to dial from …`	Send `to` in international format; a national number is read against the country of the number you dial from.
`this endpoint runs voice agents; …`	Only `voice` agents can be on a phone call.
`publish the agent before calling`	Publish it.
`'<name>' is required and has no default`	Send it in `vars`, or give it a default.
`402`	Workspace out of credit. Top up.
`502 failed to dispatch outbound call`	The call could not start; it is recorded with `sip_dispatch_failed`. Retry; if it repeats, contact support with the session id.

Details: outbound calls. A batch that stopped itself is covered in batch calling.

The call drops immediately

`close_reason`	Cause	Fix
`prepare_failed`	The agent could not be built — usually a missing provider key or an unknown model.	Read `error`; run validation.
`agent_start_failed`	The agent died before its first word — most often two tools exposing the same name.	Read `error`, fix, republish.
`avatar_start_failed`	Video only: the avatar never joined.	Check the avatar and its provider key.
`conversation_bind_failed`	The call could not be attached to a conversation.	Platform-side; contact support with the session id.

Reasons ending in _failed (and rejected, insufficient_credits, stale) waive the platform fee; provider spend already incurred on your own keys remains.

No audio, or one-way audio

The recording is stereo — caller on the left, agent on the right — so a silent channel shows which side never arrived.

Symptom	Likely cause
Caller channel silent	Their audio never reached Talqing — a carrier media problem, often ending `sip_media_failure_failed`.
Agent channel silent	The agent never spoke. Read the transcript and `close_reason`.
`sip_media_failure_failed` mid-call	The carrier’s audio path broke.

user_initiated means the agent ended the call (via end_call), not the caller; the caller hanging up is participant_disconnected.

Credentials expired or rotated

Symptoms: the carrier account flips to error with the carrier’s message; GET .../remote-numbers or import fails with could not list numbers from <carrier>; a batch stops after ten setup failures in a row; deleting the account returns 502. Fix: PATCH /v1/telephony/accounts/{account_id} with the new credentials (it merges), then POST .../provision. remote-numbers reads the carrier live, so it is the quickest check that a credential works.

Still stuck

Email hello@talqing.com with the number in E.164, the session_id of one bad call, and its close_reason.

Close reasons

Every reason a call can end and what to do about it.

Debugging agents

The agent said something odd, was slow, or hung up.

Get started

Build

Guides

Telephony troubleshooting

The number is not live

Inbound calls are not arriving

Outbound calls refused at setup

The call drops immediately

No audio, or one-way audio

Credentials expired or rotated

Still stuck

Next

Close reasons

Debugging agents

​The number is not live

​Inbound calls are not arriving

​Outbound calls refused at setup

​The call drops immediately

​No audio, or one-way audio

​Credentials expired or rotated

​Still stuck

​Next

Close reasons

Debugging agents

The number is not live

Inbound calls are not arriving

Outbound calls refused at setup

The call drops immediately

No audio, or one-way audio

Credentials expired or rotated

Still stuck

Next