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

# Troubleshooting

> Find the cause and fix for common problems with dialing, voicemail, conversation quality, webhooks, SIP, WhatsApp, and email.

Each entry below lists a symptom, the likely causes, and how to fix them. If you're still stuck, open the call on the agent page and report it from **Any issues during the call?** below the transcript, or email [support@callers.ai](mailto:support@callers.ai) with the agent name and call ID (copy it from the call view).

## The agent can't start or isn't dialing

> **Clicking Start shows "Cannot start Agent"**
>
> The message tells you what's missing:
>
> | Message | Fix |
> | - | - |
> | "Please select at least one phone number before starting the Agent." | Open **Channels** in the editor and select a number on **Voice Channels** (or **Text Channels** for text agents). |
> | "Please connect at least one email mailbox before starting the Agent." | Connect a mailbox to the email agent. See [Email setup](https://docs.callers.ai/documentation/email-agents/email-setup.md). |
> | "Publish a version before starting the Agent." | Save your changes and click **Publish**. See [Versions](https://docs.callers.ai/documentation/build-your-agent/versions-and-split-traffic.md). |
> | "The following integration connections are missing: …" | An action or trigger uses an App Center connection that no longer exists. Reconnect it in the [App Center](https://docs.callers.ai/documentation/integrations/app-center.md) or update the step. |
> | "Review success criteria before starting" / "Add a success criterion before starting" | Open **Workflow** → **Success Criteria**, add at least one goal-reached criterion, and save. See [Success criteria](https://docs.callers.ai/documentation/results/success-criteria.md). |

> **The agent is running but no calls go out**
>
> Check these in order:
>
> 1. **The agent stopped itself.** An agent stops when no contacts are left that are eligible to call. Add contacts and click **Start** again.
> 2. **No eligible contacts.** Contacts that are completed, marked **Do not call** or **Wrong number**, archived, or out of attempts aren't called. Filter the contact list by status to see what's left.
> 3. **Outside availability.** Calls only go out during the agent's calling hours. Check the time zone in **Availability**. With **Use Contact's Time Zone** on, a contact is only called during the hours in *their* time zone.
> 4. **Waiting between attempts.** After a missed call, the contact waits for the minimum time between attempts (default 90 minutes) and the daily attempt limit before being called again. See [Scheduling and retries](https://docs.callers.ai/documentation/contacts/scheduling-and-retries.md).
> 5. **Concurrency limit.** **Max Outgoing Calls in Parallel** (default 10) caps how many calls run at once. A low value slows large lists.
> 6. **Do Not Call.** If **Enable Account Do Not Call (DNC) List** or **Check US Federal Do Not Call (DNC) Registry** is on, matching numbers are skipped. See [Do Not Call](https://docs.callers.ai/documentation/contacts/do-not-call.md).

> **Calls fail right away or show Failed**
>
> * Check the number format. Use international format with the country code, for example `+442071234567`. For US lists missing the leading `1`, import through the API with `fixUSPhoneNumber=true`.
> * If you use your own Twilio account, make sure **Voice Geographic Permissions** in Twilio allow the destination country.
> * For SIP numbers, see [SIP calls don't connect](#sip-and-telephony) below.

> **Few people answer**
>
> * Check your numbers for spam flags in **Phone numbers**. Numbers showing **Spam Risk Detected** get fewer answers; replace or rest them.
> * Use several numbers with **Prefer Local Numbers** or **Auto Optimize**. See [Phone numbers and caller ID](https://docs.callers.ai/documentation/contacts/phone-numbers-and-caller-id.md).
> * Spread retries across days and times rather than calling back quickly.
> * Send a [pre-call chat](https://docs.callers.ai/documentation/build-your-agent/pre-call-chat.md) message to ask permission first.

## Voicemail and call screening

> **The agent talks to a voicemail greeting, or hangs up on a real person**
>
> Voicemail detection runs during the call and again in post-call analysis. If a call was classified wrongly, open it and, under **Any issues during the call?**, choose **Incorrect Voicemail Detection** or **Missed Voicemail Detection** so the team can review it. To make sure contacts who reach voicemail still get your message, turn on **Leave message if reaching voicemail**. See [Voicemail and screening](https://docs.callers.ai/documentation/voice/voicemail-and-screening.md).

> **The agent leaves too many voicemails**
>
> Under **Leave message if reaching voicemail**, choose **First detected voicemail only** or leave the message only on the final scheduled call instead of **Whenever voicemail is detected**.

> **Calls get stuck on call-screening assistants**
>
> Some phones answer unknown callers with an AI screening assistant. Callers can detect these, answer the screening question, and wait for the person. See [Voicemail and screening](https://docs.callers.ai/documentation/voice/voicemail-and-screening.md).

## Conversation quality

For a deeper guide to responsiveness, see [Latency and conversation quality](https://docs.callers.ai/documentation/best-practices/latency-and-conversation-quality.md).

> **The agent interrupts the contact, or the contact keeps interrupting the agent**
>
> * **Agent cuts people off:** raise the **Patience Level** (toward **Slow**) so the agent waits longer before replying. Raise it on individual steps where contacts read out numbers or think before answering.
> * **Background noise triggers interruptions:** turn on **Auto-Adjust Patience on Interruptions**, and noise reduction where available.
> * **Important lines get cut off:** turn on **Speak with no interruptions** on that step (optionally **Only on first play**).
>
> See [Conversation dynamics](https://docs.callers.ai/documentation/voice/conversation-dynamics.md).

> **The agent replies too slowly**
>
> Lower the **Patience Level** (toward **Fast**). Keep steps short, and move long reference text to the [knowledge base](https://docs.callers.ai/documentation/using-callers/knowledge-base.md). For in-call actions that call slow APIs, use **Run in background** or a Wait step with a short **Say while waiting** line. See [Actions](https://docs.callers.ai/documentation/build-your-agent/agent-actions.md).

> **The agent mispronounces a name, brand, or term**
>
> Add the word to a [pronunciation dictionary](https://docs.callers.ai/documentation/voice/pronunciation-dictionary.md) with a **Sounds like** spelling or IPA, and attach the dictionary to the agent. For a single name that comes from contact data, a phonetic spelling in a variable also works.

> **The agent mishears words (names, product codes, addresses)**
>
> Add the terms to the agent's [speech recognition vocabulary](https://docs.callers.ai/documentation/voice/speech-recognition-vocabulary.md) with a positive weight so recognition favors them. For numbers like account IDs, let the contact type them with [keypad input](https://docs.callers.ai/documentation/voice/keypad-input.md).

> **The agent says things it shouldn't, or makes up answers**
>
> * Put facts in a [knowledge base](https://docs.callers.ai/documentation/using-callers/knowledge-base.md) and connect it to the agent.
> * Add instructions that limit scope, and [guardrails](https://docs.callers.ai/documentation/build-your-agent/instructions-and-guardrails.md) such as "No pricing commitments" or "Stay on topic".
> * Add [scenarios](https://docs.callers.ai/documentation/build-your-agent/agent-scenarios.md) for questions it answers poorly.

> **A variable is read out as \{\{name}} or left blank**
>
> The contact doesn't have a value for that variable. Map the CSV column to the variable during import, or send it in the contact's `data` object through the API. Mark variables the script can't work without as required. See [Variables](https://docs.callers.ai/documentation/build-your-agent/agent-variables.md).

> **Calls end on their own**
>
> Calls end after the maximum call duration (default 30 minutes) or after a long silence (default 30 seconds). Adjust these in [call recording and limits](https://docs.callers.ai/documentation/voice/call-recording-and-limits.md).

## Webhooks and actions

> **My webhook isn't receiving anything**
>
> 1. **Use HTTPS.** Webhook URLs must be HTTPS and publicly reachable.
> 2. **Check the events.** The webhook only fires for the events you selected. If you didn't select any, it fires only when post-call analysis finishes. To get every call, add events such as `CALL_FINISHED`. See [Webhook events](https://docs.callers.ai/documentation/webhook/webhook-events.md).
> 3. **Check the logs.** Advanced webhooks keep a request log with the status code your endpoint returned. Use **Test** to send a sample request.
> 4. **Allowlist the IPs.** Requests come from `35.245.204.86` and `35.221.61.75`. Allow both on your firewall.
> 5. **Check the right agent.** Webhooks can be set per agent or for the whole account (or subaccount). Make sure it's attached where the calls happen.

> **Signature validation fails**
>
> Simple webhooks are signed with RSA-SHA256; advanced webhooks and HTTP actions use HMAC-SHA256 with your account secret. Check the `X-Signature-Type` header, and verify against the raw request body before parsing JSON. See [Validating webhook signatures](https://docs.callers.ai/documentation/webhook/validating-webhook-signatures.md).

> **An in-call action times out or returns nothing**
>
> In-call actions wait 30 seconds for a response by default, and responses over 1 MB aren't used. Use **Test** on the action to see the exact request and response. For slow endpoints, use **Run in background** or a Wait step. Allowlist the IPs above if the endpoint is behind a firewall.

## SIP and telephony

> **Inbound SIP calls don't reach the agent**
>
> * Allowlist the Callers SIP address `35.245.182.192` (or `sip.callers.ai`) on your carrier or PBX. This address is for calls *into* Callers only.
> * Make sure the number is added to the SIP connection in E.164 format (`+` country code and number) and selected on an incoming agent.
> * Check that the agent is running and within its availability, or that **Receive calls full time** is on.

> **Outbound SIP calls fail or have no audio**
>
> * Check the SIP URL, port (default `5060`), and outbound authentication in the SIP connection.
> * Turn on **Tech prefix** or **SIP Diversion Header** if your carrier requires them.
> * Download the PCAP for the call from the call view and share it with your carrier or Callers support.
>
> See [SIP integration](https://docs.callers.ai/documentation/integrations/sip.md).

> **Twilio or Telnyx numbers don't appear**
>
> Sync the account again from **Phone numbers**, and make sure the numbers have voice (and SMS, for text agents) capability in the provider's console. See [Twilio](https://docs.callers.ai/documentation/integrations/twilio.md) and [Telnyx](https://docs.callers.ai/documentation/integrations/telnyx-integration.md).

## Text and email

> **WhatsApp template can't be used**
>
> WhatsApp only lets you start a conversation (or message outside the 24-hour window) with a template Meta has approved. A template that is pending or rejected can't be sent. Wait for approval (Callers notifies you when a template is approved), or edit and resubmit a rejected template. See [WhatsApp](https://docs.callers.ai/documentation/text-agents/whatsapp.md).

> **Text contacts stop getting messages**
>
> The contact may have opted out (for example, by replying STOP), or the agent reached its follow-up limit. Check the contact's status and the agent's follow-up settings in [Text agent setup](https://docs.callers.ai/documentation/text-agents/text-agent-setup.md).

> **Emails bounce**
>
> * **Hard bounce or invalid address:** the address can't receive mail. Callers skips the contact so it isn't emailed again. Fix the address and re-add the contact.
> * **Mailbox errors** (authentication failed, connection failed, account suspended) affect the whole agent. Reconnect the mailbox and check its credentials.
> * **Rate limited:** you're sending faster than the provider allows. Lower the mailbox's daily **Send Limit**, or add mailboxes and use a rotating sending strategy.
> * Set up SPF, DKIM, and DMARC on your sending domain to keep emails out of spam.
>
> See [Email setup](https://docs.callers.ai/documentation/email-agents/email-setup.md).

## Related

> **[FAQ](https://docs.callers.ai/documentation/resources/faq.md)**
>
> Quick answers to common questions.

> **[Reporting call issues](https://docs.callers.ai/documentation/using-callers/reporting-call-issues.md)**
>
> Send a problem call to the Callers team for review.

> **[Web SDK troubleshooting](https://docs.callers.ai/sdk/troubleshooting.md)**
>
> Fix widget and SDK issues on your website.

> **[Statuses and outcomes](https://docs.callers.ai/documentation/using-callers/call-statuses.md)**
>
> What each call and contact status means.


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