Quick Start Guide

Get your first AI agent up and running in less than 5 minutes. This guide walks you through creating a working agent, testing it in the dashboard, and understanding what you’ve built.

What You’ll Build

By the end of this guide, you’ll have:

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

Time Investment: 5 minutes from start to first conversation

Prerequisites

Before you begin, make sure you have:

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)

No Phone Number Required: You can create and test agents entirely in the browser. Phone setup is only needed for real phone calls.

Navigate to blackbox.dasha.ai and sign in with your credentials. After signing in, you’ll see the Dashboard showing:

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

First Time? The dashboard will be empty initially. Don’t worry - you’ll create your first agent in the next step!

Step 2: Create Your First Agent

From the dashboard, click the “Create Agent” button. This opens the agent creation wizard.

The agent creation interface with essential configuration tabs

Set Basic Information

Start by configuring the essential details: 1. Agent Name Enter a descriptive name for your agent:

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

2. System Prompt This is the most important setting - it defines your agent’s personality and behavior. For your first agent, try this simple prompt:

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.

Pro Tip: Start with a simple, clear prompt. You can always refine it based on testing. Be specific about what you want the agent to do and how it should behave.

3. Primary Language Select your primary language from the dropdown. For most users, this will be:

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

Language Impact: This setting affects voice synthesis, speech recognition accuracy, and the cultural context of responses.

Quick Configuration with Defaults

For this quickstart, we’ll use the platform’s smart defaults: LLM (Language Model)

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

Voice Provider

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

Speech Recognition (ASR)

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

Skip Optional Tabs for Now: The agent creator has 10 tabs total. For your first agent, only the Basic Info tab is required. You can explore other tabs later.

Step 3: Save Your Agent

Once you’ve filled in the basic information:

Save Your Agent

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

Agent detail page showing configuration summary

Your newly created agent, ready for testing

Agent Status:

Newly created agents are enabled by default (toggle is ON)
You can disable an agent anytime using the “Allow this agent to take calls” toggle
Disabled agents are safe for editing without affecting live calls

Step 4: Test Your Agent

Now comes the fun part - testing your agent! From your agent’s detail page:

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

Test widget showing conversation interface

Test widget for trying your agent in the browser

Start a Conversation

You have two testing options:

Voice Test
Text Chat Test

Talk to Your Agent

Click the microphone icon or “Start Voice Call” button
Allow microphone access when prompted
Say: “Hello, what can you help me with?”
Listen to your agent’s response
Continue the conversation naturally

Voice Tips:

Speak clearly and at a normal pace
Wait for the agent to finish before speaking
Try barge-in (interrupting) to test natural flow

What to Test

Try these conversation starters to see how your agent responds: 1. Basic Greeting

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

2. Simple Question

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

3. Clarification Request

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

4. Edge Case

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

Monitor the Conversation

While testing, observe:

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

Agent Not Responding?

New agents are enabled by default, but verify the toggle is ON if you disabled it
Check that System Prompt is not empty
Refresh the page and try again
See Troubleshooting below

Step 5: Review and Next Steps

Congratulations! You’ve created and tested your first AI agent. Let’s review what you’ve accomplished.

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

To see the conversation details:

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

Call inspector showing your test conversation transcript

Call Inspector: Every conversation is automatically saved. Use the inspector to analyze agent performance and debug issues.

Improving Your Agent

Now that you have a working agent, here’s how to make it better:

Refine the System Prompt

Based on your test:

Go back to your agent’s Edit page
Open the Basic Info tab
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
Save and test again

Example Improved Prompt:

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

Want a different voice or faster responses? Change Voice Provider:

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

Voice selection interface with preview button

Choose from hundreds of voices across 5+ providers Change LLM Model:

Go to LLM Config tab
Select a different vendor (openai, groq, grok, deepseek)
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
Adjust temperature (0.5-1.0 recommended)
Save and test again

Detailed Configuration: See Creating Your First Agent for step-by-step configuration of all 10 tabs.

Add Advanced Features

Ready to level up? Explore these features: Tools (Tab 4)

Connect external APIs
Query databases
Perform calculations
Schedule appointments

Schedule (Tab 6)

Set business hours
Define timezone availability
Handle calls outside hours

Features (Tab 7)

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

Webhooks (Tab 8)

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

MCP Connections (Tab 9)

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

What’s Next?

Now that you have a working agent, choose your path:

🔧 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

Problem: Test widget shows no response or error Solutions:

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

Microphone Not Working

Problem: Can’t start voice call or agent doesn’t hear you Solutions:

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

Voice Sounds Robotic or Unnatural

Problem: Agent’s voice quality is poor Solutions:

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

Agent Gives Wrong Answers

Problem: Responses don’t match expectations Solutions:

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

Slow Response Times

Problem: Agent takes too long to respond Solutions:

Switch to Faster Model: Try gpt-4.1-mini or groq models
Enable Priority Tier: For OpenAI, turn on “Use priority tier (lower latency)”
Reduce Max Tokens: Limit response length for faster generation
Use Faster Voice: Cartesia and Dasha are optimized for low latency
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

Prefer to create agents programmatically? You can do everything via API:

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

API Documentation: See API Reference for complete endpoint documentation and code examples in multiple languages.

Summary

You’ve completed the Quick Start Guide! Here’s what you accomplished:

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

Total Time: ~5 minutes from zero to working agent Next Steps:

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

Welcome to BlackBox! 🎉

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

Introduction

Build

WebSockets

​Quick Start Guide

​What You’ll Build

​Prerequisites

​Step 1: Sign In to BlackBox

​Step 2: Create Your First Agent

​Set Basic Information

​Quick Configuration with Defaults

​Step 3: Save Your Agent

​Save Your Agent

​Step 4: Test Your Agent

​Open the Test Widget

​Start a Conversation

​What to Test

​Monitor the Conversation

​Step 5: Review and Next Steps

​What You’ve Achieved

​Review Your First Conversation

​Improving Your Agent

​Refine the System Prompt

​Customize Voice and LLM

​Add Advanced Features

​What’s Next?

​🔧 Build - Enhance Your Agent

​🧪 Test - Ensure Quality

​🚀 Deploy - Go Live

​📊 Monitor - Track Performance

​Troubleshooting

​Agent Not Responding

​Microphone Not Working

​Voice Sounds Robotic or Unnatural

​Agent Gives Wrong Answers

​Slow Response Times

​Need More Help?

​API Alternative

​Create Agent via API

​Test Agent via API

​Summary

​API Cross-Refs

Quick Start Guide

What You’ll Build

Prerequisites

Step 1: Sign In to BlackBox

Step 2: Create Your First Agent

Set Basic Information

Quick Configuration with Defaults

Step 3: Save Your Agent

Save Your Agent

Step 4: Test Your Agent

Open the Test Widget

Start a Conversation

What to Test

Monitor the Conversation

Step 5: Review and Next Steps

What You’ve Achieved

Review Your First Conversation

Improving Your Agent

Refine the System Prompt

Customize Voice and LLM

Add Advanced Features

What’s Next?

🔧 Build - Enhance Your Agent

🧪 Test - Ensure Quality

🚀 Deploy - Go Live

📊 Monitor - Track Performance

Troubleshooting

Agent Not Responding

Microphone Not Working

Voice Sounds Robotic or Unnatural

Agent Gives Wrong Answers

Slow Response Times

Need More Help?

API Alternative

Create Agent via API

Test Agent via API

Summary

API Cross-Refs