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

# Calling troubleshooting

> Fix incoming call routing, missing Inbox controls, webhook errors, and audio problems

## Your agent cannot answer, or Inbox has no answer button

Start with the number's **Incoming call answering** setting. **Calls** enables Calling, but does not choose who answers.

1. Open **Phone numbers** in Kapso.
2. Select the number and open **Settings**.
3. Check that **Calls** is on.
4. Under **Incoming call answering**, select the mode for your setup.

| Your setup | Select | What happens |
| - | - | - |
| An agent or integration, with teammates available as backup | **Agent with Inbox fallback** | The agent and Inbox can answer. The first answerer gets the call. |
| Only an agent or external integration | **Agent or integration** | Inbox shows call activity without answer controls. |
| Only teammates in their browsers | **Inbox only** | Inbox answers. Voice agents do not launch, and integrations cannot answer through Kapso. |

To keep your agent and let teammates answer, use **Agent with Inbox fallback**.
For this mode, send integration call actions through Kapso's Calling API.
Calls answered directly through Meta bypass Kapso's coordination and live answer tracking.

Before you select **Inbox only**, remove the number's assigned voice agent.
After you save a different mode, end the test call and place a new call.
Mode changes apply to new calls.

## The agent already answered, but you cannot join

**Agent with Inbox fallback** lets a teammate answer an unanswered call. It does not transfer an answered call.

A read-only **In call** card means the agent or integration has the call. The browser does not receive its audio.

The experimental live handoff requires a compatible voice-agent bridge and project access to the handoff rollout.
The bridge must request a teammate before **Join call** appears.
The phone-number mode alone does not enable this handoff.

## A call action returns 409

| Error | What to do |
| - | - |
| `inbound_calls_answered_in_inbox` | If your agent must answer, change **Inbox only** to **Agent with Inbox fallback** or **Agent or integration**. |
| `answered_elsewhere` | Another answerer claimed the call. Stop this answer attempt and release its local media. |
| `call_ended` | The call ended. Start a new test call. |

Do not retry an answer through Meta directly to bypass these errors.

## The phone rings, but nothing appears in Inbox

1. Check that you selected the correct project, number, and contact conversation.
2. Open the app Inbox with your Kapso account.
3. Check that your teammate can reply in the conversation.
4. Reload the page to recover its connection.
5. Place a new test call.

Call activity is independent of the answering mode. **Agent or integration** still shows call activity.
For missing answer controls, use [the mode checks above](#your-agent-cannot-answer-or-inbox-has-no-answer-button).

The embedded Inbox and Inbox access tokens cannot answer calls.
A closed browser receives no call alert.
For a background tab, enable **Ringtone** and **Desktop alerts** under **Call alert settings**.

## Your server receives no call webhook

1. Check that the number has an active webhook with `kind: meta`.
2. Check its destination URL and delivery logs.
3. Check that your server accepts the delivery and verifies its signature.

Kapso-format webhooks do not receive Meta Calling events.
A number has one Meta webhook. Changing its URL redirects every Meta event for that number, including message events.

See [webhook setup](https://docs.kapso.ai/docs/whatsapp/calling/overview.md#3-register-a-meta-webhook).

## The call connects, but audio fails

1. Check microphone access in the browser.
2. Check ICE connection errors on the browser and your media server.
3. Test without a VPN or restrictive firewall.
4. If direct media fails, check the media server's TURN configuration.

An HTTPS tunnel delivers webhooks. It does not make UDP audio reachable.
Changing **Incoming call answering** does not fix an audio connection.

See [audio setup](https://docs.kapso.ai/docs/whatsapp/calling/overview.md#4-connect-audio).

## The starter answers, but stops after its greeting

Check provider errors, speech recognition, and audio frames in both directions.
A greeting proves playback, not that the agent hears the caller.

Run the [full conversation test](https://docs.kapso.ai/docs/whatsapp/calling/voice-agents.md#test-a-full-conversation).

## What to send support

Include the project ID, Meta phone number ID, call ID, test time with timezone, and selected answering mode.
Include the exact error and relevant webhook delivery or request ID.
Describe whether the problem affects ringing, answering, two-way audio, or live handoff.

Do not include API keys, webhook secrets, TURN credentials, or raw SDP.

## Diagnose with an agent

Kapso Agent in Inbox or API mode can use `inspect_whatsapp_calling` to read saved setup and call state.
Use the Meta phone number ID or Kapso configuration UUID as `number_ref`.
Optional inputs include `conversation_id`, a Kapso call UUID as `call_id`, `limit`, and the history cursor `after`.

The result includes routing diagnostics, recent calls, saved active calls, and links to the Inbox and call details.
It does not test audio or answer calls.
For a different answering mode, Kapso Agent requests approval before it changes the number.

Project MCP exposes the same inspection tool.
Granular connections need `mcp:numbers:read`, `mcp:conversations:read`, `mcp:webhooks:read`, and `mcp:agents:read`.
The existing `update_whatsapp_number` tool accepts `inbound_call_handler` with `mcp:numbers:write`.


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