# Voice AI Troubleshooting — Diagnosing misbehaving agents

## Symptom: greeting starts, then call drops / audio stops

**Root cause: duplicate number assignment.** Two agents hold the same `inboundNumbers` entry. GHL routes the call to one agent, which starts the greeting, then the conflict resolves and audio cuts out.

**Diagnosis:** `GET /voice-ai/agents?locationId=<loc>` — scan every agent's `inboundNumbers` field. Same phone string on two agents = conflict.

**Fix:** PATCH one agent to detach the number:
```
PATCH /voice-ai/agents/{id}?locationId=<loc>
Body: {"inboundNumber": "", "inboundNumbers": []}
```
Confirm with a fresh GET. `isActive` is `null` in the API even for working agents — don't trust it. Test with an actual call.

---

## Symptom: ALL endpoints against a sub-account return 403 "token does not have access to this location"

**Root cause:** The sub-account wasn't selected during the V3 app install, so the agency token has zero access to it — not just voice-ai, but contacts, conversations, phone-system numbers, everything.

**Diagnosis:**
```bash
# Test two different endpoint families
curl -s -H "Authorization: Bearer $AGENCY_TOKEN" \
  "https://services.leadconnectorhq.com/voice-ai/agents?locationId=<loc>"
curl -s -H "Authorization: Bearer $AGENCY_TOKEN" \
  "https://services.leadconnectorhq.com/contacts/?locationId=<loc>&limit=1"
# If BOTH return "The token does not have access to this location" → sub-account not in install scope
```

**Fix:** Uninstall V3 at agency level → reinstall → at chooselocation picker, tick BOTH the working sub-account and the broken one. Or use "Install under all locations" + auto-install to future locations.

**Why this is confusing:** The error wording is identical to voice-ai's per-endpoint authClass restriction (`type is not allowed`), but the cause is completely different — it's an install-scope issue, not an endpoint restriction. Always test a second endpoint family before assuming it's voice-ai-specific.

**Why this matters for debugging:** The instinct is "voice-ai needs a location token" — but if the agency token can't even reach contacts on that sub-account, the problem is upstream. Fix the install scope first, then worry about voice-ai tokens.

---

## Symptom: TTS mispronounces brand names and context-dependent words

**Root cause:** ElevenLabs TTS treats all text as standard English. "Lead" (prospect) → "led" (metal). "Marketo" → "Mar-quet-to" instead of "Mark-toe".

**Fix:** append a **Pronunciation Rules** section to the agent prompt:
```
PRONUNCIATION RULES (follow these exactly — never deviate):
- "lead" (sales prospect) = "leed"
- "Marketo" = "Mark-toe"
- "Salesforce" = "Sales-Force"
- "n8n" = "n-eight-n"
- "GTM" = "G-T-M"
- "AI" = "A-I"
```
PATCH `agentPrompt` with the updated text. Takes effect on next call. Add entries as you hear new mispronunciations.

---

## Symptom: "Scopes can't be empty" during chooselocation install

**Root cause:** Using the scopeless short link for a **location-level** install. GHL's agency flow falls back to the app's registered scopes; the location flow does NOT.

**Fix:** use the full chooselocation URL with `&scope=` spelled out. Keep the list short (~10–15 scopes). URL-encode redirect_uri, `+` between scopes, `%2F` for slashes. See `gohighlevel-ops` pitfall #15 for the working pattern.