Fix Common Agent and API Problems - Dasha BlackBox Documentation

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
HTTP 401 errors	Invalid/expired API key	Authentication Failures
Webhooks not received	URL not accessible	Webhook Failures
”Concurrent limit exceeded”	Too many active calls	Concurrent Limits
Tool calls failing	Webhook timeout or schema mismatch	Tool Failures
Robotic/choppy voice	TTS provider or network	Voice Quality
Agent mishears user	Language or noise settings	ASR Errors
Slow/irrelevant responses	Model or prompt issues	LLM Issues
Recording not found	Not enabled or still processing	Recording Issues

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

Verify via API

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);

Debug Steps

Test from dashboard — If dashboard test works but live calls fail, issue is phone/integration setup
Check call logs — Dashboard → Calls → Filter by agent → Review failed calls
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

Verify API Key

// 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);

Fix Origin Restrictions

For web integrations, add all required origins:

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']
  })
});

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	—

Fix Slow Endpoints

// Respond immediately, process async
app.post('/webhook', (req, res) => {
  res.status(200).json({ received: true });

  setImmediate(async () => {
    await processWebhook(req.body);
  });
});

Test Webhook

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');

Local Development

Use ngrok to expose local endpoints:

ngrok http 3000
# Use the https://xxx.ngrok.io URL in webhook configuration

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

Growth and Enterprise plan limits can be adjusted based on your needs. Contact support@dasha.ai to discuss your requirements.

Check Current Usage

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);

Solutions

Wait for slots — Poll active calls, schedule when capacity available
Stagger scheduling — Space calls over time instead of bulk scheduling
Upgrade tier — Contact 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

Verify Tool Configuration

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}`);
});

Fix Prompt for Tool Usage

Add explicit instructions to system prompt:

ALWAYS use the check_availability tool before confirming a booking.
NEVER guess about availability - always check first.

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

Switch Provider

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 } }
  })
});

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

Enable Noise Suppression

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 } }
  })
});

Add Confirmation to Prompt

ALWAYS confirm critical information by repeating it back:
- Names: "Your name is [name]. Is that correct?"
- Numbers: "That's [number]. Right?"

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

Adjust Settings

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
      }
    }
  })
});

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}`

Enable Recording

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 } }
  })
});

Check Recording Status

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

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

When to Contact Support

Email 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

Dashboard Testing — Test agents in the browser
Call Inspector — Deep call analysis
Webhooks Overview — Webhook configuration and security
Production Checklist — Pre-launch validation

Documentation Index

​Quick Diagnosis

​Agent Not Responding

​Quick Checks

​Debug Steps

​Authentication Failures

​Common Causes

​Webhook Delivery Failures

​Common Causes

​Timeout Requirements

​Concurrent Call Limit Exceeded

​Limits by Plan

​Solutions

​Tool Calling Failures

​Common Causes

​Voice Quality Issues

​Quick Fixes

​Provider Comparison

​ASR Transcription Errors

​Quick Fixes

​LLM Response Issues

​Quick Fixes

​Model Comparison

​Call Recording Not Available

​Quick Checks

​Dashboard Loading Issues

​Quick Fixes

​When to Contact Support

​Related Resources

Quick Diagnosis

Agent Not Responding

Quick Checks

Debug Steps

Authentication Failures

Common Causes

Webhook Delivery Failures

Common Causes

Timeout Requirements

Concurrent Call Limit Exceeded

Limits by Plan

Solutions

Tool Calling Failures

Common Causes

Voice Quality Issues

Quick Fixes

Provider Comparison

ASR Transcription Errors

Quick Fixes

LLM Response Issues

Quick Fixes

Model Comparison

Call Recording Not Available

Quick Checks

Dashboard Loading Issues

Quick Fixes

When to Contact Support

Related Resources