---
id: troubleshooting
title: Troubleshooting
slug: /troubleshooting
description: Fixes for the most common Chatley problems — calls not connecting, agents not answering correctly, bookings not appearing, and webhooks not arriving.
---

Start here when something is not behaving. Each section names the symptom as you
would see it, not the subsystem behind it.

## Calls

### The number rings but no agent answers

Work down in this order:

1. **Is a number assigned to the agent?** An agent without a number cannot
   receive anything — check the agent's configuration under [Agents](./agents.md).
2. **Is the agent published?** Draft changes do not affect live calls until
   published.
3. **Is the number pointed at Chatley?** If you brought your own number, its
   provider still needs to route to Chatley — see [Inbound calls](./inbound.md).

### Outbound calls are blocked with "DNC Compliance Required"

The agent has not accepted the DNC attestation. Accept it on the agent, then
retry — [Compliance](./compliance.md) walks through it.

### Calls connect but the caller hears silence

Usually a voice that has not finished loading or an agent with no opening line.
Confirm a voice is assigned on [Voices](./voices.md), then test with
[Talk to Assistant](./talk-to-assistant.md) before calling the real number.

### A call ends abruptly

Check the call in [Insights](./insights.md) for its outcome, and listen to the
recording. Abrupt endings are most often a transfer target that did not answer —
see [Call transfer](./call-transfer.md).

## Agent behaviour

### The agent answers questions wrongly, or makes things up

The agent only knows what you have given it. Attach the relevant material to its
[knowledge base](./knowledge-base.md), and be specific in its instructions about
what to do when it does not know — without that, a model will tend to guess.

:::tip[Test the exact phrasing that failed]
Reproduce it in [Talk to Assistant](./talk-to-assistant.md) rather than by
placing repeated live calls. It is faster and it does not call a real person.
:::

### The agent ignores an instruction

Long instructions bury the important parts. Put the non-negotiable rules first,
keep them short and literal, and prefer a [template](./templates.md) that already
works over rewriting from scratch.

### Captured fields come back empty

[Structured outputs](./structured-outputs.md) only fill when the agent actually
obtains the value. If a field is frequently empty, the agent is probably not
asking for it — say so explicitly in the instructions.

## Bookings

### A call went well but no appointment appears

1. Confirm the calendar is still connected — tokens expire. See
   [Integrations](./integrations.md).
2. Confirm the agent has booking enabled and a calendar selected.
3. Check [Appointments](./booked-appointments.md) — the booking may exist
   on a different calendar than the one you are looking at.

## Webhooks and leads

### Webhook events are not arriving

- Confirm the endpoint is reachable from the public internet over HTTPS.
- Return a 2xx quickly; a slow endpoint reads as a failure.
- Check whether your endpoint returned an error — see [Webhooks](./webhooks.md).

### Leads are captured but do not reach the CRM

The capture and the delivery are separate steps. Confirm the lead exists in
[Lead capture](./lead-capture.md) first — if it does, the problem is the webhook.

## Quotes

### The agent says it can't price a job

The job isn't on your price list, or none of its names match what the customer said.
Add the job, or add the customer's wording under **Other ways callers say it**, in
[Price list](./quote-agent/price-list.md). Until then those requests come to you as
**Needs inspection**.

### I don't get approval texts or emails

Check **Approvals** under **Quote Agent → Channels & settings**. Approval texts are
sent from the agent's phone number, so an agent without a number sends email only. A
blank approver email uses the workspace owner's email.

### The customer didn't get the quote by text

Texts need the agent to have a phone number registered for business texting, and the
customer must not have replied STOP. The email still goes out. Open the quote — its
history shows how it was delivered.

### An existing agent doesn't quote

Click **Turn on quoting** for it under **Channels & settings → Phone and chat**, then
add the line shown there to its instructions and publish. See
[Use an agent you already have](./quote-agent/channels.md#use-an-agent-you-already-have).

## API

### A request returns 401

The key is missing, malformed, or revoked. The header format is in
[Authentication](./api/authentication.md). A key pasted with a trailing space is
the most common cause.

## Still stuck

Have this ready and it will be resolved considerably faster:

- the **call ID** or **agent name**, and roughly when it happened;
- what you expected, and what happened instead;
- whether it happens every time or intermittently.