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

# Fix Common Agent and API Problems

> Quick solutions for the most common Dasha BlackBox problems: agent issues, API errors, webhooks, and voice quality

Fix common Dasha BlackBox problems quickly. Find your symptom, identify the cause, apply the solution.

***

## Quick Diagnosis

| Symptom                      | Likely Cause                       | Solution                                             |
| ---------------------------- | ---------------------------------- | ---------------------------------------------------- |
| Agent enabled but calls fail | Phone not configured               | [Agent Not Responding](#agent-not-responding)        |
| HTTP 401 errors              | Invalid/expired API key            | [Authentication Failures](#authentication-failures)  |
| Webhooks not received        | URL not accessible                 | [Webhook Failures](#webhook-delivery-failures)       |
| "Concurrent limit exceeded"  | Too many active calls              | [Concurrent Limits](#concurrent-call-limit-exceeded) |
| Tool calls failing           | Webhook timeout or schema mismatch | [Tool Failures](#tool-calling-failures)              |
| Robotic/choppy voice         | TTS provider or network            | [Voice Quality](#voice-quality-issues)               |
| Agent mishears user          | Language or noise settings         | [ASR Errors](#asr-transcription-errors)              |
| Slow/irrelevant responses    | Model or prompt issues             | [LLM Issues](#llm-response-issues)                   |
| Recording not found          | Not enabled or still processing    | [Recording Issues](#call-recording-not-available)    |

***

## Agent Not Responding

**Symptoms**: Agent shows "Enabled" but calls don't connect, go to voicemail, or fail immediately.

### Quick Checks

| Check           | How to Verify                           | Fix                                       |
| --------------- | --------------------------------------- | ----------------------------------------- |
| Agent status    | Dashboard → Agent → Status badge        | Enable if Disabled                        |
| Phone number    | Agent config → `phoneNumber` field      | Assign E.164 format number (+12025551234) |
| Required fields | System prompt, LLM, TTS, STT configured | Fill missing fields                       |

<Accordion title="Verify via API">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const agent = await fetch(`https://blackbox.dasha.ai/api/v1/agents/${agentId}`, {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }).then(r => r.json());

  console.log('Enabled:', agent.isEnabled);
  console.log('Outbound SIP:', agent.config.outboundSipConfig?.fromUser);
  console.log('Inbound SIP URI:', agent.inboundSipConfig?.sipUri);
  ```
</Accordion>

### Debug Steps

1. **Test from dashboard** — If dashboard test works but live calls fail, issue is phone/integration setup
2. **Check call logs** — Dashboard → Calls → Filter by agent → Review failed calls
3. **Verify webhooks** — Ensure webhook URLs are publicly accessible (not localhost)

***

## Authentication Failures

**Symptoms**: HTTP 401 Unauthorized, "Invalid API key", "Token expired"

### Common Causes

| Error                     | Cause                         | Fix                             |
| ------------------------- | ----------------------------- | ------------------------------- |
| "Invalid API key"         | Key doesn't exist or revoked  | Generate new key in dashboard   |
| "Token expired"           | Web integration token expired | Regenerate via API or dashboard |
| 401 only in production    | Using wrong environment key   | Check environment variables     |
| 401 from specific origins | Origin not whitelisted        | Add origin to web integration   |

<Accordion title="Verify API Key">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // Test key validity
  const response = await fetch('https://blackbox.dasha.ai/api/v1/agents', {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  });
  console.log('Valid:', response.status !== 401);
  ```
</Accordion>

<Accordion title="Fix Origin Restrictions">
  For web integrations, add all required origins:

  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  await fetch('https://blackbox.dasha.ai/api/v1/web-integrations/YOUR_INTEGRATION_ID', {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      allowedOrigins: ['https://yourapp.com', 'http://localhost:3000']
    })
  });
  ```
</Accordion>

***

## Webhook Delivery Failures

**Symptoms**: Webhooks not received, timeout errors, SSL certificate errors

### Common Causes

| Error                 | Cause                       | Fix                                |
| --------------------- | --------------------------- | ---------------------------------- |
| Connection timeout    | Endpoint too slow           | Respond immediately, process async |
| Connection refused    | URL not accessible          | Use public URL, not localhost      |
| SSL certificate error | Self-signed or expired cert | Use Let's Encrypt or valid CA      |
| DNS resolution failed | Domain doesn't resolve      | Check DNS configuration            |

### Timeout Requirements

| Webhook Type        | Default Timeout | Max Configurable |
| ------------------- | --------------- | ---------------- |
| StartWebHookPayload | 10 seconds      | 300 seconds      |
| ToolWebHookPayload  | 5 seconds       | 300 seconds      |
| Other webhooks      | 30 seconds      | —                |

<Accordion title="Fix Slow Endpoints">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // Respond immediately, process async
  app.post('/webhook', (req, res) => {
    res.status(200).json({ received: true });

    setImmediate(async () => {
      await processWebhook(req.body);
    });
  });
  ```
</Accordion>

<Accordion title="Test Webhook">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const result = await fetch('https://blackbox.dasha.ai/api/v1/webhooks/test', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      webHook: { url: 'https://your-server.com/webhook' },
      webhookType: 'CompletedWebHookPayload'
    })
  }).then(r => r.json());

  console.log('Success:', result.success, 'Time:', result.timeTaken, 'ms');
  ```
</Accordion>

<Accordion title="Local Development">
  Use ngrok to expose local endpoints:

  ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
  ngrok http 3000
  # Use the https://xxx.ngrok.io URL in webhook configuration
  ```
</Accordion>

***

## Concurrent Call Limit Exceeded

**Symptoms**: "Concurrent call limit exceeded", HTTP 429 with "Too many active calls"

### Limits by Plan

| Plan             | Concurrent Lines | Minutes/Month |
| ---------------- | ---------------- | ------------- |
| Developer (Free) | 1                | 1,000         |
| Growth           | 30 (at start)    | Contact sales |
| Enterprise       | Custom           | Custom        |

<Note>
  Growth and Enterprise plan limits can be adjusted based on your needs. Contact [support@dasha.ai](mailto:support@dasha.ai) to discuss your requirements.
</Note>

<Accordion title="Check Current Usage">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const concurrency = await fetch('https://blackbox.dasha.ai/api/v1/misc/concurrency', {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }).then(r => r.json());

  console.log('Active:', concurrency.active, '/', concurrency.concurrency);
  ```
</Accordion>

### Solutions

1. **Wait for slots** — Poll active calls, schedule when capacity available
2. **Stagger scheduling** — Space calls over time instead of bulk scheduling
3. **Upgrade tier** — Contact [support@dasha.ai](mailto:support@dasha.ai) for higher limits

***

## Tool Calling Failures

**Symptoms**: Agent says "I'm unable to complete that request", tool webhook errors, missing parameters

### Common Causes

| Error                  | Cause                         | Fix                                  |
| ---------------------- | ----------------------------- | ------------------------------------ |
| Timeout                | Webhook takes over 10 seconds | Optimize endpoint, respond faster    |
| Invalid response       | Response not JSON             | Return valid JSON object             |
| Missing parameters     | Schema mismatch               | Check tool schema in agent config    |
| Agent doesn't use tool | Prompt unclear                | Add explicit tool usage instructions |

<Accordion title="Verify Tool Configuration">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const agent = await fetch('https://blackbox.dasha.ai/api/v1/agents/YOUR_AGENT_ID', {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }).then(r => r.json());

  console.log('Tools:', agent.config.tools?.map(t => t.name));
  agent.config.tools?.forEach(t => {
    console.log(`  ${t.name} webhook: ${t.webhook?.url}`);
  });
  ```
</Accordion>

<Accordion title="Fix Prompt for Tool Usage">
  Add explicit instructions to system prompt:

  ```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
  ALWAYS use the check_availability tool before confirming a booking.
  NEVER guess about availability - always check first.
  ```
</Accordion>

***

## Voice Quality Issues

**Symptoms**: Robotic voice, choppy audio, audio dropouts

### Quick Fixes

| Issue                | Try This                                    |
| -------------------- | ------------------------------------------- |
| Robotic voice        | Switch TTS provider or try different voice  |
| Too fast/slow        | Adjust `speed` (0.8-1.2 range)              |
| Choppy audio         | Check network quality, use wired connection |
| Inconsistent quality | Try different voice ID                      |

### Provider Comparison

| Provider   | Quality   | Best For                       |
| ---------- | --------- | ------------------------------ |
| Cartesia   | Good      | Emotions, wide speed range     |
| ElevenLabs | Excellent | Premium quality, voice cloning |
| Inworld    | Very Good | Character voices, gaming       |
| LMNT       | Good      | Consistent output              |

<Accordion title="Switch Provider">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  await fetch('https://blackbox.dasha.ai/api/v1/agents/YOUR_AGENT_ID', {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      config: { ttsConfig: { provider: 'Cartesia', speed: 1.0 } }
    })
  });
  ```
</Accordion>

***

## ASR Transcription Errors

**Symptoms**: Agent responds to wrong words, user repeats themselves, numbers transcribed incorrectly

### Quick Fixes

| Issue               | Fix                                           |
| ------------------- | --------------------------------------------- |
| Wrong language      | Set correct `primaryLanguage` (e.g., `en-US`) |
| Background noise    | Enable `ambientNoise: true` in features       |
| Frequent mishearing | Add confirmation prompts to system prompt     |

<Accordion title="Enable Noise Suppression">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  await fetch('https://blackbox.dasha.ai/api/v1/agents/YOUR_AGENT_ID', {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      config: { features: { ambientNoise: true } }
    })
  });
  ```
</Accordion>

<Accordion title="Add Confirmation to Prompt">
  ```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
  ALWAYS confirm critical information by repeating it back:
  - Names: "Your name is [name]. Is that correct?"
  - Numbers: "That's [number]. Right?"
  ```
</Accordion>

***

## LLM Response Issues

**Symptoms**: Slow responses (over 5 seconds), irrelevant answers, hallucinations, repetition

### Quick Fixes

| Issue                | Fix                                       |
| -------------------- | ----------------------------------------- |
| Too slow             | Use faster model (Reflex-1, GPT-4.1 Mini) |
| Irrelevant responses | Improve system prompt clarity             |
| Hallucinations       | Lower temperature (0.3-0.5)               |
| Repetitive           | Adjust presence/frequency penalties       |

### Model Comparison

| Model             | Speed     | Intelligence | Cost   |
| ----------------- | --------- | ------------ | ------ |
| Reflex-1          | Very Fast | Good         | High   |
| GPT-4.1 Mini      | Fast      | Good         | Low    |
| Claude 3.5 Sonnet | Fast      | Excellent    | Medium |
| Gemini 2.5 Flash  | Very Fast | Good         | Low    |
| GPT-4             | Medium    | Excellent    | Medium |

<Accordion title="Adjust Settings">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  await fetch('https://blackbox.dasha.ai/api/v1/agents/YOUR_AGENT_ID', {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      config: {
        llmConfig: {
          model: 'gpt-4.1-mini',
          temperature: 0.5
        }
      }
    })
  });
  ```
</Accordion>

***

## Call Recording Not Available

**Symptoms**: "Recording not found", null recordingId, some calls have recordings but others don't

### Quick Checks

| Issue              | Fix                                                |
| ------------------ | -------------------------------------------------- |
| Recording disabled | Enable `recordingEnabled: true` in agent features  |
| Just completed     | Wait 1-2 minutes for processing                    |
| 404 on download    | Use correct endpoint: `/calls/media/{recordingId}` |

<Accordion title="Enable Recording">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  await fetch('https://blackbox.dasha.ai/api/v1/agents/YOUR_AGENT_ID', {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      config: { features: { recordingEnabled: true } }
    })
  });
  ```
</Accordion>

<Accordion title="Check Recording Status">
  ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const call = await fetch('https://blackbox.dasha.ai/api/v1/calls/YOUR_CALL_ID', {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
  }).then(r => r.json());

  console.log('Recording ID:', call.recordingId);
  // If null and call is Completed, wait and retry
  ```
</Accordion>

***

## Dashboard Loading Issues

**Symptoms**: Blank screen, infinite spinner, 403/401 errors

### Quick Fixes

| Issue              | Fix                                              |
| ------------------ | ------------------------------------------------ |
| Blank screen       | Clear cache and cookies, try incognito           |
| 401/403 errors     | Log out, clear cookies, log back in              |
| Works in incognito | Disable browser extensions                       |
| Still broken       | Check [status.dasha.ai](https://status.dasha.ai) |

***

## When to Contact Support

Email **[support@dasha.ai](mailto:support@dasha.ai)** when:

* Service unavailable for over 15 minutes
* Data loss or security concerns
* Tried all troubleshooting steps without resolution
* Need account-level changes (tier upgrades, custom limits)

**Include in your email**:

* Agent ID and Call ID (if applicable)
* Error messages (exact text)
* Steps already tried
* Timestamp when issue occurred

***

## Related Resources

* [Dashboard Testing](/docs/test/dashboard-testing) — Test agents in the browser
* [Call Inspector](/docs/test/call-inspector) — Deep call analysis
* [Webhooks Overview](/docs/webhooks-and-events/webhooks-overview) — Webhook configuration and security
* [Production Checklist](/docs/deploy/production-checklist) — Pre-launch validation