​

Quick Start Guide

​

What You’ll Build

• ✅ A working AI agent with voice capabilities
• ✅ Tested conversation via dashboard widget
• ✅ Understanding of basic configuration options

​

Prerequisites

• BlackBox Account: Sign up at blackbox.dasha.ai
• Modern Browser: Chrome, Firefox, Safari, or Edge (latest version)
• Microphone Access: For voice testing (optional, can also use text chat)

​

Step 1: Sign In to BlackBox

• Overview of your agents (if any)
• Call statistics
• Quick access to create your first agent

​

Step 2: Create Your First Agent

​

Set Basic Information

• ✅ Good Examples: “Customer Support Bot”, “Sales Assistant”, “FAQ Helper”
• ❌ Avoid: “Agent 1”, “Test”, “My Agent”

You are a friendly and helpful AI assistant. Your role is to:
- Answer user questions clearly and concisely
- Be polite and professional
- Ask clarifying questions when needed
- Admit when you don't know something

Keep responses brief and conversational.

• English (USA) - en-US
• English (UK) - en-GB
• Or any of the 40 supported languages

​

Quick Configuration with Defaults

• Default: OpenAI GPT-4.1-mini
• Why: Best balance of quality, speed, and cost
• You can change this later in the LLM Config tab

• Default: ElevenLabs (eleven_flash_v2_5)
• Why: High-quality, natural-sounding voices with low latency
• You can customize later in the Voice & Speech tab

• Automatic: Platform automatically selects the best provider
• No configuration needed: Optimized based on language and conditions

​

Step 3: Save Your Agent

​

Save Your Agent

1. Click the “Save Agent” button at the bottom of the form
2. Your agent is created and automatically enabled (ready to take calls)
3. You’ll be redirected to the agent detail page

​

Step 4: Test Your Agent

​

Open the Test Widget

1. Click the “Test Agent” button (usually in the top-right corner)
2. The test widget opens in a modal or sidebar

​

Start a Conversation

​

What to Test

You: "Hello!"
Expected: Friendly greeting and offer to help

You: "What's the weather like today?"
Expected: Agent asks for location or admits it doesn't have weather data

You: "I need help"
Expected: Agent asks what you need help with

You: "I don't understand"
Expected: Agent rephrases or asks for more context

​

Monitor the Conversation

• Response Time: How quickly the agent responds
• Voice Quality: Natural sounding, correct pronunciation
• Accuracy: Follows the system prompt instructions
• Turn-Taking: Handles interruptions smoothly

​

Step 5: Review and Next Steps

​

What You’ve Achieved

• ✅ Created an AI Agent: With name, prompt, and language configured
• ✅ Enabled Live Testing: Agent is active and ready for conversations
• ✅ Tested Voice/Chat: Verified the agent works in real-time
• ✅ Understood Basics: Know how to create, enable, and test agents

​

Review Your First Conversation

1. Go to the Calls page (main navigation)
2. Find your test conversation in the list
3. Click “Inspect” to see:
   • Full transcript of the conversation
   • Metadata (duration, status, timestamps)
   • LLM and voice provider used

​

Improving Your Agent

​

Refine the System Prompt

1. Go back to your agent’s Edit page
2. Open the Basic Info tab
3. Update the System Prompt to:
   • Be more specific about the agent’s role
   • Add examples of good responses
   • Include guardrails for what NOT to do
4. Save and test again

You are a customer support agent for BlackBox, an AI voice platform.

Your role:
- Help users understand how to create and configure AI agents
- Answer questions about voice providers, LLMs, and testing
- Guide users to relevant documentation
- Be patient with technical questions

Guidelines:
- Keep responses under 50 words when possible
- Use simple language, avoid jargon
- If you don't know something, admit it and suggest checking the docs
- Never make up features or capabilities

Example questions you might receive:
- "How do I add a phone number to my agent?"
- "What's the difference between ElevenLabs and Cartesia?"
- "Can my agent transfer calls?"

​

Customize Voice and LLM

1. Go to Voice & Speech tab
2. Select a different TTS provider (ElevenLabs, Cartesia, Dasha, Inworld, LMNT)
3. Browse available voices
4. Preview the voice before saving
5. Adjust speed if supported by the provider

1. Go to LLM Config tab
2. Select a different vendor (openai, groq, grok, deepseek)
3. Choose a model:
   • Fast & Cheap: gpt-4.1-mini, llama-3.1-8b-instant
   • High Quality: gpt-4.1, llama-3.3-70b-versatile
   • Reasoning: deepseek-r1, o3-mini
4. Adjust temperature (0.5-1.0 recommended)
5. Save and test again

​

Add Advanced Features

• Connect external APIs
• Query databases
• Perform calculations
• Schedule appointments

• Set business hours
• Define timezone availability
• Handle calls outside hours

• Enable/disable advanced capabilities
• Configure knowledge base access
• Manage agent behavior flags

• Get notified when calls start/end
• Process conversation results
• Update your CRM automatically

• Connect to Model Context Protocol servers
• Access pre-built tool integrations
• Expand agent capabilities instantly

​

What’s Next?

​

🔧 Build - Enhance Your Agent

• Agent Basics - Lifecycle, states, and management
• LLM Configuration - Deep dive into all LLM vendors and models
• Voice & Speech - Complete guide to TTS providers and options
• Tools & Functions - Add external integrations and function calling
• Best Practices - Prompt engineering and performance optimization

​

🧪 Test - Ensure Quality

• Testing Overview - Comprehensive testing strategy
• Dashboard Testing - Use the built-in test widget
• Voice Preview - Test voices before deploying
• Dev Toolbar - Advanced debugging tools
• Call Inspector - Analyze conversation transcripts

​

🚀 Deploy - Go Live

• Phone Numbers - Connect real phone numbers
• Inbound Calls - Receive calls on your agent
• Outbound Calls - Make calls programmatically
• Web Widget Embedding - Add to your website
• Production Checklist - Pre-launch verification

​

📊 Monitor - Track Performance

• Dashboard Overview - Understand your metrics
• Call Management - View and manage all calls
• Call History - Search and filter past calls
• Analytics - Analyze agent performance
• Agent Performance - Track key metrics

​

Troubleshooting

​

Agent Not Responding

1. Check Agent Status: Ensure toggle “Allow this agent to take calls” is ON (new agents are enabled by default)
2. Verify System Prompt: Must not be empty. Add a simple prompt and save.
3. Refresh Page: Sometimes the widget needs a refresh after changes
4. Try Text Chat First: Eliminates microphone/voice issues
5. Check Browser Console: Look for error messages (F12 → Console tab)

​

Microphone Not Working

1. Grant Permissions: Click the browser prompt to allow microphone access
2. Check System Settings: Ensure microphone is not muted in OS settings
3. Try Different Browser: Chrome and Firefox have best WebRTC support
4. Use Text Chat: Alternative testing method while troubleshooting
5. Check Microphone: Test in another app (Zoom, Google Meet) to verify hardware

​

Voice Sounds Robotic or Unnatural

1. Change Voice Provider: Try ElevenLabs for highest quality
2. Select Different Voice: Browse and preview other voices
3. Adjust Speed: Slower speeds (0.8-0.9x) often sound more natural
4. Check Language Match: Ensure voice language matches primary language setting

​

Agent Gives Wrong Answers

1. Refine System Prompt: Be more specific about role and behavior
2. Lower Temperature: Set to 0.5-0.7 for more consistent responses
3. Add Examples: Include example Q&A in the prompt
4. Test Different Models: Some models are better for certain tasks
5. Review Conversation: Use Call Inspector to see what the LLM actually received

​

Slow Response Times

1. Switch to Faster Model: Try gpt-4.1-mini or groq models
2. Enable Priority Tier: For OpenAI, turn on “Use priority tier (lower latency)”
3. Reduce Max Tokens: Limit response length for faster generation
4. Use Faster Voice: Cartesia and Dasha are optimized for low latency
5. Check Network: Ensure stable internet connection

​

Need More Help?

• 📚 Documentation: Browse the full documentation for detailed guides
• 🔍 Search: Use the search bar (top-right) to find specific topics
• 💬 Support: Contact our support team for personalized help
• 🐛 Common Issues: Check Common Issues for known problems

​

API Alternative

​

Create Agent via API

const response = await fetch('https://blackbox.dasha.ai/api/v1/agents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "My First Agent",
    isEnabled: true,
    config: {
      primaryLanguage: "en-US",
      llmConfig: {
        vendor: "openai",
        model: "gpt-4.1-mini",
        prompt: "You are a helpful assistant...",
        options: {
          temperature: 0.7,
          maxTokens: 300
        }
      },
      ttsConfig: {
        vendor: "ElevenLabs",
        model: "eleven_flash_v2_5",
        voiceId: "zmcVlqmyk3Jpn5AVYcAL",
        speed: 1.0
      },
      sttConfig: {
        vendor: "Auto"
      },
      features: {}
    }
  })
});

const agent = await response.json();
console.log('Agent created:', agent.agentId);

​

Test Agent via API

const callResponse = await fetch(`https://blackbox.dasha.ai/api/v1/calls?agentId=${agent.agentId}`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    endpoint: "web", // For web testing
    priority: 5,
    callDeadline: new Date(Date.now() + 10 * 60 * 1000).toISOString() // 10 min from now
  })
});

const call = await callResponse.json();
console.log('Call scheduled:', call.callId);

​

Summary

1. ✅ Signed in to the BlackBox dashboard
2. ✅ Created your first AI agent with basic configuration
3. ✅ Saved and enabled the agent for live testing
4. ✅ Tested the agent using voice or text chat
5. ✅ Reviewed the conversation in the call inspector

• Refine your agent’s prompt and voice
• Add tools and integrations
• Deploy to phone or web
• Monitor performance and iterate

​

API Cross-Refs

• POST /api/v1/agents - Create a new agent
• GET /api/v1/agents - List all agents
• PUT /api/v1/agents/ - Update agent configuration
• POST /api/v1/calls - Schedule a call for testing
• GET /api/v1/voice - List available voices