# Add Realistic Background Sounds to Conversations
Source: https://blackbox.dasha.ai/docs/advanced-features/ambient-noise
Add realistic background sounds to your Dasha BlackBox voice agent. Make conversations more natural with office, cafe, or custom ambient noise that eliminates uncanny silence.
Make conversations feel more natural. Add subtle background sounds (office, cafe, custom) that eliminate uncanny silence and increase caller trust.
**What you'll learn:** Noise level configuration, predefined sound options, custom sound upload, and best practices for authenticity.
## Why Use Ambient Noise?
### Increases Perceived Authenticity
Complete silence can trigger the "uncanny valley" effect, where conversations feel almost-but-not-quite human. Subtle background noise makes agents sound like they're calling from a real location, increasing trust and engagement.
### Reduces Caller Discomfort
Many callers find perfectly silent backgrounds unsettling. Natural ambient noise creates a more comfortable conversation environment and reduces suspicion that they're speaking with an AI system.
### Enhances Brand Professionalism
Choose background sounds that match your brand context:
* **Office sounds** for professional business calls
* **Cafe ambiance** for casual, friendly interactions
* **Custom sounds** for specific brand environments
## How to Configure Ambient Noise
### Step 1: Enable Ambient Noise
1. Open your agent's configuration
2. Navigate to the **Features** tab
3. Find **Ambient Noise** and toggle it on
### Step 2: Adjust Noise Level
Use the **Ambient Noise Level** slider to control how prominent background sounds are:
* **0.0 (Silent)**: No ambient noise
* **0.3-0.5 (Subtle)**: Barely noticeable, professional background
* **0.6-0.8 (Moderate)**: Clearly present but not distracting
* **1.0 (Prominent)**: Loud background, use sparingly
**Recommended starting point:** 0.4 for most professional applications
### Step 3: Select Background Sound
Choose from predefined ambient sounds or upload your own:
#### Predefined Options
* **Office Environment**: Keyboard typing, distant conversations, office equipment
* **Cafe Ambiance**: Background chatter, coffee machine, dishes
* **Street Sounds**: Light traffic, pedestrian activity
* **Quiet Room**: Subtle air conditioning, very minimal noise
#### Custom Sounds
Upload and use custom ambient noise files from your media library:
1. First, upload audio files to the **Media** tab in Dasha BlackBox
2. In Ambient Noise settings, select from your uploaded custom sounds
3. Recommended: Loop-friendly audio, 30-60 seconds duration
4. Audio should be subtle and not contain distinct voices or identifiable sounds
**Best practices for custom sounds:**
* Use seamless loops that don't have obvious start/end points
* Keep volume consistent throughout the audio
* Avoid sounds with recognizable patterns that repeat noticeably
* Test at different volume levels before using in production
* Upload media files (MP3, WAV, OGG supported) to the Media tab before using in Ambient Noise
### Step 4: Test and Refine
Before deploying to production:
1. Make test calls with ambient noise enabled
2. Ask colleagues to evaluate naturalness
3. Adjust volume if background sounds are too prominent or too subtle
4. Ensure ambient noise doesn't interfere with speech clarity
## Configuration Examples
> [accordion] Example: Professional Customer Support
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "ambientNoise": "enabled",
> "noiseLevel": 0.4,
> "backgroundSound": "Office Environment"
> }
> ```
>
> **Result:** Agent sounds like they're calling from a professional call center with subtle office background.
> [accordion] Example: Friendly Sales Outreach
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "ambientNoise": "enabled",
> "noiseLevel": 0.5,
> "backgroundSound": "Cafe Ambiance"
> }
> ```
>
> **Result:** Agent sounds more approachable and casual, suitable for informal sales conversations.
> [accordion] Example: Subtle Enhancement
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "ambientNoise": "enabled",
> "noiseLevel": 0.3,
> "backgroundSound": "Quiet Room"
> }
> ```
>
> **Result:** Barely noticeable background that eliminates complete silence without drawing attention.
## Common Use Cases
### Customer Service Centers
* **Configuration:** Office environment at 0.4-0.5 level
* **Why:** Sounds like a professional call center, establishes credibility
### Healthcare Appointment Reminders
* **Configuration:** Quiet room at 0.3 level
* **Why:** Professional but not distracting; calm and focused tone
### Real Estate Follow-ups
* **Configuration:** Office environment or quiet room at 0.4 level
* **Why:** Professional context for high-value conversations
### Survey and Research
* **Configuration:** Quiet room at 0.3 level
* **Why:** Minimal distraction while still eliminating artificial silence
## Technical Considerations
### Audio Quality
Ambient noise is mixed with agent speech at the configured level. Higher quality background sounds produce better results:
* **Sample rate**: 44.1kHz or 48kHz recommended
* **Bit depth**: 16-bit minimum, 24-bit preferred
* **Format**: MP3, WAV, or OGG supported
### Performance Impact
Ambient noise has minimal impact on call quality or latency. The background audio is mixed server-side and does not affect speech processing.
### Compatibility
Ambient noise works across all call types:
* ✅ Outbound phone calls
* ✅ Inbound phone calls
* ✅ Web-based voice calls
* ✅ WebSocket sessions
## Troubleshooting
### Problem: Background Noise Too Loud
**Solution:** Reduce the Ambient Noise Level slider to 0.3-0.4. Background should enhance, not overpower speech.
### Problem: Background Noise Sounds Repetitive
**Solution:** Use longer audio loops (60+ seconds) or switch to different background sound. Ensure custom audio has seamless loop points.
### Problem: Callers Mention Background Noise
**Solution:** If callers specifically comment on background sounds, reduce level to 0.3 or lower. The goal is subtle enhancement, not obvious noise.
### Problem: Speech Clarity Affected
**Solution:** Lower ambient noise level or switch to "Quiet Room" option. Speech clarity should never be compromised.
## Next steps
> [card] [Fillers](/docs/advanced-features/fillers)
>
> Add verbal hesitations during processing
> [card] [Backchannel](/docs/advanced-features/backchannel)
>
> Include active listening cues
> [card] [Talk First](/docs/advanced-features/talk-first)
>
> Control opening greetings
> [card] [Voice & Speech](/docs/create/voice-and-speech)
>
> Configure voice settings
# Add Active Listening Cues to Conversations
Source: https://blackbox.dasha.ai/docs/advanced-features/backchannel
Enable your Dasha BlackBox voice agent to produce active listening cues like 'mm-hmm', 'I see', and 'right' while callers speak. Create more engaging, natural conversations with intelligent backchannel responses.
Signal active listening with natural cues. Backchannel phrases like "mm-hmm" and "I see" reassure callers the agent is engaged, encouraging them to share more details.
**What you'll learn:** Backchannel modes (static, dynamic, LLM), phrase configuration, and frequency tuning.
## Why Use Backchannel?
### Signals Active Engagement
Backchannel responses reassure callers that the agent is listening and processing what they say. This is especially important during longer caller explanations.
### Improves Conversation Flow
Active listening cues create natural rhythm in conversations. They encourage callers to continue speaking and provide more detailed information.
### Increases Perceived Empathy
Backchannel responses make agents seem more empathetic and understanding, particularly important for support and service conversations.
### Reduces Caller Uncertainty
When callers share information and hear nothing in response, they often wonder if the agent is still listening or if the call dropped. Backchannel eliminates this uncertainty.
## How to Configure Backchannel
Dasha BlackBox offers three backchannel modes with increasing sophistication:
### Mode 1: Static (Simple)
Basic backchannel with a list of phrases and frequency control.
#### Configuration Steps
1. Open your agent's configuration
2. Navigate to the **Features** tab
3. Find **Backchannel** and toggle it on
4. Select **Static** mode
#### Settings
**Backchannel Phrases** - Add phrases the agent should use:
* "Mm-hmm"
* "I see"
* "Right"
* "Okay"
* "Got it"
* "I understand"
**Frequency** - Value from 0.0 to 1.0:
* **0.25**: Infrequent, occasional acknowledgment
* **0.5**: Moderate, balanced approach (recommended starting point)
* **0.75**: Frequent, very engaged listening
**Recommended starting configuration:**
* 5-6 varied phrases
* Frequency: 0.4-0.6
### Mode 2: Static Advanced (Precise Control)
Full control over backchannel timing and behavior.
#### Configuration Steps
1. Enable backchannel and select **Static Advanced** mode
2. Configure detailed timing parameters
> [accordion] Settings
>
> **Backchannel Phrases** - Same as Static mode, add multiple varied phrases
>
> **Minimum Voice Length** (`minLengthVoice`, seconds)
>
> * How long the caller must speak before backchannel can occur
>
> * Minimum: 1 second
>
> * Recommended: 3-5 seconds (prevents interrupting short statements)
>
> **Voice Length Deviation** (`minLengthVoiceDeviation`, 0.0-1.0)
>
> * Randomization of the minimum voice length
>
> * 0.2 deviation means timing varies ±20% for naturalness
>
> * Recommended: 0.15-0.25 for natural variation
>
> **Frequency** (`frequency`, 0.0-1.0)
>
> * Chance of backchannel occurring when conditions are met
>
> * Recommended: 0.4-0.6 (not every eligible moment gets a response)
>
> **Minimum Cooldown** (`minCooldown`, seconds)
>
> * Required time between backchannel responses
>
> * Minimum: 1 second
>
> * Prevents excessive acknowledgments
>
> * Recommended: 4-8 seconds
>
> **Cooldown Deviation** (`minCooldownDeviation`, 0.0-1.0)
>
> * Randomization of cooldown timing
>
> * Recommended: 0.2-0.3 for natural unpredictability
>
> **Example Advanced Configuration:**
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "isEnabled": true,
> "behavior": {
> "type": "staticAdvanced",
> "phrases": ["Mm-hmm", "I see", "Right", "Okay", "I understand", "Go on"],
> "minLengthVoice": 4,
> "minLengthVoiceDeviation": 0.2,
> "frequency": 0.5,
> "minCooldown": 6,
> "minCooldownDeviation": 0.25
> }
> }
> ```
### Mode 3: Smart V1 (AI-Generated)
Language model generates contextually appropriate backchannel responses.
#### Configuration Steps
1. Enable backchannel and select **Smart V1** mode
2. Optionally add instructions to guide the language model
#### Settings
**Additional Instructions** (optional)
* Guide the model's backchannel behavior
* Example: "Use professional acknowledgments appropriate for healthcare"
* Example: "Be empathetic and supportive when caller describes problems"
* Example: "Keep responses very brief—1-2 words maximum"
#### How Smart Mode Works
The language model analyzes:
* What the caller is saying
* Emotional tone of the conversation
* Appropriate moments for acknowledgment
* Contextually relevant responses
Instead of random selection from a phrase list, Smart mode generates responses like:
* "That makes sense"
* "I can help with that"
* "I understand your concern"
* "Tell me more"
**Advantages:**
* Context-aware responses
* More natural and varied
* Can adapt to conversation tone
**Considerations:**
* Slightly higher latency (generating responses takes time)
* Uses more language model resources
* May occasionally generate longer responses than desired
## Configuration Examples
> [accordion] Example: Customer Support (Static)
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "isEnabled": true,
> "behavior": {
> "type": "static",
> "phrases": [
> "Mm-hmm",
> "I see",
> "I understand",
> "Got it",
> "Okay"
> ],
> "frequency": 0.5
> }
> }
> ```
>
> **Result:** Balanced, professional acknowledgment during customer explanations.
> [accordion] Example: Healthcare (Static Advanced)
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "isEnabled": true,
> "behavior": {
> "type": "staticAdvanced",
> "phrases": [
> "Mm-hmm",
> "I understand",
> "I see",
> "Please continue"
> ],
> "minLengthVoice": 5,
> "minLengthVoiceDeviation": 0.15,
> "frequency": 0.45,
> "minCooldown": 7,
> "minCooldownDeviation": 0.2
> }
> }
> ```
>
> **Result:** Careful, measured responses appropriate for medical conversations. Longer pauses allow patients to fully explain symptoms.
> [accordion] Example: Empathetic Support (Smart V1)
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "isEnabled": true,
> "behavior": {
> "type": "smartV1",
> "additionalInstructions": "Provide empathetic, supportive acknowledgments. When the caller describes problems or frustrations, respond with understanding and validation."
> }
> }
> ```
>
> **Result:** Context-aware, empathetic responses that adapt to caller emotions and conversation content.
## Common Use Cases
### Customer Support (Problem Description)
* **Configuration:** Static mode, 0.5 frequency, empathetic phrases
* **Why:** Callers explain problems at length; backchannel shows agent is listening and cares
### Healthcare Appointments
* **Configuration:** Static Advanced, longer voice length, lower frequency (0.4)
* **Why:** Patients need space to fully describe symptoms without interruption
### Sales Discovery Calls
* **Configuration:** Static mode, 0.55-0.6 frequency, encouraging phrases
* **Why:** Encourages prospects to share more information; builds rapport
### Survey and Research
* **Configuration:** Smart V1 mode with supportive instructions
* **Why:** Contextual responses show genuine interest in respondent's answers
### Technical Support
* **Configuration:** Static mode, 0.45 frequency, understanding phrases
* **Why:** Acknowledges complex technical descriptions without interrupting troubleshooting flow
## Technical Considerations
### Voice Activity Detection
Backchannel relies on detecting when callers are speaking. The system monitors:
* Voice activity duration
* Pauses in caller speech
* Natural conversation rhythm
Backchannel occurs during natural pauses while the caller is still actively speaking (not during silent gaps between turns).
### Timing and Latency
* **Static modes**: Near-instant backchannel responses
* **Smart V1 mode**: Slight delay (0.5-1.5 seconds) for language model generation
### Speech Mixing
Backchannel responses are mixed with ongoing caller speech at reduced volume, similar to how humans layer acknowledgments over others' speech without fully interrupting.
### Compatibility
Backchannel works across all call types:
* ✅ Outbound phone calls
* ✅ Inbound phone calls
* ✅ Web-based voice calls
* ✅ All voice vendors
## Troubleshooting
### Problem: Too Many Backchannel Responses
**Solution:** Reduce frequency to 0.35-0.45 or increase minimum cooldown. Some conversations need less acknowledgment.
### Problem: Backchannel Interrupts Callers
**Solution:** Increase minimum voice length to 5-6 seconds. This ensures callers speak longer before backchannel occurs.
### Problem: Same Phrase Repeats Too Often
**Solution:** Add more varied phrases (target 6-8 different options). More variety prevents noticeable patterns.
### Problem: Backchannel Doesn't Occur
**Solution:** Verify backchannel is enabled. Increase frequency percentage. Ensure callers are speaking for minimum voice length duration.
### Problem: Smart Mode Responses Too Long
**Solution:** Add instructions like "Keep responses to 1-2 words maximum" or "Use only brief acknowledgments like 'mm-hmm' or 'I see'".
## Measuring Effectiveness
Track these metrics to evaluate backchannel impact:
* **Call completion rate** - Better engagement may improve completions
* **Average caller explanation length** - More backchannel often encourages longer, more detailed responses
* **Caller satisfaction scores** - Active listening improves satisfaction
* **Perceived agent empathy** - Survey callers about how well agent listened
## Next steps
> [card] [Fillers](/docs/advanced-features/fillers)
>
> Add verbal pauses during processing
> [card] [Ambient Noise](/docs/advanced-features/ambient-noise)
>
> Add realistic background sounds
> [card] [Talk First](/docs/advanced-features/talk-first)
>
> Control opening greetings
> [card] [Voice & Speech](/docs/create/voice-and-speech)
>
> Configure voice settings
# Route Calls to Human Operators
Source: https://blackbox.dasha.ai/docs/advanced-features/call-transfers
Transfer Dasha BlackBox voice agent calls to human operators or other systems. Warm transfers brief operators with context first. Cold transfers provide direct routing for speed. HTTP transfers use webhook-based dynamic routing for intelligent assignment.
Route calls to human operators when needed. Choose warm transfers (with context briefing), cold transfers (direct routing), or HTTP transfers (dynamic webhook-based routing).
**What you'll learn:** Transfer type comparison, configuration basics, effectiveness metrics, and troubleshooting patterns.
***
## What is a call transfer?
A call transfer hands the conversation from your AI agent to a human operator or another system. The agent recognizes when it can't resolve an issue — complex requests, escalation demands, or specialized queries — and routes the caller to someone who can help.
**When agents should transfer:**
* Customer explicitly requests a human ("I want to talk to a person")
* Issue exceeds agent's knowledge or authority
* Sensitive situations requiring human judgment
* Complex multi-step problems needing real-time troubleshooting
***
## Transfer types
Dasha BlackBox offers three transfer methods. Choose based on your needs:
| Transfer Type | Pros | Cons | Best For |
| - | - | - | - |
| **Warm Transfer** | • Operator receives context before speaking with caller • Caller doesn't re-explain situation • Agent verifies operator availability • Agent can resume if operator disconnects | • More complex to configure • Takes longer (agent briefs operator first) • Uses more resources during handoff • Requires operator to answer and engage | Personalized escalations, complex customer issues, high-value calls, situations requiring context handoff |
| **Cold Transfer** | • Simplest to configure • Fastest transfer method • Agent freed immediately • Works well for automated systems | • No spoken operator briefing • Caller may need to explain details unless the destination reads SIP context • No operator availability verification • Less personalized experience | Simple routing, IVR/menu systems, general department transfers, high-volume basic escalations |
| **HTTP Transfer** | • Dynamic routing based on real-time data • CRM and system integration • Skill-based/intelligent assignment • Custom business logic • Workforce management integration | • Requires webhook development • Most complex to implement • Depends on external system reliability • Adds latency for webhook call • More potential failure points | Dynamic routing based on availability, skill-based assignment, CRM-integrated routing, complex business rules |
## Transfer Methods
Learn about each transfer type:
* **[Warm Transfer](/docs/advanced-features/call-transfers/warm-transfer)** - Agent briefs operator before connecting caller
* **[Cold Transfer](/docs/advanced-features/call-transfers/cold-transfer)** - Direct routing without operator briefing
* **[HTTP Transfer](/docs/advanced-features/call-transfers/http-transfer)** - Webhook-based dynamic routing
> [accordion] Quick Start: Configure Transfer via API
>
> This example shows the transfer-related fields. The PUT endpoint requires the full agent configuration including `name`, `config.primaryLanguage`, `config.ttsConfig`, and `config.llmConfig`.
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> curl -X PUT "https://blackbox.dasha.ai/api/v1/agents/{agentId}" \
> -H "Authorization: Bearer YOUR_API_KEY" \
> -H "Content-Type: application/json" \
> -d '{
> "name": "Your Agent Name",
> "config": {
> "primaryLanguage": "en-US",
> "ttsConfig": { ... },
> "llmConfig": { ... },
> "features": {
> "transfer": {
> "type": "warm",
> "description": "Transfer when customer requests human agent or issue is complex",
> "endpointDestination": "+15550100",
> "callerIdMode": "userPhoneNumber",
> "interactionWithOperator": {
> "type": "smartV1",
> "additionalInstructions": "Brief operator in under 10 seconds with issue summary"
> },
> "sayPhraseToCustomer": "Let me connect you with a specialist. One moment please.",
> "continueAfterOperatorDisconnected": true,
> "failoverBehavior": {
> "continueConversation": true,
> "staticPhrase": "All representatives are busy. Let me try to help you directly."
> }
> }
> }
> }
> }'
> ```
## Send lead data with a transfer
Cold and warm transfers support `sipUui` and `sipHeaders` under
`config.features.transfer`. In **Features → Call transfer**, choose cold or warm transfer,
then fill in **Transfer SIP headers**. Leave these fields empty to keep the existing behavior.
This example shows only the transfer-related configuration; include the full agent configuration when updating an agent.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"config": {
"features": {
"transfer": {
"type": "cold",
"isEnabled": true,
"description": "Transfer callers who ask for sales",
"endpointDestination": "sip:queue@yourcompany.sip.talkdesk.com",
"sipUui": "lead-{{leadId}}",
"sipHeaders": {
"X-Lead-ID": "{{leadId}}",
"X-Caller": "{{sip_endpoint}}"
}
}
}
}
}
```
Use `"type": "warm"` with the same fields for a warm transfer. Both fixed and AI-generated
operator briefings support them. Headers also follow route retries and the warm transfer's
cold fallback.
Values use the same `{{variableName}}` templates as the agent's prompts:
* Non-null registered-call `additionalData` overrides the agent's `additionalData` for the same key.
For example, `additionalData: {"leadId": "42"}` renders `lead-{{leadId}}` as `lead-42`.
* `{{sip_endpoint}}` is the current caller endpoint (a phone number or SIP address).
* `{{call_id}}` is the BlackBox call ID.
* `{{transfer_reason}}` is the reason passed to this transfer's `transferDecision` tool call.
Templates are evaluated when the agent starts the transfer, in the caller's context.
Tool results are not automatically turned into template variables. Supply required lead
fields in `additionalData` before the call starts.
BlackBox converts the UUI text to uppercase UTF-8 hex and appends `;encoding=hex`. For example,
`lead-42` becomes `User-to-User: 6C6561642D3432;encoding=hex`. Cold transfers put the header
inside the REFER's `Refer-To` SIP URI; warm transfers send it on the operator leg's INVITE.
Use a SIP route that preserves those headers through every hop. A PSTN route may discard them,
and a `tel:` transfer destination cannot carry URI headers.
Header names must start with `X-` (case insensitive) and contain only letters, digits, hyphens or underscores
(maximum 64 characters). Configure at most 16 headers, with no duplicate names ignoring case.
UUI and header templates are limited to 1024 characters. Control characters and pipes are
rejected in configuration; rendered CR, LF and pipes are removed before sending.
Keep the rendered UUI within 256 UTF-8 bytes (128 or fewer for broader carrier compatibility).
Longer UUI payloads are truncated with a warning.
> [!NOTE]
>
> TalkDesk needs a BYOC SIP route and a Studio flow that reads UUI.
### Twilio to TalkDesk
Use a **Programmable Voice SIP Domain**, dial it over SIP, and have its voice webhook read
`SipHeader_User-to-User`. Twilio documents this UUI support for Programmable Voice SIP calls;
[BYOC trunks discard incoming custom headers before the webhook](https://www.twilio.com/docs/voice/api/sending-sip#advanced-features).
Your TwiML must re-stamp the UUI value on the next SIP leg:
```xml theme={"theme":{"light":"github-light","dark":"github-dark"}}
sip:queue@yourcompany.sip.talkdesk.com?User-to-User=6C6561642D3432%3Bencoding%3Dhex
```
Percent-encode `;`, `=` and `&` in the header value. Keep the SIP URI under 255 characters
and its header part under 1024. See Twilio's [SIP header documentation](https://www.twilio.com/docs/voice/twiml/sip#custom-headers).
## Measuring Transfer Effectiveness
Track these metrics:
* **Transfer rate**: Percentage of calls resulting in transfer
* **Transfer reason analysis**: Why are customers being transferred?
* **Transfer success rate**: Percentage of completed vs. failed transfers
* **Post-transfer satisfaction**: Are transferred customers satisfied?
* **First-call resolution impact**: How do transfers affect resolution rates?
High transfer rates may indicate:
* Agent needs more training or knowledge
* Knowledge base needs expansion
* Complex scenarios require human handling
* Transfer criteria are too broad
## Troubleshooting
### Problem: Transfers Fail Frequently
**Solution:** Verify destination numbers are correct and answering. Check network connectivity. Review failover logs for error patterns.
### Problem: Agent Transfers Too Often
**Solution:** Refine transfer description to be more specific about when transfers are appropriate. Expand knowledge base. Update system prompt with problem-solving guidance.
### Problem: Callers Drop During Transfer
**Solution:** Add hold media to maintain engagement. Set clear expectations before transfer. Reduce transfer connection time if possible.
## Next steps
> [card] [Warm Transfer](/docs/advanced-features/call-transfers/warm-transfer)
>
> Brief operators with context first
> [card] [Cold Transfer](/docs/advanced-features/call-transfers/cold-transfer)
>
> Direct routing for speed
> [card] [HTTP Transfer](/docs/advanced-features/call-transfers/http-transfer)
>
> Webhook-based dynamic routing
> [card] [Maximum Call Duration](/docs/advanced-features/max-call-duration)
>
> Control transferred call length
# Set Up Fast Direct Routing
Source: https://blackbox.dasha.ai/docs/advanced-features/call-transfers/cold-transfer
Configure cold transfers for fast, direct routing without operator briefing. Your agent transfers the call immediately and disconnects—caller goes straight to the destination with no three-way handoff. Simple to set up, ideal for high-volume basic escalations and IVR routing where speed matters more than context.
Route calls directly without briefing. Cold transfers connect callers straight to the destination — fastest option when speed matters more than context handoff.
**What you'll learn:** Cold transfer workflow, configuration steps, route options, and when to choose cold over warm transfers.
## How Cold Transfer Works
1. **Agent determines the caller needs transfer**
2. **Agent initiates transfer** to configured destination
3. **Agent disconnects immediately**
4. **Caller connects directly** with destination
Cold transfers have no spoken operator briefing, but SIP UUI and custom X-\* headers can carry lead data to the destination. See [Send lead data with a transfer](/docs/advanced-features/call-transfers#send-lead-data-with-a-transfer) for configuration, templates, encoding, and limits.
## When to Use Cold Transfer
**Best for:**
* Simple routing to departments or IVR systems
* High-volume, basic escalations
* General inquiries that don't require context
* Routing to automated systems or menus
* Situations where speed matters more than context
**Choose warm transfer instead when:**
* Complex issues requiring operator context
* High-value calls needing personalization
* Caller shouldn't have to re-explain situation
## Configuring Cold Transfer
> [accordion] Quick Start: Configure via API
>
> This example shows only the transfer-related fields. The PUT endpoint requires the full agent configuration including `name`, `config.primaryLanguage`, `config.ttsConfig`, and `config.llmConfig`.
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> curl -X PUT "https://blackbox.dasha.ai/api/v1/agents/{agentId}" \
> -H "Authorization: Bearer YOUR_API_KEY" \
> -H "Content-Type: application/json" \
> -d '{
> "name": "Your Agent Name",
> "config": {
> "primaryLanguage": "en-US",
> "ttsConfig": { ... },
> "llmConfig": { ... },
> "features": {
> "transfer": {
> "type": "cold",
> "description": "Transfer to support when customer needs general assistance",
> "endpointDestination": "+15550200",
> "transferRoutes": [
> {
> "name": "Sales",
> "description": "For pricing and purchases",
> "endpointDestinations": [{ "endpoint": "+15550201" }]
> },
> {
> "name": "Support",
> "description": "For technical help",
> "endpointDestinations": [{ "endpoint": "+15550202" }]
> }
> ],
> "failoverBehavior": {
> "continueConversation": true
> }
> }
> }
> }
> }'
> ```
### Configure via Dashboard
1. Open your agent's configuration
2. Navigate to the **Features** tab
3. Scroll to **Call Transfers** section
4. Select **Cold Transfer** type
### Step 2: Configure Basic Settings
**Transfer Description**
* Guides the language model on when to use this transfer
* Example: "Transfer to main support line when customer asks for general assistance"
* Be specific about when this transfer should be used
**Endpoint Destination**
* Phone number: `+1234567890`
* SIP URI: `sip:support@yourdomain.com`
### Step 3: Configure Transfer Routes (Optional)
Multiple destination options for intelligent routing:
**Example: Department-based routing**
* Route Name: "Sales Department"
* Description: "For pricing, quotes, and new purchases"
* Destination: `+1-555-0201`
* Route Name: "Technical Support"
* Description: "For technical problems and troubleshooting"
* Destination: `+1-555-0202`
The language model selects the appropriate route based on conversation context.
### Step 4: Configure Hold Media (Optional)
**Hold Media**
* Audio file played while transfer is being established
* Upload hold music or messages
* Example: "Please hold while we transfer your call."
* Professional experience during connection
### Step 5: Configure Failover Behavior
What happens if transfer fails (destination busy, unavailable, or doesn't answer):
**Failover Options:**
* **Continue Conversation**: Agent resumes and tries to help
* **End Call**: Call terminates gracefully
**System Message** (for agent context):
* Example: "Transfer failed. Apologize and offer alternative help."
**Static Phrase** (to caller):
* Example: "I apologize, but I'm unable to complete the transfer at this time. Please call back or visit our website for assistance."
## Configuration Example
> [accordion] Example: Complete Cold Transfer Configuration
>
> This shows the `config.features.transfer` object structure:
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "type": "cold",
> "description": "Transfer to main support line for general inquiries outside your knowledge base.",
> "endpointDestination": "+15550200",
> "transferRoutes": [
> {
> "name": "Sales-Department",
> "description": "For pricing, quotes, and new purchases",
> "endpointDestinations": [{ "endpoint": "+15550201" }]
> },
> {
> "name": "Technical-Support",
> "description": "For technical problems and troubleshooting",
> "endpointDestinations": [{ "endpoint": "+15550202" }]
> }
> ],
> "holdMedia": {
> "isEnabled": true,
> "mediaFilename": "hold-music.wav"
> },
> "failoverBehavior": {
> "continueConversation": false,
> "staticPhrase": "I apologize, but I'm unable to complete the transfer at this time. Please call back or visit our website for assistance."
> }
> }
> ```
## Common Use Cases
### General Department Routing
**Configuration:**
* Multiple routes: Sales, Support, Billing
* Hold media: "Please hold while we transfer you"
* Failover: Continue Conversation
**Why:** Simple routing where caller will explain needs to department
### IVR System Routing
**Configuration:**
* Single destination: Main IVR system
* Hold media: "Transferring you to our menu system"
* Failover: End Call
**Why:** IVR systems handle caller routing; no context needed
### After-Hours Routing
**Configuration:**
* Route to answering service or voicemail
* Hold media: "Transferring to our after-hours line"
* Failover: Continue and offer alternative
**Why:** Simple handoff to after-hours coverage
### High-Volume Basic Inquiries
**Configuration:**
* Route to general support queue
* Hold media: Professional hold music
* Failover: Continue Conversation
**Why:** Speed matters; support team will gather information
## Troubleshooting
### Problem: Callers Confused After Transfer
**Solution:** Configure agent to explain where caller is being transferred and why. Add clear hold media. Consider if warm transfer would be better for this use case.
### Problem: Transfers Fail Frequently
**Solution:** Verify destination numbers are correct and answering. Check if destinations have capacity. Configure appropriate failover behavior.
### Problem: Callers Have to Re-Explain Issues
**Solution:** Use SIP UUI or X-\* headers when the destination can read lead data, or choose a warm transfer when the operator needs a spoken briefing.
### Problem: Agent Transfers Too Often
**Solution:** Refine transfer description to be more specific. Expand agent's knowledge base. Update system prompt to encourage problem-solving before transferring.
## Next steps
> [card] [Warm Transfer](/docs/advanced-features/call-transfers/warm-transfer)
>
> Contextual operator briefing
> [card] [HTTP Transfer](/docs/advanced-features/call-transfers/http-transfer)
>
> Dynamic routing decisions
> [card] [Call Transfers Overview](/docs/advanced-features/call-transfers)
>
> Compare all transfer types
> [card] [Maximum Call Duration](/docs/advanced-features/max-call-duration)
>
> Control transferred call length
# Route Calls Dynamically with Webhooks
Source: https://blackbox.dasha.ai/docs/advanced-features/call-transfers/http-transfer
Configure HTTP transfers for dynamic, webhook-based call routing. Your agent calls your endpoint with conversation context, your system checks CRM data, availability, and skill levels, then returns the routing decision. Route premium customers to senior agents, balance workload across teams, and apply complex business logic in real-time.
Route calls dynamically using your business logic. HTTP transfers call your webhook with conversation context — your system decides the destination based on CRM data, availability, or skill requirements.
**What you'll learn:** Webhook configuration, request/response schemas, fallback handling, and dynamic routing patterns.
## How HTTP Transfer Works
1. **Agent determines the caller needs transfer**
2. **Agent calls your webhook endpoint** with conversation context
3. **Your webhook returns routing decision**: destination, type (warm/cold), and configuration
4. **Agent executes the transfer** as specified by webhook response
5. **If webhook fails**, the agent uses the fallback transfer
## When to Use HTTP Transfer
**Best for:**
* Dynamic routing based on agent availability
* Skill-based routing (route to agents with specific expertise)
* CRM-integrated routing (based on customer tier, history)
* Workload balancing across teams
* Complex business rules that change dynamically
* Geographic or language-based routing
**Choose simpler transfers when:**
* Static routing to fixed numbers
* Simple department routing
* No integration needs
## Configuring HTTP Transfer
### Step 1: Enable HTTP Transfer
1. Open your agent's configuration
2. Navigate to the **Features** tab
3. Scroll to **Call Transfers** section
4. Select **HTTP Transfer** type
### Step 2: Configure Transfer Description
**Transfer Description**
* Guides the language model on when to use this transfer
* Example: "Transfer to the best available agent based on customer priority and issue type"
* Be specific about when this dynamic routing should be triggered
> [accordion] Step 3: Configure Webhook
>
> **Webhook Endpoint**
>
> * Your API URL: `https://api.yourcompany.com/routing-decision`
>
> * Will be called when transfer is initiated
>
> **Webhook Method**
>
> * GET or POST (POST recommended for complex data)
>
> **Custom Headers**
>
> * Authentication: `Authorization: Bearer your-api-token`
>
> * API keys, custom metadata
>
> * Example:
>
> ```
> Authorization: Bearer sk_live_abc123xyz789
> Content-Type: application/json
> ```
**Query Parameters** (optional)
* Parameters passed with every request. Values accept variables.
* Example: `api_version=v1&source=voice_agent`
**Call data in the request** (optional)
* The webhook URL, header values and query parameters accept variables such as `{{callAdditionalData.customerId}}` or `{{transferReason}}`
* Example: `https://api.yourcompany.com/routing/{{callAdditionalData.customerId}}`
* Set the method, query parameters and body under **Advanced request settings**
* See [Request Templating](/docs/webhooks-and-events/webhook-request-templating) for all variables and rules
> [accordion] Step 4: Webhook Request Format
>
> Your webhook receives a `TransferWebHookPayload` with conversation context:
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "type": "TransferWebHookPayload",
> "status": "running",
> "callId": "call_abc123",
> "agentId": "agent_xyz789",
> "orgId": "org_123",
> "endpoint": "+1234567890",
> "transferReason": "Customer requested to speak with a billing specialist",
> "transcription": [
> {
> "speaker": "ai",
> "name": "Agent",
> "text": "Hello, how can I help you today?",
> "startTime": "2026-04-10T10:00:00Z",
> "endTime": "2026-04-10T10:00:03Z"
> },
> {
> "speaker": "human",
> "name": "Customer",
> "text": "I have a question about my bill. Can I speak with someone from billing?",
> "startTime": "2026-04-10T10:00:04Z",
> "endTime": "2026-04-10T10:00:08Z"
> }
> ],
> "callAdditionalData": {
> "customerId": "cust_456",
> "priority": "high"
> },
> "agentAdditionalData": {},
> "sip": {
> "fromUser": "+1234567890",
> "fromDomain": "sip.provider.com",
> "toUser": "+1987654321",
> "toDomain": "blackbox.dasha.ai",
> "diversion": [],
> "xHeaders": { "X-Account-Id": "acct-42" },
> "uui": { "raw": "616363742D3432;encoding=hex", "data": "acct-42", "encoding": "hex" },
> "callId": "a84b4c76e66710@sip.provider.com"
> }
> }
> ```
**Request Fields:**
* `type`: Always `"TransferWebHookPayload"` for transfer webhooks
* `status`: Always `"running"` (call is active)
* `callId`: Unique identifier for this call
* `agentId`: Your voice agent's ID
* `orgId`: Your organization ID
* `endpoint`: Phone number or SIP address of the caller
* `transferReason`: AI-generated explanation of why transfer is needed
* `transcription`: Full conversation history with speaker, text, and timestamps
* `callAdditionalData`: Custom data passed when the call was created
* `agentAdditionalData`: Custom data configured on the agent
* `sip`: The SIP dialog of the phone call: From and To addresses, diversion headers, custom X- headers, the User-to-User header and the Call-ID, as described in [Webhook Events](/docs/webhooks-and-events/webhook-events); absent for web calls and chats
> [accordion] Step 5: Webhook Response Format
>
> Your webhook returns a `TransferWebhookResponse` with routing instructions:
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "isSuccess": true,
> "message": "Routing to billing department",
> "transfer": {
> "type": "warm",
> "description": "Transfer to billing specialist",
> "endpointDestination": "+15550150",
> "sayToCustomer": "Connecting you with our billing specialist",
> "operatorInteraction": {
> "type": "static",
> "staticPhrase": "High priority customer with billing question"
> },
> "continueAfterOperatorDisconnect": true
> }
> }
> ```
>
> For a cold transfer response:
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "isSuccess": true,
> "transfer": {
> "type": "cold",
> "description": "Transfer to support queue",
> "endpointDestination": "+15550200"
> }
> }
> ```
>
> To cancel the transfer and continue the conversation:
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "isSuccess": false,
> "message": "No agents available, continue with AI"
> }
> ```
**Response Fields:**
**Required:**
* `isSuccess`: Boolean - whether to proceed with transfer
* `transfer`: Transfer configuration object (required when `isSuccess` is true)
**Transfer Object (required when isSuccess is true):**
* `type`: `"warm"` or `"cold"`
* `description`: Description for logging/debugging
* `endpointDestination`: Phone number or SIP URI to transfer to
**Optional (warm transfer only):**
* `sayToCustomer`: What agent tells customer before transfer
* `operatorInteraction`: How agent briefs the operator (static phrase or smart mode)
* `continueAfterOperatorDisconnect`: Boolean - can agent resume if operator hangs up?
**Optional:**
* `message`: Context message for logging/debugging
### Step 6: Configure Fallback Transfer
If webhook fails (timeout, error, unreachable), use fallback:
**Fallback Transfer Type**
* Warm or Cold
**Fallback Destination**
* Backup phone number: `+1-555-0100`
**Fallback Configuration**
* For warm: Operator message, customer message
* For cold: Customer message
**Failover Behavior** (if fallback also fails)
* Continue Conversation: Agent resumes
* End Call: Call terminates gracefully
**Failover Messages:**
* System message for agent context
* Static phrase for caller
## Configuration Example
> [accordion] Example: Complete HTTP Transfer Configuration
>
> This shows the `config.features.transfer` object structure for HTTP transfer:
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "type": "http",
> "description": "Transfer to the most appropriate agent based on customer tier, issue type, and agent availability.",
> "webhook": {
> "url": "https://api.yourcompany.com/v1/routing",
> "headers": {
> "Authorization": "Bearer sk_live_abc123xyz789"
> },
> "customSettings": {
> "httpMethod": "POST"
> }
> },
> "fallback": {
> "type": "warm",
> "description": "Fallback transfer when webhook unavailable",
> "endpointDestination": "+15550100",
> "sayToCustomer": "Let me connect you with our team",
> "operatorInteraction": {
> "type": "static",
> "staticPhrase": "General transfer - webhook unavailable"
> }
> },
> "failoverBehavior": {
> "continueConversation": true,
> "staticPhrase": "I'm sorry, I'm having trouble connecting you right now. Let me try to help you directly."
> }
> }
> ```
## Webhook Implementation Examples
> [accordion] Skill-Based Routing
>
> Route to agents with specific expertise:
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> app.post('/routing-decision', async (req, res) => {
> const { transferReason, transcription, callAdditionalData } = req.body;
>
> // Determine issue type from conversation
> const conversationText = transcription.map(t => t.text).join(' ');
> const issueType = categorizeIssue(conversationText);
>
> // Find available agent with matching skill
> const agent = await findAvailableAgent({
> skill: issueType,
> available: true
> });
>
> res.json({
> isSuccess: true,
> message: `Routing to ${issueType} specialist`,
> transfer: {
> type: "warm",
> description: `${issueType} transfer`,
> endpointDestination: agent.phoneNumber,
> sayToCustomer: "Connecting you with a specialist",
> operatorInteraction: {
> type: "static",
> staticPhrase: `${issueType} issue - ${transferReason}`
> }
> }
> });
> });
> ```
> [accordion] Priority-Based Routing
>
> VIP customers get routed to senior agents:
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> app.post('/routing-decision', async (req, res) => {
> const { callAdditionalData, endpoint, transferReason } = req.body;
>
> // Check customer tier using endpoint (caller's phone number)
> const customer = await crm.getCustomer(endpoint);
>
> if (customer.tier === 'VIP') {
> // Route to senior agent
> const seniorAgent = await getAvailableSeniorAgent();
> return res.json({
> isSuccess: true,
> transfer: {
> type: "warm",
> description: "VIP customer transfer",
> endpointDestination: seniorAgent.phone,
> sayToCustomer: "Connecting you with our senior specialist",
> operatorInteraction: {
> type: "static",
> staticPhrase: `VIP customer ${customer.name} - priority handling`
> }
> }
> });
> }
>
> // Standard routing
> const agent = await getNextAvailableAgent();
> res.json({
> isSuccess: true,
> transfer: {
> type: "cold",
> description: "Standard support transfer",
> endpointDestination: agent.phone
> }
> });
> });
> ```
> [accordion] Workload Balancing
>
> Route to least busy agent:
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> app.post('/routing-decision', async (req, res) => {
> const { transferReason } = req.body;
>
> // Query all agents and their current call loads
> const agents = await getAgentWorkloads();
>
> // Find agent with lowest current workload
> const bestAgent = agents.reduce((min, agent) =>
> agent.activeCalls < min.activeCalls ? agent : min
> );
>
> res.json({
> isSuccess: true,
> transfer: {
> type: "warm",
> description: "Load-balanced transfer",
> endpointDestination: bestAgent.phone,
> sayToCustomer: "Connecting you with the next available agent",
> operatorInteraction: {
> type: "static",
> staticPhrase: "New customer inquiry"
> }
> }
> });
> });
> ```
> [accordion] Geographic Routing
>
> Route to agents in customer's region:
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> app.post('/routing-decision', async (req, res) => {
> const { endpoint } = req.body;
>
> // Determine caller's region from phone number
> const region = getRegionFromNumber(endpoint);
>
> // Find available agent in same region
> const localAgent = await findAgentByRegion(region);
>
> res.json({
> isSuccess: true,
> transfer: {
> type: "warm",
> description: "Geographic routing transfer",
> endpointDestination: localAgent.phone,
> sayToCustomer: "Connecting you with a local specialist",
> operatorInteraction: {
> type: "static",
> staticPhrase: `Customer from ${region}`
> }
> }
> });
> });
> ```
## Use Cases
### Skill-Based Routing
Route to agents with specific expertise (billing, technical, sales) based on conversation content. Your webhook analyzes the issue and matches with qualified available agents.
### Priority Routing
VIP customers get immediate routing to senior agents. Standard customers follow normal queues. Your webhook checks customer tier in CRM and routes accordingly.
### Geographic Routing
Route to agents in customer's timezone or region. Your webhook uses caller location data to find local agents.
### Workload Balancing
Route to least busy available agent. Your webhook queries real-time agent workload and routes to maintain balance.
### Language Matching
Route to agents who speak customer's language. Your webhook detects language from conversation and matches with agent skills.
### Business Hours Routing
Different routing during business hours vs. after hours. Your webhook checks time and routes to appropriate team or service.
## Troubleshooting
### Problem: Webhook Times Out
**Solution:** Optimize webhook response time (target under 2 seconds). Add caching for common queries. Configure appropriate timeout and fallback transfer. Consider pre-computing routing decisions.
### Problem: Webhook Returns Errors
**Solution:** Check webhook logs for error details. Verify webhook signature/authentication. Ensure response format matches specification. Test webhook with sample payloads.
### Problem: Fallback Transfer Used Often
**Solution:** Investigate webhook reliability. Check webhook uptime and error rates. Verify network connectivity between Dasha BlackBox and webhook. Add monitoring and alerts.
### Problem: Wrong Agent Receives Transfer
**Solution:** Review webhook routing logic. Test with various conversation scenarios. Verify conversation\_summary provides enough context. Add logging to debug routing decisions.
## Next steps
> [card] [Warm Transfer](/docs/advanced-features/call-transfers/warm-transfer)
>
> What HTTP transfer returns for warm routing
> [card] [Cold Transfer](/docs/advanced-features/call-transfers/cold-transfer)
>
> What HTTP transfer returns for cold routing
> [card] [Call Transfers Overview](/docs/advanced-features/call-transfers)
>
> Compare all transfer types
> [card] [Webhooks](/docs/webhooks-and-events/webhooks-overview)
>
> Receive call events
# Brief Operators Before Connecting Callers
Source: https://blackbox.dasha.ai/docs/advanced-features/call-transfers/warm-transfer
Configure warm transfers where the AI agent briefs the operator before connecting the caller, providing context and ensuring smooth handoffs for personalized customer service.
Brief operators before connecting callers. Warm transfers let your agent speak with the operator first — providing context so customers don't need to re-explain their situation.
**What you'll learn:** Warm transfer workflow, configuration steps, operator briefing scripts, and best practices for context handoffs.
Warm transfers can also send lead data using SIP UUI and custom X-\* headers. See [Send lead data with a transfer](/docs/advanced-features/call-transfers#send-lead-data-with-a-transfer) for configuration, templates, encoding, and limits.
## How Warm Transfer Works
1. **Agent determines the caller needs transfer** (based on conversation and configured description)
2. **Agent calls the operator** at configured endpoint
3. **Agent speaks with operator** to provide context about the caller and situation
4. **Agent bridges the call** - all three parties are connected
5. **Operator handles the call** - when the operator disconnects, the agent can optionally resume the conversation with the caller
## When to Use Warm Transfer
**Best for:**
* Complex customer issues requiring context
* High-value calls where personalization matters
* Situations where operator needs background before speaking
* Escalations where caller shouldn't repeat information
**Choose cold transfer instead when:**
* Simple routing to departments or menus
* High-volume, basic escalations
* Speed matters more than context
## Configuring Warm Transfer
> [accordion] Quick Start: Configure via API
>
> This example shows only the transfer-related fields. The PUT endpoint requires the full agent configuration including `name`, `config.primaryLanguage`, `config.ttsConfig`, and `config.llmConfig`.
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> curl -X PUT "https://blackbox.dasha.ai/api/v1/agents/{agentId}" \
> -H "Authorization: Bearer YOUR_API_KEY" \
> -H "Content-Type: application/json" \
> -d '{
> "name": "Your Agent Name",
> "config": {
> "primaryLanguage": "en-US",
> "ttsConfig": { ... },
> "llmConfig": { ... },
> "features": {
> "transfer": {
> "type": "warm",
> "description": "Transfer when customer requests human agent or issue is complex",
> "endpointDestination": "+15550100",
> "callerIdMode": "userPhoneNumber",
> "interactionWithOperator": {
> "type": "smartV1",
> "additionalInstructions": "Brief operator in under 10 seconds. Include customer name and issue summary."
> },
> "sayPhraseToCustomer": "Let me connect you with a specialist. One moment please.",
> "continueAfterOperatorDisconnected": true,
> "continueRecordingInTransfer": true,
> "failoverBehavior": {
> "continueConversation": true,
> "staticPhrase": "All specialists are busy. Let me try to help you directly."
> }
> }
> }
> }
> }'
> ```
### Configure via Dashboard
1. Open your agent's configuration
2. Navigate to the **Features** tab
3. Open **Call transfer**
4. Select **Warm**
### Step 2: Configure Basic Settings
**Transfer Description**
* Guides the language model on when to use this transfer
* Example: "Transfer to a human agent when the customer explicitly requests to speak with a person, or when the issue is too complex for you to handle."
* Be specific about triggers: explicit requests, complex scenarios, frustrated customers, etc.
**Endpoint Destination**
* Phone number: `+1234567890`
* SIP URI: `sip:operator@yourdomain.com`
**Caller ID Mode**
* **Agent Phone Number**: Operator sees agent's number (default)
* **Original Caller Number**: Operator sees caller's number
### Step 3: Configure Operator Interaction
Choose how the agent communicates with the operator before bridging:
**Static Mode**
* Predefined phrase spoken to operator
* Example: "I have a customer on the line with a question about billing. I'm connecting you now."
* Fast and consistent
* Good for simple context
**Smart Mode**
* Language model generates context based on conversation
* Agent summarizes caller's situation intelligently
* Example generated phrase: "Hi, I have John Smith on the line. He's experiencing an issue with his recent invoice and needs help understanding the charges. I'm connecting him now."
* More personalized and contextual
* Best for complex scenarios
**Optional Instructions for Smart Mode:**
* Guide the language model's summary style
* Example: "Keep operator briefing under 10 seconds. Focus on the specific problem and any relevant account details."
### Step 4: Configure Caller Experience
**Say Phrase to Customer** (optional)
* What agent says to caller before transfer
* Example: "I'm connecting you with a specialist who can help you with that. Please hold for just a moment."
* Manages caller expectations during transfer
**Continue After Operator Disconnect**
* Toggle: Yes or No
* If enabled: Agent can resume conversation if operator hangs up
* If disabled: Call ends when operator disconnects
* Recommended: Enable for customer service scenarios
### Step 5: Configure Recording and Recognition
**Continue Recording During Transfer**
* Toggle: Yes or No
* If enabled: Call recording continues while transferred
* Useful for quality assurance and compliance
**Continue Speech Recognition**
* Toggle: Yes or No
* If enabled: Speech-to-text remains active during transfer
* Useful for transcript completeness
### Step 6: Configure Three-Way Announcement (Optional)
Speak to both caller and operator simultaneously right before bridging:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
"threewayMessaging": {
"type": "static",
"phrase": "Connecting you now."
}
```
Or use AI to generate a contextual announcement:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
"threewayMessaging": {
"type": "smartV1",
"additionalInstructions": "Keep it brief and professional"
}
```
Both parties hear the same message at the exact moment of connection — useful for compliance notices or smooth handoff transitions.
### Step 7: Configure Hold Media (Optional)
In **Features > Call transfer > Warm**, enable **Hold music**, choose an uploaded file in **Hold music file**, then click **Save changes**.
For API configuration, set `holdMedia.isEnabled` to `true` and `holdMedia.mediaFilename` to the uploaded file's name.
**Hold Media**
* Audio file played while transfer is being established
* Upload hold music or messages
* Example: "Please wait while we connect you with an agent."
* Improves experience during connection delays
### Step 8: Configure Transfer Routes (Optional)
Multiple transfer destinations for intelligent routing:
**Example: Department-based routing**
* Route Name: "Billing Department"
* Description: "Use for billing and payment questions"
* Destination: `+1234567891`
* Route Name: "Technical Support"
* Description: "Use for technical issues and troubleshooting"
* Destination: `+1234567892`
The language model selects the appropriate route based on conversation context.
### Step 9: Configure Failover Behavior
What happens if transfer fails (number busy, unavailable, or doesn't answer):
**Try another transfer** (optional): turn on **Cold transfer to the same number** (`fallbackToColdTransfer: true`, off by default). If the operator does not answer, the briefing fails, or the operator call cannot be placed, the agent cold-transfers the caller to the same destination. If that transfer also fails, the failover options below apply. The fallback runs on phone calls only: a cold transfer is a SIP REFER, which a web call can't take, so web calls go straight to the failover options.
**Failover Options:**
* **Continue Conversation**: Agent resumes and tries to help
* **End Call**: Call terminates gracefully
**System Message** (for agent context):
* Example: "The operator is unavailable. Apologize and offer to help or schedule a callback."
**Static Phrase** (to caller):
* Example: "I apologize, but all our representatives are currently assisting other customers. Would you like me to help you, or can I schedule a callback?"
## Configuration Example
> [accordion] Example: Complete Warm Transfer Configuration
>
> This shows the `config.features.transfer` object structure for warm transfer:
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "type": "warm",
> "description": "Transfer when customer explicitly requests a human agent, or when their issue requires account-level access you don't have.",
> "endpointDestination": "+15550100",
> "callerIdMode": "userPhoneNumber",
> "interactionWithOperator": {
> "type": "smartV1",
> "additionalInstructions": "Brief the operator in under 10 seconds. Mention customer name, issue category, and any relevant account details."
> },
> "sayPhraseToCustomer": "Let me connect you with someone who can help with that immediately. One moment please.",
> "continueAfterOperatorDisconnected": true,
> "continueRecordingInTransfer": true,
> "continueRecognitionInTransfer": true,
> "holdMedia": {
> "isEnabled": true,
> "mediaFilename": "hold-music.wav"
> },
> "fallbackToColdTransfer": true,
> "failoverBehavior": {
> "continueConversation": true,
> "systemMessage": "Operator unavailable. Offer to help or schedule callback.",
> "staticPhrase": "I'm sorry, our specialists are all busy right now. I can try to help you, or I can schedule a callback. Which would you prefer?"
> }
> }
> ```
>
> Example using static operator interaction instead of smart mode:
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "type": "warm",
> "description": "Transfer to billing department",
> "endpointDestination": "+15550100",
> "interactionWithOperator": {
> "type": "static",
> "sayPhraseToOperator": {
> "phrase": "I have a customer on the line with a billing question. Connecting now.",
> "beforeOperator": false
> },
> "waitFirstAnswerFromOperator": true,
> "waitChecksTimeoutInS": 4
> },
> "sayPhraseToCustomer": "Connecting you to billing now.",
> "continueAfterOperatorDisconnected": false
> }
> ```
## Common Use Cases
### Customer Service Escalations
**Configuration:**
* Smart Mode with instructions: "Brief operator about customer issue and sentiment"
* Continue After Disconnect: Yes
* Hold media: Professional hold music
**Why:** Complex issues need context; agent can help if transfer fails
### VIP Customer Handling
**Configuration:**
* Smart Mode with instructions: "Mention customer VIP status, name, and specific request"
* Caller ID: Original Caller Number
* Hold media: Premium hold experience
**Why:** VIP customers expect personalized, seamless service
### Technical Support Escalations
**Configuration:**
* Smart Mode with instructions: "Describe technical issue, steps already attempted, and error codes mentioned"
* Continue Recording: Yes
* Continue Speech Recognition: Yes
**Why:** Operators need technical context; recording captures full troubleshooting session
## Troubleshooting
### Problem: Operators Lack Context
**Solution:** Switch from Static to Smart Mode. Improve Smart Mode instructions to be more specific about what information operators need. Review example transfers to identify missing context.
### Problem: Operator Briefings Too Long
**Solution:** Update Smart Mode instructions to emphasize brevity (e.g., "Keep briefing under 10 seconds"). Use Static Mode for simpler scenarios.
### Problem: Transfers Take Too Long
**Solution:** Warm transfers inherently take longer than cold transfers. Consider cold transfer for less complex scenarios. Optimize hold media to keep callers engaged.
### Problem: Operator Doesn't Answer
**Solution:** Verify endpoint is correct and operational. Turn on **Cold transfer to the same number** so the caller still reaches the destination without a briefing. Configure appropriate failover behavior. Enable "Continue After Disconnect" so agent can help.
## Next steps
> [card] [Cold Transfer](/docs/advanced-features/call-transfers/cold-transfer)
>
> Faster, simpler routing
> [card] [HTTP Transfer](/docs/advanced-features/call-transfers/http-transfer)
>
> Dynamic routing decisions
> [card] [Call Transfers Overview](/docs/advanced-features/call-transfers)
>
> Compare all transfer types
> [card] [Maximum Call Duration](/docs/advanced-features/max-call-duration)
>
> Control transferred call length
# Add Natural Verbal Pauses During Processing
Source: https://blackbox.dasha.ai/docs/advanced-features/fillers
Add natural verbal pauses like 'um', 'let me check that', and 'one moment' to your Dasha BlackBox voice agent during processing delays. Research shows these fillers reduce perceived wait time by up to 40%, making conversations feel more human.
Reduce perceived wait times with verbal pauses. Filler phrases like "let me check that" make delays feel up to 40% shorter and signal the agent is actively working.
**What you'll learn:** Filler phrase configuration, recommended phrases, and strategies for natural-sounding processing delays.
## Why Use Fillers?
### Reduce Perceived Wait Time
Research shows verbal acknowledgment during pauses reduces perceived wait time by up to 40%. Saying "let me check that" feels shorter than 3 seconds of silence.
### Increase Conversation Naturalness
Humans rarely speak in perfectly polished sentences. Natural hesitations and thinking pauses are part of authentic conversation. Fillers make your agent sound less robotic.
### Maintain Caller Engagement
Silence can cause callers to wonder if the call dropped or the agent stopped listening. Fillers reassure callers the agent is actively processing their request.
### Set Appropriate Expectations
Phrases like "let me look that up" or "give me just a moment" signal that the agent is working on something, preparing callers for a brief pause.
## How to Configure Fillers
### Step 1: Enable Fillers
1. Open your agent's configuration
2. Navigate to the **Features** tab
3. Find **Fillers** and toggle it on
### Step 2: Configure Filler Phrases
Add the verbal pauses your agent should use:
1. Click **Add Filler Phrase**
2. Enter a natural hesitation phrase
3. Repeat to add multiple phrases (agent will randomly select)
#### Recommended Filler Phrases
The agent will randomly select from your configured filler phrases whenever a response is delayed. Include a variety of phrases for natural variation:
**Examples:**
* "Um"
* "Uh"
* "Hmm"
* "Let me see"
* "One moment"
* "Let me check that for you"
* "Let me look that up"
* "Give me just a moment"
* "Let me think about that"
* "Just a second"
**Recommendation:** Include 5-8 varied phrases so the agent doesn't repeat the same filler too frequently. Mix shorter and longer phrases to match your agent's personality.
### Step 3: Test Filler Behavior
Make test calls to verify filler behavior:
1. Have conversations with your agent
2. Listen for fillers when responses are delayed
3. Verify fillers sound natural and appropriate for your agent's personality
4. Confirm fillers don't interrupt conversation flow
5. Ensure fillers reduce awkward silence
## Configuration Examples
> [accordion] Example: Professional Support Agent
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "fillers": "enabled",
> "phrases": [
> "Let me check that for you",
> "One moment please",
> "Let me look that up",
> "Just a moment",
> "Let me find that information"
> ]
> }
> ```
>
> **Result:** Professional, helpful tone during information retrieval.
> [accordion] Example: Conversational Sales Agent
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "fillers": "enabled",
> "phrases": [
> "Um, let me see",
> "Hmm, good question",
> "Let me think about that",
> "Give me just a second",
> "Let me check on that"
> ]
> }
> ```
>
> **Result:** Casual, conversational tone with natural hesitations.
> [accordion] Example: Minimal Fillers
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "fillers": "enabled",
> "phrases": [
> "One moment",
> "Just a second",
> "Let me check"
> ]
> }
> ```
>
> **Result:** Minimal but effective acknowledgment during pauses.
## Common Use Cases
### Professional Support Agents
* **Filler style:** Polite and helpful
* **Example phrases:** "Let me check that for you", "One moment please", "Let me look that up"
* **Why:** Maintains professional tone during any response delays
### Conversational Sales Agents
* **Filler style:** Casual and natural
* **Example phrases:** "Hmm, let me think", "Um, let me see", "That's a good question"
* **Why:** Creates authentic, human-like conversation with natural hesitations
### Minimal/Efficient Agents
* **Filler style:** Brief acknowledgments
* **Example phrases:** "One moment", "Just a second", "Let me check"
* **Why:** Acknowledges delays without excessive talking
### Friendly Service Agents
* **Filler style:** Warm and reassuring
* **Example phrases:** "Let me find that for you", "Give me just a moment", "Let me see here"
* **Why:** Keeps callers comfortable during any pauses in conversation
## Technical Considerations
### Response Delays
The agent uses fillers whenever response is delayed, regardless of the reason (LLM processing, knowledge base searches, API calls, or any other delay).
For very short delays (under 1 second), fillers may not be used. For very long delays (over 10 seconds), consider optimizing your systems.
### Speech Timing
Fillers are spoken using the same voice and settings as your agent's primary voice. They blend naturally into the conversation audio stream.
### Compatibility
Fillers work across all call types and integrations:
* ✅ Outbound phone calls
* ✅ Inbound phone calls
* ✅ Web-based voice calls
* ✅ All voice vendors and models
## Troubleshooting
### Problem: Fillers Used Too Frequently
**Solution:** This usually indicates your agent is experiencing slow processing. Optimize knowledge base queries, external APIs, or consider using a faster language model. Fillers are symptoms of delays, not the cause.
### Problem: Fillers Sound Awkward
**Solution:** Review your filler phrase list. Remove overly formal or informal phrases that don't match your agent's personality. Test different phrases to find natural-sounding options.
### Problem: Same Filler Repeats Often
**Solution:** Add more filler phrases (aim for 6-8 varied options). More variety prevents noticeable repetition.
### Problem: Fillers Don't Appear
**Solution:** Verify fillers are enabled and you have phrases configured. Fillers only appear during response delays—if your agent responds instantly, fillers won't be used.
## Measuring Effectiveness
Track these metrics to evaluate filler impact:
* **Perceived wait time** - Survey callers about wait time perception
* **Call completion rate** - Compare rates before/after enabling fillers
* **Caller interruptions** - Fewer "hello? are you there?" interruptions
* **Conversation naturalness ratings** - Improved naturalness scores
## Next steps
> [card] [Backchannel](/docs/advanced-features/backchannel)
>
> Add active listening cues while callers speak
> [card] [Ambient Noise](/docs/advanced-features/ambient-noise)
>
> Add realistic background sounds
> [card] [Talk First](/docs/advanced-features/talk-first)
>
> Control opening greetings
> [card] [Voice & Speech](/docs/create/voice-and-speech)
>
> Configure voice settings
# Handle Voicemail and Automated Phone Systems
Source: https://blackbox.dasha.ai/docs/advanced-features/ivr-detection
Detect when Dasha BlackBox voice agent calls reach automated systems or voicemail. Leave professional messages, navigate menus with DTMF tones, or disconnect gracefully.
Handle automated systems intelligently. IVR detection identifies when calls reach voicemail or phone trees — your agent can leave messages, navigate menus, or disconnect and retry later.
**What you'll learn:** Detection configuration, voicemail behavior, DTMF navigation, and outbound campaign optimization.
## Why Use IVR Detection?
### Optimize Outbound Campaigns
Reaching voicemail or automated systems wastes time and resources when your goal is human contact. IVR detection allows you to:
* Disconnect quickly and try again later
* Leave a professional message and mark the contact for follow-up
* Navigate menus to reach the right department
### Professional Voicemail Handling
Instead of awkwardly attempting conversation with voicemail, leave a well-crafted message designed for voicemail boxes.
### Improve Contact Rates
By identifying and handling automated systems efficiently, you can:
* Retry contacts at different times
* Focus resources on reaching actual humans
* Improve overall campaign success rates
### Navigate Complex Phone Systems
Attempt to reach human operators by automatically navigating IVR menus with DTMF tones (dial pad presses).
## How to Configure IVR Detection
### Step 1: Enable IVR Detection
1. Open your agent's configuration
2. Navigate to the **Features** tab
3. Find **IVR Detection** and toggle it on
### Step 2: Configure Channel-Specific Settings
Control where IVR detection is active:
**Outbound Calls** (Phone)
* Default: Enabled
* When your agent calls outbound phone numbers
* Most common use case for IVR detection
**Inbound Calls** (Phone)
* Default: Disabled
* When callers phone your agent
* Rarely needed (inbound callers are usually human)
**Chat Sessions**
* Default: Disabled (testing only)
* Text-based chat interactions
* IVR detection not typically relevant
**Web Calls**
* Default: Disabled (testing only)
* Browser-based voice calls
* IVR detection not typically relevant
**Recommended:** Enable for outbound calls only.
### Step 3: Configure IVR Navigation (Optional)
**IVR Navigation Toggle**
* Enable if you want the agent to attempt navigating automated menus
* Agent will try pressing dial pad numbers to reach human operators
* Uses DTMF tone signals to interact with IVR systems
**When to enable:**
* Calling businesses with complex phone trees
* Want to reach specific departments automatically
* Willing to spend time navigating before reaching humans
**When to disable:**
* Quick connect/disconnect preferred
* Don't want agent spending time in phone menus
* Target numbers don't have complex IVR systems
### Step 4: Configure Detection Behavior
Choose how the agent responds when IVR/voicemail is detected:
#### Option 1: Continue (No AMD)
**What it does:** Disables answering machine detection; agent treats all answers as human
**When to use:**
* Detection isn't needed for your use case
* All calls should proceed normally regardless of who/what answers
* Testing or specific scenarios where IVR detection causes issues
#### Option 2: Hang Up
**What it does:** Immediately disconnects when voicemail or IVR is detected
**When to use:**
* Reaching humans is critical; voicemail is wasted effort
* Plan to retry contacts at different times
* Want to maximize human contact attempts
* **Configuration:**
* Simply select "Hang Up" behavior
* No additional settings needed
* Agent disconnects silently and immediately
#### Option 3: Leave Message
**What it does:** Agent leaves a voicemail message when detection occurs
**Configuration modes:**
**Static Mode:**
* Predefined voicemail message
* Supports variable interpolation: `{{caller_name}}`, `{{company_name}}`, etc.
* Example: "Hi `{{caller_name}}`, this is `{{agent_name}}` from `{{company_name}}`. I'm calling about your appointment scheduled for tomorrow. Please call us back at `{{phone_number}}`. Thank you!"
**Smart Mode:**
* Language model generates contextual voicemail based on call purpose
* More dynamic and personalized
* Optionally provide additional instructions to guide message generation
* Example instructions: "Keep the message under 20 seconds. Mention the appointment time and provide a callback number."
**When to use Static:**
* Consistent, predictable messages
* Regulatory or compliance requirements for exact wording
* Simple, templated voicemail
**When to use Smart:**
* Personalized, context-aware messages
* Call reasons vary significantly
* Want natural, conversational voicemail
## Configuration Examples
> [accordion] Example: Aggressive Human-Only Outreach
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "ivrDetection": "enabled",
> "channels": "Outbound Calls Only",
> "ivrNavigation": "disabled",
> "behavior": "Hang Up"
> }
> ```
>
> **Rationale:** Disconnect immediately when voicemail/IVR detected. Retry contacts at different times. Maximize time spent with humans.
> [accordion] Example: Professional Voicemail Campaign
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "ivrDetection": "enabled",
> "channels": "Outbound Calls Only",
> "ivrNavigation": "disabled",
> "behavior": "Leave Message (Static)",
> "message": "Hello `{{customer_name}}`, this is `{{agent_name}}` calling from `{{company_name}}` regarding your upcoming appointment on `{{appointment_date}}`. Please call us back at `{{callback_number}}` to confirm. Thank you!"
> }
> ```
>
> **Rationale:** Leave consistent, professional message when reaching voicemail. Simple, templated approach.
> [accordion] Example: Contextual Voicemail
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "ivrDetection": "enabled",
> "channels": "Outbound Calls Only",
> "ivrNavigation": "disabled",
> "behavior": "Leave Message (Smart)",
> "additionalInstructions": "Leave a brief, friendly message under 20 seconds. Mention why you're calling and provide the callback number clearly. End with 'Have a great day!'"
> }
> ```
>
> **Rationale:** Personalized voicemail adapted to conversation context. Natural, friendly tone.
> [accordion] Example: Navigate Business Phone Systems
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "ivrDetection": "enabled",
> "channels": "Outbound Calls Only",
> "ivrNavigation": "enabled",
> "behavior": "Leave Message (Smart)",
> "additionalInstructions": "If you reach a human after navigation, introduce yourself and explain the call purpose. If unable to reach a human, leave a voicemail."
> }
> ```
>
> **Rationale:** Attempt to navigate through automated menus to reach departments or operators. Leave message if navigation fails.
## Common Use Cases
### Appointment Reminder Campaigns
* **Configuration:** Hang up on voicemail, retry later
* **Why:** Reminders are time-sensitive; voicemail less effective than conversation
### Sales Lead Follow-up
* **Configuration:** Leave message (smart mode) with callback and value proposition
* **Why:** Provide information even when reaching voicemail; gives leads opportunity to respond
### Customer Satisfaction Surveys
* **Configuration:** Hang up on voicemail
* **Why:** Surveys require conversation; voicemail can't complete survey
### Service Outage Notifications
* **Configuration:** Leave message (static mode) with clear, consistent notification
* **Why:** Critical information must be delivered; voicemail ensures message is received
### Complex Business Outreach
* **Configuration:** Navigate IVR, leave message if human not reached
* **Why:** Reaching decision-makers in large organizations often requires menu navigation
## Measuring Effectiveness
### Key Metrics
* **IVR/voicemail detection rate** - What percentage of calls reach automated systems?
* **Navigation success rate** - When navigation is enabled, how often does it reach humans?
* **Callback rate from voicemail** - Do contacts respond after voicemail messages?
* **Time spent in IVR** - How long does navigation take before reaching humans?
* **False positive rate** - How often are humans mistaken for IVR?
### Optimization Signals
**High voicemail rate** (>40%)
* Try calling at different times
* Validate phone number quality
* Consider leaving messages instead of hanging up
**Low navigation success** (\<20%)
* Phone systems may be too complex
* Consider disabling navigation and hanging up
* Focus efforts on direct contact numbers
**Low callback rate** (\<5%)
* Improve voicemail message quality
* Ensure callback number is clear
* Provide better value proposition in message
**High false positive rate** (>10%)
* Detection may be too aggressive
* Report patterns to Dasha BlackBox support
* Consider adjusting detection sensitivity (if available)
## Technical Considerations
### Detection Accuracy
IVR detection is highly accurate (>90%) but not perfect:
* Clear, professional recordings are easiest to detect
* Personal voicemail greetings with music or long messages may delay detection
* Poor audio quality can affect detection accuracy
* Unusual IVR systems may not be recognized
### DTMF Tone Generation
When navigation is enabled, agent sends standard DTMF tones:
* Compatible with virtually all IVR systems
* Timing calibrated for reliable recognition
* Supports 0-9, \*, # characters
### Latency Considerations
IVR detection adds 2-8 seconds at call start:
* Necessary for accurate detection
* Faster than human would react to IVR menus
* Minimal compared to time saved by proper handling
### Compatibility
IVR detection works for:
* ✅ Outbound phone calls (primary use case)
* ✅ Inbound phone calls (if enabled)
* ⚠️ Web calls (limited utility)
* ❌ Chat sessions (not applicable)
## Troubleshooting
### Problem: Detection Not Working (Treats Voicemail as Human)
**Solution:** Verify IVR detection is enabled for outbound calls. Test with known voicemail numbers. Check detection behavior configuration is not set to "Continue".
### Problem: False Positives (Humans Detected as IVR)
**Solution:** This is rare but can happen with unusual human answering patterns. Report specific cases to support. Consider if detection is actually correct (e.g., receptionist reading from script).
### Problem: Agent Can't Navigate IVR Successfully
**Solution:** IVR navigation works best with simple menus. Complex multi-level systems may be too difficult. Disable navigation and use hang-up or leave message behavior instead.
### Problem: Voicemail Messages Being Cut Off
**Solution:** Keep messages under 20 seconds. Some voicemail systems have short recording limits. Front-load important information (callback number, name, purpose).
### Problem: Too Many Calls Going to Voicemail
**Solution:** Adjust calling times to match target availability. Consider multiple attempts at different times. Validate phone number quality from data source.
## Next steps
> [card] [Maximum Call Duration](/docs/advanced-features/max-call-duration)
>
> Control call length after navigation
> [card] [Talk First](/docs/advanced-features/talk-first)
>
> Configure opening greetings
> [card] [Silence Management](/docs/advanced-features/silence-management)
>
> Handle unresponsive IVR systems
> [card] [Outbound Calls](/docs/deploy/outbound-calls)
>
> Schedule outbound campaigns
# Connect Your Agent to Knowledge Bases
Source: https://blackbox.dasha.ai/docs/advanced-features/knowledge-base
Connect your Dasha BlackBox voice agent to knowledge bases for accurate, real-time information retrieval. Your agent searches documentation, FAQs, and product manuals instead of relying on memory—this approach (Retrieval-Augmented Generation/RAG) reduces hallucinations. Update your docs and your agent immediately knows the latest information.
Ground your agent in factual data. Connect knowledge bases so your agent searches documentation, FAQs, and product manuals — reducing hallucinations and staying current.
**What you'll learn:** Knowledge base setup, document formats, RAG configuration, and update workflows.
## Why Use Knowledge Base Integration?
### Reduce Hallucinations
Language models sometimes generate plausible-sounding but incorrect information. Knowledge base integration grounds responses in factual data, dramatically reducing false or misleading answers.
### Always Current Information
Product details, pricing, policies, and procedures change. Knowledge bases can be updated instantly, ensuring agents always provide current information without retraining.
### Domain Expertise
General language models lack specialized knowledge about your specific products, services, or business. Knowledge bases provide domain-specific expertise.
### Verifiable Answers
Responses based on documentation can be traced back to source material, important for compliance, quality assurance, and trust.
### Handling Complex Queries
Detailed technical questions, multi-step processes, or nuanced policies are better handled by retrieving exact information than relying on model knowledge.
## How to Configure Knowledge Base Integration
### Step 1: Create or Upload Knowledge Bases
Before integrating with agents, you need knowledge bases in your Dasha BlackBox account:
1. Navigate to **Knowledge Bases** in your dashboard
2. Click **Create Knowledge Base**
3. Upload documentation, FAQs, or content (must be in Markdown format)
4. Process and index the content
Knowledge bases can contain:
* Product documentation
* FAQs and help articles
* Company policies
* Technical manuals
* Training materials
* Process documentation
### Step 2: Enable Knowledge Base Integration
1. Open your agent's configuration
2. Navigate to the **Features** tab
3. Find **Knowledge Base Integration** and toggle it on
### Step 3: Select Knowledge Bases
Choose which knowledge bases this agent can access:
1. Use the search/filter to find knowledge bases
2. Click checkboxes to select relevant bases
3. Selected knowledge bases appear as removable chips
4. Agent can search all selected knowledge bases during conversations
**Best practice:** Only connect knowledge bases relevant to the agent's purpose. Don't give support agents access to internal HR policies they'll never need.
### Step 4: Test Knowledge Retrieval
Make test calls asking questions that should be answered from knowledge bases:
1. Ask specific factual questions from your documentation
2. Verify agent retrieves and uses correct information
3. Ask edge cases or ambiguous questions
4. Ensure agent handles "not found" scenarios gracefully
## Configuration Examples
> [accordion] Example: Customer Support Agent
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "knowledgeBaseIntegration": "enabled",
> "connectedKnowledgeBases": [
> "Product Documentation (v2.4)",
> "FAQs - Common Issues",
> "Warranty and Returns Policy",
> "Troubleshooting Guide"
> ]
> }
> ```
>
> **Rationale:** Support agent needs product details, common solutions, policies, and troubleshooting steps.
> [accordion] Example: Sales Agent
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "knowledgeBaseIntegration": "enabled",
> "connectedKnowledgeBases": [
> "Product Catalog",
> "Pricing and Plans",
> "Competitive Comparison Guide",
> "Case Studies"
> ]
> }
> ```
>
> **Rationale:** Sales agent needs product information, pricing, competitive positioning, and social proof.
> [accordion] Example: Appointment Scheduling
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "knowledgeBaseIntegration": "enabled",
> "connectedKnowledgeBases": [
> "Service Descriptions",
> "Location and Hours",
> "Preparation Instructions"
> ]
> }
> ```
>
> **Rationale:** Scheduling agent needs service details, availability information, and instructions for appointments.
> [accordion] Example: Technical Support
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "knowledgeBaseIntegration": "enabled",
> "connectedKnowledgeBases": [
> "Technical Documentation",
> "API Reference",
> "Known Issues and Workarounds",
> "System Requirements"
> ]
> }
> ```
>
> **Rationale:** Technical support needs detailed technical information, API details, known problems, and requirements.
## Common Use Cases
### Product Support
**Knowledge Bases:** Product documentation, troubleshooting guides, FAQs
**Queries:** "How do I reset my password?", "What are the system requirements?", "Why isn't feature X working?"
### Policy Information
**Knowledge Bases:** Return policies, warranty information, terms of service
**Queries:** "What's your return policy?", "How long is the warranty?", "Can I cancel my subscription?"
### Appointment Information
**Knowledge Bases:** Service descriptions, preparation instructions, location details
**Queries:** "What should I bring to my appointment?", "Where is your office located?", "What does the consultation include?"
### Technical Support
**Knowledge Bases:** API documentation, technical specifications, known issues
**Queries:** "What's the syntax for this API call?", "What version supports feature X?", "Is there a known issue with Y?"
### Billing and Account Questions
**Knowledge Bases:** Billing FAQs, plan descriptions, account management guides
**Queries:** "How do I update my payment method?", "What's included in the pro plan?", "Why was I charged?"
## Knowledge Base Content Best Practices
> [accordion] Structure
>
> Use clear headings and sections:
>
> ```markdown theme={"theme":{"light":"github-light","dark":"github-dark"}}
> # Password Reset
>
> ## How to Reset Your Password
>
> 1. Go to the login page
> 2. Click "Forgot Password"
> 3. Enter your email address
> 4. Check your email for reset link
> 5. Follow the link and create new password
>
> ## Troubleshooting
>
> ### I didn't receive the reset email
>
> Check your spam folder. If still not found, contact support at...
>
> ### The reset link expired
>
> Links expire after 24 hours. Request a new reset link.
> ```
### Write for Voice
Knowledge bases used by voice agents should be conversational:
**Good:**
"To reset your password, go to the login page and click Forgot Password. Enter your email address, and we'll send you a reset link within a few minutes."
**Less Good:**
"Password Reset Procedure: 1) Navigate to auth interface 2) Select passwd recovery option 3) Submit email addr for verification token delivery"
> [accordion] Include Variations
>
> Include different ways people ask the same question:
>
> ```markdown theme={"theme":{"light":"github-light","dark":"github-dark"}}
> # Shipping Time
>
> **Question:** How long does shipping take?
> **Also asked as:**
> - When will my order arrive?
> - What's your delivery time?
> - How fast is shipping?
>
> **Answer:** Standard shipping takes 5-7 business days...
> ```
### Keep Updated
Set review schedule:
* Critical information (pricing, policies): Monthly review
* Product documentation: Review with each release
* FAQs: Add new questions as they arise
* Seasonal information: Update before relevant periods
## Monitoring and Optimization
### Key Metrics
* **Retrieval success rate** - How often does agent find relevant information?
* **Answer accuracy** - Are retrieved answers correct?
* **Knowledge base usage** - Which bases are accessed most frequently?
* **Failed queries** - What questions couldn't be answered?
* **Caller satisfaction** - Are callers happy with answers provided?
### Improvement Process
1. **Monitor failed queries**: Track questions where agent couldn't find information
2. **Identify gaps**: What content is missing from knowledge bases?
3. **Add content**: Create documentation for common unanswered questions
4. **Refine existing content**: Improve content that retrieves poorly
5. **Test improvements**: Verify new content retrieves correctly
6. **Repeat**: Continuous improvement based on usage data
### Content Quality Signals
**Good retrieval** (agent easily finds correct information):
* Well-structured content with clear headings
* Comprehensive coverage of topic
* Uses common terminology and phrasing
* Includes examples and variations
**Poor retrieval** (agent struggles to find information):
* Vague or unclear content
* Missing common questions
* Uses jargon without explanation
* Poorly organized or fragmented information
## Technical Considerations
### Supported Formats
Currently, knowledge bases must be uploaded in **Markdown format** (.md files). Your documentation, FAQs, and content should be formatted as Markdown documents for upload.
### Vector Embeddings
Knowledge bases use semantic embeddings:
* Content is converted to vector representations
* Searches find semantically similar content (not just keyword matches)
* "How do I reset my password?" matches "Password recovery process"
### Update Latency
After updating knowledge bases:
* Changes typically propagate within minutes
* Re-indexing may be required for large updates
* Test retrieval after significant changes
### Context Limits
Retrieved information consumes agent context:
* Agents balance between conversation history and retrieved content
* Very long knowledge base passages may be truncated
* Focus on concise, relevant content for best results
## Troubleshooting
### Problem: Agent Doesn't Use Knowledge Base Information
**Solution:** Verify knowledge base integration is enabled and bases are selected. Check knowledge base actually contains relevant information. Update system prompt to encourage knowledge base usage: "Search knowledge bases for factual information before answering questions."
### Problem: Agent Retrieves Wrong Information
**Solution:** Review knowledge base organization. Ensure content has clear context and isn't ambiguous. Improve headings and structure. Consider splitting overly broad knowledge bases into focused ones.
### Problem: Agent Can't Find Information That Exists
**Solution:** Improve content searchability with clearer headings, better keywords, and question variations. Ensure content is indexed (re-index if needed). Use language similar to how callers ask questions.
### Problem: Retrieved Information is Outdated
**Solution:** Implement knowledge base update process. Review and refresh content regularly. Set up alerts for content age. Consider version control for documentation.
### Problem: Too Many Knowledge Bases Confuse Agent
**Solution:** Reduce number of connected bases. Combine related bases. Only connect bases directly relevant to agent's purpose. Use more focused, purpose-built knowledge bases.
## Next steps
> [card] [Tools & Functions](/docs/create/tools-and-functions)
>
> Extend agent capabilities beyond knowledge bases
> [card] [Post-Call Analysis](/docs/advanced-features/post-call-analysis)
>
> Extract insights from conversations
> [card] [Language Switching](/docs/advanced-features/language-switching)
>
> Multi-language knowledge base support
> [card] [MCP Connections](/docs/create/mcp-connections)
>
> Connect to external data sources
# Enable Mid-Conversation Language Changes
Source: https://blackbox.dasha.ai/docs/advanced-features/language-switching
Enable your Dasha BlackBox voice agent to switch languages mid-conversation when customers request it in the current language. One agent handles multiple languages (English, Spanish, French, etc.). Important: The agent can't detect requests in other languages—customers must ask in the current conversation language first.
Serve multilingual customers with one agent. Language switching lets callers request a different language mid-conversation — one agent handles English, Spanish, French, and more.
**What you'll learn:** Supported languages, switching behavior, limitations, and configuration steps.
## Why Use Language Switching?
### Serves Multilingual Customers
Many customers are more comfortable speaking in their native language, especially for complex topics or sensitive conversations. Language switching removes language barriers for customers who can communicate the switch request in your primary language.
### Increases Accessibility
Customers who have basic proficiency in your primary language can request support in their preferred language, improving satisfaction and conversation quality once switched.
### Expands Market Reach
A single agent can serve customers across multiple language markets, reducing the need for separate language-specific agents or campaigns.
### Improves Conversation Quality
When customers speak in their preferred language:
* They express themselves more clearly
* Misunderstandings decrease
* Satisfaction increases
* Complex topics are easier to discuss
### Cost Efficient
Instead of maintaining separate agents for each language, one multilingual agent can handle diverse customer needs.
## How Language Switching Works
**Important limitation:** The agent can only understand and respond in its current primary language. To switch languages, callers must make the request in the primary language.
**Example flow (Primary Language: English):**
✅ **Correct:**
```
Agent: "Hello, how can I help you today?"
Caller: "Do you speak Spanish?" [Request in English - primary language]
Agent: "Sí, puedo ayudarte en español. ¿En qué puedo ayudarte?"
[Rest of conversation continues in Spanish]
```
❌ **Incorrect:**
```
Agent: "Hello, how can I help you today?"
Caller: "¿Hablas español?" [Request in Spanish - NOT primary language]
Agent: [Does not understand - continues in English or becomes confused]
```
**The agent cannot:**
* Detect when callers suddenly start speaking a different language
* Understand language switch requests made in languages other than the primary language
* Automatically recognize what language the caller prefers
**The agent can:**
* Switch to a different language when explicitly requested in the primary language
* Maintain conversation context across the language switch
* Continue the entire conversation in the new language after switching
## How to Configure Language Switching
### Step 1: Set Primary Language
Your agent's primary language must be configured before enabling language switching.
1. Open your agent's configuration
2. Navigate to the **Basic Info** tab
3. Select **Primary Language** from available options
4. Common options: English (en-US), Spanish (es-ES), French (fr-FR), German (de-DE), Portuguese (pt-BR), and many more
### Step 2: Enable Language Switching
1. Navigate to the **Features** tab
2. Find **Language Switching** and toggle it on
That's it. Once enabled, your agent can switch languages when customers request it in the primary language.
**Note:** Language switching uses your agent's configured voice for all languages. You cannot configure different voices for different languages — the same voice is used throughout the conversation regardless of language switches. Ensure your selected voice model supports the languages you expect customers to request.
## Supported Languages
Dasha BlackBox supports language switching for all languages supported by your configured voice and language model. However, the agent must receive the initial switch request in the primary language.
**Common languages:**
* English (multiple variants: US, UK, Australian, etc.)
* Spanish (Spain, Latin American variants)
* French (France, Canadian)
* German
* Portuguese (Brazil, Portugal)
* Italian
* Dutch
* Chinese (Mandarin, Cantonese)
* Japanese
* Korean
* Arabic
* Hindi
* And many more...
**Voice availability varies by provider.** Ensure your chosen voice vendor supports the languages you need with good quality.
## Configuration Examples
> [accordion] Example: English-Spanish Support Agent
>
> This shows the `config.features.languageSwitching` object:
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "isEnabled": true
> }
> ```
>
> Combined with agent's `primaryLanguage` set to `"en-US"` and a voice that supports both English and Spanish.
>
> **Customer experience:**
>
> * Agent starts in English
> * Customer asks "Can you speak Spanish?" (in English)
> * Agent switches to Spanish (using the same voice)
> * Conversation continues in Spanish
> [accordion] Example: Multilingual European Support
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "isEnabled": true
> }
> ```
>
> Combined with agent's `primaryLanguage` set to `"en-GB"` and a voice that supports English, French, German, and Italian.
>
> **Customer experience:**
>
> * Agent starts in English
> * Customer asks "Do you speak German?" (in English)
> * Agent switches to German (using the same voice)
> * Conversation continues in German
> [accordion] Example: Spanish Primary with English Switching
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "isEnabled": true
> }
> ```
>
> Combined with agent's `primaryLanguage` set to `"es-ES"` and a voice that supports Spanish and English.
>
> **Customer experience:**
>
> * Agent starts in Spanish
> * Customer asks "¿Hablas inglés?" (in Spanish - the primary language)
> * Agent switches to English (using the same voice)
> * Conversation continues in English
## Common Use Cases
### International Customer Support
* **Configuration:** English primary with Spanish, French, German switching enabled
* **Why:** Customers worldwide can request support in their preferred language (in English initially)
### Healthcare Services
* **Configuration:** English primary with community languages in service area
* **Why:** Medical conversations require clear understanding—native language improves outcomes
### Banking and Financial Services
* **Configuration:** Primary language based on market, switching for secondary languages
* **Why:** Financial topics are complex; native language reduces misunderstandings
### Government Services
* **Configuration:** Official language primary, switching to common community languages
* **Why:** Accessibility requirements often mandate multilingual support
### E-commerce Support
* **Configuration:** Primary market language with switching to secondary market languages
* **Why:** International customers need support in their language for purchases and returns
## Technical Considerations
### Language Detection Limitations
**Critical understanding:**
* Agent ONLY understands its current primary language
* Agent CANNOT detect when callers suddenly speak different languages
* Agent REQUIRES explicit requests in the primary language to switch
**Valid switch requests (assuming English primary):**
* "Can you speak Spanish?"
* "Do you speak French?"
* "Are you able to communicate in German?"
* "Can we switch to Portuguese?"
**Invalid switch requests (assuming English primary):**
* "¿Hablas español?" - Agent won't understand (not in primary language)
* Starting to speak Spanish without requesting - Agent won't understand
* "Parlez-vous français?" - Agent won't understand (not in primary language)
### Voice Consistency
When switching languages, the agent uses the same configured voice throughout the conversation. You cannot configure different voices for different languages — language switching only changes the spoken language, not the voice.
The agent maintains:
* Same voice vendor and model
* Consistent voice characteristics (as much as possible)
* Similar speaking style and pace
The voice quality in switched languages depends on the voice vendor's multilingual capabilities. Choose a voice that supports all languages you expect customers to request.
### Knowledge Base Behavior
If you use [Knowledge Base Integration](/docs/advanced-features/knowledge-base):
* Searches are performed in the active conversation language
* Ensure knowledge bases contain content in all supported languages
* Consider language-specific knowledge bases for best results
* Structure content with language tagging for efficient retrieval
### Custom Tools
[Custom tools](/docs/create/tools-and-functions) receive context about the current conversation language. Design APIs to handle multiple languages appropriately.
### Compatibility
Language switching works across:
* ✅ Outbound phone calls
* ✅ Inbound phone calls
* ✅ Web-based voice calls
* ✅ All voice vendors supporting multiple languages
## Troubleshooting
### Problem: Agent Doesn't Switch Languages
**Solution:** Verify language switching is enabled in Features tab. Ensure the caller requested the switch in the primary language (not in the target language). Try explicit requests like "Can you speak in \[language]?" in the primary language.
### Problem: Agent Doesn't Understand Language Request
**Solution:** The request may have been made in the wrong language. Callers must request language switches in the current primary language. For example, if the agent speaks English, ask "Do you speak Spanish?" in English, not "¿Hablas español?" in Spanish.
### Problem: Poor Quality in Switched Language
**Solution:** The voice vendor may not support that language well. Test different voice vendors or select a vendor specializing in that language. Check voice vendor documentation for language support quality.
### Problem: Speech Recognition Errors After Switch
**Solution:** Some speech-to-text providers perform better in certain languages. Verify your speech provider supports the target language. Consider testing different providers for better recognition accuracy.
### Problem: Knowledge Base Returns Wrong Language
**Solution:** Ensure knowledge bases contain content in all supported languages. Structure knowledge bases with language indicators. Consider creating separate knowledge bases per language for better retrieval accuracy.
### Problem: Caller Can't Request Switch
**Solution:** If callers don't speak the primary language well enough to request a switch, consider setting the primary language to the most common customer language, or use separate agents for different primary languages.
## Enhancing Multilingual Capabilities
> [accordion] Multilingual System Prompts
>
> Include language guidance in your system prompt:
>
> ```
> You are a helpful customer support agent. Your primary language is English, but you can communicate in Spanish, French, and German when customers request it.
>
> When customers ask questions like "Do you speak Spanish?" or "Can you speak French?", confirm the switch in their requested language and continue the entire conversation in that language.
>
> Remember: You can only understand language switch requests when they are asked in your current language. If you hear unfamiliar language, politely remind the customer to request language changes in English.
> ```
> [accordion] Language-Specific Behaviors
>
> If certain behaviors differ by culture, include guidance:
>
> ```
> When speaking Spanish, use formal "usted" form for customer service. When speaking French, use "vous" for formal conversations unless the customer indicates otherwise.
> ```
### Multilingual Knowledge Bases
Structure knowledge bases to support multiple languages:
* Organize content by language with clear tagging
* Use consistent formatting across languages
* Keep translations synchronized with updates
* Test retrieval accuracy in each language
* Consider separate knowledge bases per language for best performance
## Measuring Effectiveness
Track these metrics for language switching:
* **Language switch rate** - Percentage of calls where switching occurs
* **Switch success rate** - How often switches are understood and executed
* **Failed switch attempts** - Requests made in wrong language that fail
* **Satisfaction by language** - Compare satisfaction scores across languages
* **Language distribution** - Which languages are most requested
* **Speech recognition accuracy** - Quality metrics per language
* **Resolution rate by language** - Whether outcomes differ by language
## Next steps
> [card] [Knowledge Bases](/docs/advanced-features/knowledge-base)
>
> Provide multilingual content
> [card] [Tools & Functions](/docs/create/tools-and-functions)
>
> Design language-aware integrations
> [card] [Post-Call Analysis](/docs/advanced-features/post-call-analysis)
>
> Extract data regardless of language
> [card] [Voice & Speech](/docs/create/voice-and-speech)
>
> Configure multilingual voices
# Set Automatic Time Limits for Calls
Source: https://blackbox.dasha.ai/docs/advanced-features/max-call-duration
Set automatic time limits for Dasha BlackBox voice agent calls to control costs and prevent stuck calls from running indefinitely. When a call reaches the limit, your agent gracefully ends the conversation. Configure different limits for normal and transferred calls.
Control costs with automatic time limits. Set maximum durations for calls — when reached, your agent ends the conversation gracefully instead of running indefinitely.
**What you'll learn:** Duration configuration, separate limits for normal vs. transferred calls, and cost control strategies.
## Why Use Maximum Call Duration?
### Cost Control
Voice conversations incur per-minute costs for telephony, speech processing, and language model usage. Time limits prevent unexpectedly expensive calls from eroding your budget.
### Resource Management
Long-running calls consume system resources. Time limits ensure resources are available for other calls, particularly important for high-volume operations.
### Prevents Stuck Calls
Technical issues can occasionally cause calls to remain connected indefinitely. Maximum duration acts as a safety net, automatically ending problematic calls.
### Operational Efficiency
Most legitimate conversations complete within predictable timeframes. Time limits help identify and terminate anomalous calls that may indicate problems.
## How to Configure Maximum Call Duration
### Step 1: Enable Maximum Call Duration
1. Open your agent's configuration
2. Navigate to the **Features** tab
3. Find **Maximum Call Duration** and toggle it on
### Step 2: Set Time Limits
Configure duration limits in seconds:
**maxDurationSeconds** (Normal Calls)
* Default: 3600 seconds (1 hour)
* Applies to standard agent conversations
**maxDurationInTransferSeconds** (During Transfer)
* Default: 7200 seconds (2 hours)
* Applies while a call is in transfer state (connected to human operator)
**Why different limits?**
* Normal agent calls typically resolve quickly (5-15 minutes)
* Calls in transfer state may involve complex troubleshooting requiring more time
* Human-to-human conversations naturally run longer than agent interactions
### Step 3: Test Time Limits
Before deploying to production:
1. Make test calls that approach the time limit
2. Verify the agent ends calls gracefully
3. Ensure callers receive appropriate closing messages
4. Adjust limits based on actual conversation durations
## Configuration Examples
This shows the `config.features.maxDuration` object structure:
> [accordion] Example: Customer Support (Conservative)
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "isEnabled": true,
> "maxDurationSeconds": 1800,
> "maxDurationInTransferSeconds": 3600
> }
> ```
>
> **Rationale:** Most support calls resolve in 10-20 minutes. Generous buffer allows complex issues while preventing extreme outliers.
> [accordion] Example: Sales Qualification (Tight Control)
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "isEnabled": true,
> "maxDurationSeconds": 900,
> "maxDurationInTransferSeconds": 2400
> }
> ```
>
> **Rationale:** Qualification calls should be brief. Tight limits maintain efficiency and prevent rambling conversations.
> [accordion] Example: Technical Support (Generous)
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "isEnabled": true,
> "maxDurationSeconds": 2400,
> "maxDurationInTransferSeconds": 7200
> }
> ```
>
> **Rationale:** Technical troubleshooting takes time. Generous limits accommodate complex diagnostic processes.
> [accordion] Example: Survey Collection (Very Short)
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "isEnabled": true,
> "maxDurationSeconds": 600,
> "maxDurationInTransferSeconds": 1800
> }
> ```
>
> **Rationale:** Surveys should be brief and focused. Short limits respect respondent time and maintain survey quality.
## Common Use Cases
### High-Volume Outbound Campaigns
* **Configuration:** 10-15 minute limit for normal calls
* **Why:** Cost control at scale. Brief, focused conversations keep campaign costs predictable.
### Customer Support with Escalation
* **Configuration:** 30 minutes normal, 1-2 hours transferred
* **Why:** Agent handles routine issues quickly; complex issues get adequate human time after transfer.
### Appointment Reminders
* **Configuration:** 5-10 minute limit
* **Why:** Reminders should be brief confirmations, not extended conversations.
### Lead Qualification
* **Configuration:** 15-20 minute limit
* **Why:** Qualification should be efficient. Long calls often indicate poor fit or lack of interest.
### Technical Support Triage
* **Configuration:** 20-30 minutes normal, 2+ hours transferred
* **Why:** Agent triages issues quickly; deep troubleshooting happens after transfer with adequate time.
## Monitoring and Optimization
### Key Metrics
Track these metrics to optimize time limits:
* **Average call duration** - What's typical for your use case?
* **Calls hitting limit** - What percentage reach maximum duration?
* **Duration distribution** - What's the 90th percentile call length?
* **Limit-hit outcomes** - Were these legitimate long calls or stuck calls?
### Optimization Process
1. **Baseline**: Set initial limits based on expected durations
2. **Collect data**: Monitor actual call durations for 1-2 weeks
3. **Analyze**: Review calls hitting limits—were they legitimate or stuck?
4. **Adjust**: Increase limits if legitimate calls are cut short; decrease if limits aren't catching outliers
5. **Repeat**: Continuously monitor and refine
### Warning Signs
**Too many calls hitting limits** (>5% of total)
* Limits may be too restrictive
* Complex issues may need more time
* Consider increasing limits by 25-50%
**No calls ever hit limits**
* Limits may be too generous
* Not providing cost protection
* Consider reducing limits to find optimal threshold
**Caller complaints about abrupt endings**
* Limits too short for your use case
* Improve graceful ending messages
* Increase limits to provide adequate time
## Technical Considerations
### Timer Precision
Duration tracking is accurate to within 1-2 seconds. Calls terminate as soon as the limit is reached.
### Transfer Timing
When a call is transferred:
* Normal call timer stops
* Transferred call timer starts
* Only transferred call limit applies after transfer
* Pre-transfer duration doesn't count toward transferred limit
### Multiple Transfers
If a call is transferred multiple times:
* Transferred call limit applies to total post-transfer time
* Timer doesn't reset between transfers
### Compatibility
Maximum call duration works across:
* ✅ Outbound phone calls
* ✅ Inbound phone calls
* ✅ Web-based voice calls
* ✅ All call types and scenarios
## Troubleshooting
### Problem: Legitimate Calls Being Cut Short
**Solution:** Increase maximum duration by 25-50%. Review calls hitting limits to understand why they run long. Consider if agent needs better training to resolve issues more efficiently.
### Problem: Stuck Calls Not Being Caught
**Solution:** Reduce maximum duration. Verify time limits are enabled. Check for technical issues causing calls to hang without triggering duration tracking.
### Problem: Callers Frustrated by Time Limits
**Solution:** Implement warning system so agent can notify callers when time is running out. Offer to schedule follow-up calls for complex issues. Increase limits if consistently insufficient.
### Problem: High Costs Despite Time Limits
**Solution:** Review actual call duration distribution. Consider whether limits need to be more aggressive. Analyze calls to identify opportunities for agent efficiency improvements.
### Problem: Different Limits Needed for Different Scenarios
**Solution:** Create separate agents for different use cases, each with appropriate time limits. Use agent selection logic to route calls to correctly-configured agents.
## Cost Impact Example
**Scenario:** 10,000 calls per month
**Without time limits:**
* Average duration: 15 minutes
* Outliers (2%): 90 minutes average
* Total minutes: 153,600
* Cost at $0.05/min: $7,680
**With 30-minute limit:**
* Average duration: 15 minutes (unchanged)
* Limited outliers (2%): 30 minutes max
* Total minutes: 150,600
* Cost at $0.05/min: $7,530
* **Savings: \$150/month (2%)**
Even small percentages of outlier calls can significantly impact costs at scale.
## Next steps
> [card] [Silence Management](/docs/advanced-features/silence-management)
>
> Handle inactive calls before time limit
> [card] [Call Transfers](/docs/advanced-features/call-transfers)
>
> Configure separate limits for transferred calls
> [card] [Webhooks](/docs/webhooks-and-events/webhooks-overview)
>
> Receive notifications when calls hit limits
> [card] [Call History](/docs/monitor/call-history)
>
> Monitor call duration metrics
## Disable Automatic Loop-Based Endings
For an agent that should use its own conversation policy, set this field in the agent's configuration through the API:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"features": {
"disableAutomaticLoopDetection": true
}
}
```
This removes the appended loop-detection, input-quality and conversation-limit instructions for that agent. The finish validator also rejects a finish classified as `loop detected`. The setting is optional: omitted, `null` or `false` preserves the default instructions and validation behavior.
The agent can still end for a supported independent reason, including a caller's goodbye. Its own prompt and tool instructions still apply. Maximum-duration timers and silence thresholds are separate and remain active. There is no dashboard switch for this API setting.
# Filter Background Noise from Calls
Source: https://blackbox.dasha.ai/docs/advanced-features/noise-suppression
Remove background noise from call audio using Krisp-powered noise suppression. Improve speech recognition accuracy and call quality in noisy environments.
Filter out background noise from incoming audio so your agent hears speech clearly — even when callers are in noisy environments. Uses Krisp's AI-powered noise suppression engine.
**What you'll learn:** How to enable noise suppression, configure suppression levels, and choose recording strategies.
> [!NOTE]
>
> Krisp noise suppression incurs an additional per-minute fee.
***
## When to use noise suppression
| Environment | Without suppression | With suppression |
| - | - | - |
| **Street/traffic** | Agent mishears words, frequent "could you repeat that" | Clear speech isolation |
| **Cafe/restaurant** | Background chatter confuses STT | Voice stands out from ambiance |
| **Construction site** | Heavy machinery drowns out caller | Speech remains intelligible |
| **Home with kids/pets** | Barking, crying triggers false transcriptions | Focuses on primary speaker |
Noise suppression improves speech-to-text accuracy by removing non-voice audio before it reaches the transcription engine.
***
## Configure noise suppression
> [tab] Dashboard
>
> 1. Open your agent's configuration
> 2. Navigate to the **Features** tab
> 3. Find **Noise Suppression** and toggle it on
> 4. Select **Krisp** as the engine
> 5. Adjust the suppression level (0–100)
> 6. Choose recording strategy (raw or cleaned)
> 7. Save your agent
> [tab] API
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> 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: 'Support Agent',
> config: {
> features: {
> noiseSuppression: {
> isEnabled: true,
> type: 'krisp',
> noiseSuppressionLevel: 75,
> recordWriteStrategy: 'raw'
> }
> }
> // ... other config
> }
> })
> });
> ```
***
## Configuration options
| Field | Type | Default | Description |
| - | - | - | - |
| `isEnabled` | boolean | `false` | Master toggle for noise suppression |
| `type` | string | `"none"` | Engine: `"none"` or `"krisp"` |
| `noiseSuppressionLevel` | integer | `75` | Aggressiveness (0–100) |
| `recordWriteStrategy` | string | `"raw"` | What to save: `"raw"` or `"cleaned"` |
***
## Suppression levels
The `noiseSuppressionLevel` controls how aggressively background noise is filtered:
| Level | Effect | Best for |
| - | - | - |
| **0–30** | Light filtering | Quiet environments with occasional noise |
| **40–60** | Moderate filtering | Office or home settings |
| **70–85** | Strong filtering | Busy public spaces (default: 75) |
| **90–100** | Maximum filtering | Extremely noisy environments |
> [!WARNING]
>
> Very high levels (90+) may slightly affect voice quality. Start at 75 and adjust based on your use case.
***
## Recording strategy
Choose what audio gets saved in call recordings:
| Strategy | Saves | Use when |
| - | - | - |
| **raw** | Original unprocessed audio | You need the authentic recording for compliance or disputes |
| **cleaned** | Noise-suppressed audio | You want cleaner recordings for review or training |
> [accordion] Example: Compliance-first (raw recordings)
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> noiseSuppression: {
> isEnabled: true,
> type: 'krisp',
> noiseSuppressionLevel: 75,
> recordWriteStrategy: 'raw' // Keep original audio for legal purposes
> }
> ```
> [accordion] Example: Clean recordings for QA
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> noiseSuppression: {
> isEnabled: true,
> type: 'krisp',
> noiseSuppressionLevel: 80,
> recordWriteStrategy: 'cleaned' // Save the cleaned version
> }
> ```
***
## How it works
1. **Caller audio arrives** with background noise
2. **Krisp engine processes** the audio in real-time
3. **Cleaned audio goes to STT** for accurate transcription
4. **Recording saves** either raw or cleaned audio (your choice)
The agent always hears the cleaned audio. The recording strategy only affects what gets stored.
***
## Troubleshooting
### Agent still mishearing in noisy environments
| Symptom | Fix |
| - | - |
| Suppression enabled but no improvement | Verify `type` is set to `"krisp"`, not `"none"` |
| Some noise gets through | Increase `noiseSuppressionLevel` to 85–90 |
| Extreme noise environments | Level 100 + consider if call quality is viable |
### Voice sounds distorted
| Symptom | Fix |
| - | - |
| Voice sounds robotic or thin | Lower `noiseSuppressionLevel` to 60–70 |
| Words getting cut off | Reduce level; aggressive filtering can clip speech |
***
## Next steps
> [card] [Ambient Noise](/docs/advanced-features/ambient-noise)
>
> Add background sounds (outgoing)
> [card] [Voice & Speech](/docs/create/voice-and-speech)
>
> Configure STT and TTS
> [card] [Language Switching](/docs/advanced-features/language-switching)
>
> Support multiple languages
> [card] [Call Inspector](/docs/test/call-inspector)
>
> Debug call audio issues
# Enhance Your Voice Agent
Source: https://blackbox.dasha.ai/docs/advanced-features/overview
Enhance Dasha BlackBox voice agents with natural conversation features, intelligent call handling, post-call analysis, and powerful integrations.
Make your agents more capable. This section covers natural conversation enhancements, call handling features, post-call analysis, knowledge bases, and integrations.
**What you'll learn:** Ambient noise, fillers, backchannel, noise suppression, call transfers, IVR detection, pre-conversation media, language switching, and more.
***
## Voice & Conversation
### [Ambient Noise](/docs/advanced-features/ambient-noise)
Add realistic background sounds. Eliminates uncanny silence and makes conversations feel natural.
### [Fillers](/docs/advanced-features/fillers)
Insert verbal pauses like "um" and "let me think" during processing delays.
### [Backchannel](/docs/advanced-features/backchannel)
Enable acknowledgment sounds like "mm-hmm" and "I see" while callers speak.
### [Talk First](/docs/advanced-features/talk-first)
Configure your agent to speak first when calls connect. Control opening greetings and timing.
### [Language Switching](/docs/advanced-features/language-switching)
Allow dynamic language switching mid-conversation for multilingual customers.
### [Noise Suppression](/docs/advanced-features/noise-suppression)
Filter background noise from incoming audio using Krisp-powered AI. Improve speech recognition in noisy environments.
***
## Call Handling
### [Call Transfers](/docs/advanced-features/call-transfers)
Transfer calls to human operators:
* **Warm transfer** — Context handoff with agent briefing
* **Cold transfer** — Direct routing without context
* **HTTP transfer** — Webhook-based dynamic routing
### [Max Call Duration](/docs/advanced-features/max-call-duration)
Set automatic time limits for cost control and resource management.
### [Silence Management](/docs/advanced-features/silence-management)
Handle caller silence with configurable reminders and timeouts.
### [IVR Detection](/docs/advanced-features/ivr-detection)
Detect automated systems and voicemail. Leave messages or navigate menus automatically.
### [Pre-Conversation Media](/docs/advanced-features/pre-conversation-media)
Play audio when calls connect — compliance disclosures, branded greetings, or hold music before the agent speaks.
***
## Intelligence & Analysis
### [Post-Call Analysis](/docs/advanced-features/post-call-analysis)
Extract structured data from transcripts — sentiment, outcomes, and custom fields.
### [Knowledge Base](/docs/advanced-features/knowledge-base)
Connect to knowledge bases for accurate information retrieval and reduced hallucinations.
***
## Integration
### [Tools & Functions](/docs/create/tools-and-functions)
Enable agents to perform actions — CRM lookups, appointment scheduling, order status checks.
### [Webhooks](/docs/webhooks-and-events/webhooks-overview)
Receive real-time notifications for call events and enable dynamic configuration.
### [MCP Connections](/docs/create/mcp-connections)
Connect to external MCP servers for standardized tools and data sources.
### [WebSockets](/docs/websockets/websockets-overview)
Real-time bidirectional communication for live monitoring and dynamic control.
***
## Next Steps
> [card] [Ambient Noise](/docs/advanced-features/ambient-noise)
>
> Add realistic background sounds
> [card] [Call Transfers](/docs/advanced-features/call-transfers)
>
> Route calls to human operators
> [card] [Post-Call Analysis](/docs/advanced-features/post-call-analysis)
>
> Extract insights from conversations
> [card] [Knowledge Base](/docs/advanced-features/knowledge-base)
>
> Ground responses in your data
# Extract Structured Data from Conversations
Source: https://blackbox.dasha.ai/docs/advanced-features/post-call-analysis
Automatically analyze and label Dasha BlackBox voice agent conversations using custom categories you define (sentiment, outcomes, topics, follow-up required). After each call, AI determines label values from transcripts—no manual review needed. Structured data flows directly to CRM, analytics dashboards, and business intelligence tools.
Configure analysis forms with labeled fields, and AI populates them from each transcript. Results arrive via webhook or API, ready for your CRM, analytics pipeline, or alerting workflows.
**What you'll learn:** Label configuration, extraction types, CRM integration, and analytics patterns.
## Why Use Post-Call Analysis?
### Eliminate Manual Review
Instead of listening to call recordings or reading transcripts, Dasha BlackBox automatically delivers structured summaries after each call.
### Enable CRM Integration
The system flows extracted data directly into your CRM systems, automatically updating customer records with conversation outcomes and sentiment.
### Business Intelligence
Aggregate analysis data across thousands of calls to identify trends, measure satisfaction, track resolution rates, and optimize agent performance.
### Compliance and Quality Assurance
Automatically verify calls cover required topics, disclosures are made, or specific information is collected.
### Trigger Workflows
Use extracted data to trigger automated workflows: escalate negative sentiment calls, schedule follow-ups, update ticket systems, or alert managers.
## How to Configure Post-Call Analysis
### Step 1: Create Analysis Form
1. Open your agent's configuration
2. Navigate to the **Features** tab
3. Scroll to **Post-Call Analysis** section
4. Click **Add Analysis Form**
You can create multiple analysis forms per agent, each analyzing different aspects of conversations.
### Step 2: Configure Analysis Form
**Analysis Name**
* Identifier for this analysis
* Example: "Customer Satisfaction Analysis", "Lead Qualification Data", "Support Ticket Info"
**Enable/Disable Toggle**
* Control whether this analysis runs
* Useful for temporarily disabling specific analyses without deleting configuration
### Step 3: Define Data Labels
Click **Add Label** to define each label the AI should determine from the conversation.
For each label, configure:
**Label Name**
* Identifier (alphanumeric, hyphens, underscores only)
* Used in API responses and webhooks
* Example: `customer_sentiment`, `issue_resolved`, `product_name`
**Label Description**
* What the AI should determine from the conversation
* Be specific and clear
* Example: "The customer's overall sentiment about the interaction: positive, neutral, or negative"
**Data Type**
* **String**: Free-form text (names, descriptions, notes)
* **Number**: Numeric values (ratings, counts, amounts)
* **Boolean**: True/false values (yes/no questions)
* **Enum**: Predefined set of options (dropdown-style choices)
**Enum Values** (if Data Type is Enum)
* List allowed values
* Example for sentiment: `positive`, `neutral`, `negative`
* Example for product: `ProductA`, `ProductB`, `ProductC`
**Required Flag**
* Whether this field must have a value
* If required and not found in transcript, analysis may mark field as unable to determine
## Configuration Examples
> [accordion] Example: Customer Support Analysis
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "analysisName": "Support Call Analysis",
> "enabled": true,
> "labels": [
> {
> "name": "customer_sentiment",
> "description": "Customer's overall sentiment: positive, neutral, or negative",
> "type": "enum",
> "values": ["positive", "neutral", "negative"],
> "required": true
> },
> {
> "name": "issue_resolved",
> "description": "Was the customer's issue fully resolved during the call?",
> "type": "boolean",
> "required": true
> },
> {
> "name": "issue_category",
> "description": "Category of the issue discussed",
> "type": "enum",
> "values": ["billing", "technical", "account", "shipping", "other"],
> "required": true
> },
> {
> "name": "follow_up_needed",
> "description": "Does this customer need follow-up contact?",
> "type": "boolean",
> "required": false
> },
> {
> "name": "resolution_notes",
> "description": "Brief summary of how the issue was resolved",
> "type": "string",
> "required": false
> }
> ]
> }
> ```
> [accordion] Example: Sales Lead Qualification
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "analysisName": "Lead Qualification",
> "enabled": true,
> "labels": [
> {
> "name": "interest_level",
> "description": "Prospect's level of interest in the product",
> "type": "enum",
> "values": ["high", "medium", "low", "not_interested"],
> "required": true
> },
> {
> "name": "budget_discussed",
> "description": "Did the prospect discuss budget or pricing?",
> "type": "boolean",
> "required": true
> },
> {
> "name": "timeline",
> "description": "When does the prospect want to make a decision?",
> "type": "enum",
> "values": ["immediate", "this_month", "this_quarter", "long_term", "unclear"],
> "required": true
> },
> {
> "name": "decision_maker",
> "description": "Is this prospect the decision maker?",
> "type": "boolean",
> "required": true
> },
> {
> "name": "next_step",
> "description": "What is the agreed upon next step?",
> "type": "string",
> "required": true
> },
> {
> "name": "competitors_mentioned",
> "description": "Names of competitors the prospect mentioned, if any",
> "type": "string",
> "required": false
> }
> ]
> }
> ```
> [accordion] Example: Appointment Scheduling
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "analysisName": "Appointment Details",
> "enabled": true,
> "labels": [
> {
> "name": "appointment_confirmed",
> "description": "Did the caller confirm their appointment?",
> "type": "boolean",
> "required": true
> },
> {
> "name": "appointment_date",
> "description": "The confirmed appointment date and time",
> "type": "string",
> "required": true
> },
> {
> "name": "reminder_preferred",
> "description": "Does the caller want a reminder call or SMS?",
> "type": "boolean",
> "required": false
> },
> {
> "name": "special_requests",
> "description": "Any special requests or accommodations needed",
> "type": "string",
> "required": false
> },
> {
> "name": "caller_mood",
> "description": "Overall mood/demeanor of the caller",
> "type": "enum",
> "values": ["friendly", "neutral", "frustrated", "rushed"],
> "required": false
> }
> ]
> }
> ```
> [accordion] Example: Survey Response Collection
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "analysisName": "Survey Responses",
> "enabled": true,
> "labels": [
> {
> "name": "nps_score",
> "description": "Net Promoter Score: How likely is the customer to recommend us? (0-10)",
> "type": "number",
> "required": true
> },
> {
> "name": "service_rating",
> "description": "Customer rating of service quality (1-5)",
> "type": "number",
> "required": true
> },
> {
> "name": "primary_feedback",
> "description": "Main feedback or suggestion the customer provided",
> "type": "string",
> "required": false
> },
> {
> "name": "willing_to_follow_up",
> "description": "Is customer willing to be contacted for follow-up questions?",
> "type": "boolean",
> "required": false
> }
> ]
> }
> ```
## Accessing Analysis Results
> [accordion] Via Webhooks
>
> Analysis results are included in result webhook payloads:
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "call_id": "call_abc123",
> "transcript": "...",
> "analysis_results": {
> "Support Call Analysis": {
> "customer_sentiment": "positive",
> "issue_resolved": true,
> "issue_category": "billing",
> "follow_up_needed": false,
> "resolution_notes": "Updated payment method, issue resolved"
> }
> }
> }
> ```
Configure [result webhooks](/docs/webhooks-and-events/webhooks-overview) to receive analysis data automatically.
> [accordion] Via API
>
> Retrieve call results including analysis data:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> GET /v1/calls/{call_id}/result
> ```
Response includes `analysis_results` with all configured analyses.
### Via Dashboard
View analysis results in the call history:
1. Navigate to Calls page
2. Select completed call
3. View "Analysis Results" section
## Common Use Cases
### Customer Support
**Labels:** Sentiment, resolution status, issue category, follow-up needs
**Use:** Update support tickets, measure satisfaction, identify escalation needs
### Sales Qualification
**Labels:** Interest level, budget discussed, decision maker status, timeline
**Use:** Score leads, prioritize follow-ups, update CRM automatically
### Appointment Scheduling
**Labels:** Confirmation status, appointment details, reminders needed
**Use:** Update calendar systems, send confirmations, schedule reminders
### Survey Collection
**Labels:** Ratings, scores, feedback, willingness to follow up
**Use:** Aggregate survey data, identify promoters/detractors, analyze trends
### Compliance Verification
**Labels:** Required disclosures made, consent obtained, information provided
**Use:** Quality assurance, regulatory compliance, agent performance tracking
### Product Feedback
**Labels:** Products mentioned, feature requests, pain points, competitive intel
**Use:** Product roadmap, competitive analysis, customer insights
## Technical Considerations
### Analysis Accuracy
Post-call analysis is typically 85-95% accurate:
* Clear conversations with specific information are easiest to analyze
* Vague or ambiguous conversations may result in "unable to determine" for some labels
* Enum labels are generally more accurate than free-form string labels
### Processing Time
Analysis occurs after call completion:
* Typically processes within 5-30 seconds after call ends
* Complex analyses with many fields may take longer
* Results delivered via webhook once processing completes
### Transcript Quality
Analysis accuracy depends on transcript quality:
* Clear audio improves extraction accuracy
* Background noise or crosstalk can affect results
* Proper speech recognition configuration helps
### Multiple Analyses
You can configure multiple analysis forms:
* Each runs independently
* Results are namespaced by analysis name
* Use multiple forms to organize different data extraction needs
### Data Privacy
Be mindful of data privacy:
* Only analyze information you have legitimate need for
* Consider applicable data privacy regulations when labeling personal data
* Analysis results flow through webhooks—ensure secure transmission
## Measuring Effectiveness
### Key Metrics
* **Label completion rate** - Percentage of calls with all required labels populated
* **Accuracy rate** - Manual verification of label correctness
* **Unable to determine rate** - How often labels can't be determined from conversation
* **Downstream integration success** - Do CRM/analytics systems receive correct data?
### Quality Assurance Process
1. **Sample Review** - Manually verify 10-20 call analyses weekly
2. **Compare to Transcripts** - Ensure labeled data matches conversation content
3. **Track "Unable to Determine"** - Identify patterns in analysis failures
4. **Refine Descriptions** - Improve label descriptions based on accuracy results
5. **Adjust Requirements** - Make fewer labels required if analysis often fails
## Troubleshooting
### Problem: Field Consistently Shows "Unable to Determine"
**Solution:** Description may be too vague or information genuinely not in conversations. Review transcripts to verify information is discussed. Improve label description with examples. Consider making field optional if not always applicable.
### Problem: Wrong Enum Value Assigned
**Solution:** Enum values may be ambiguous or similar. Use more distinct value names. Improve label description to clarify when each value should be used. Add examples: "positive (customer expresses satisfaction)".
### Problem: String Fields Contain Too Much Text
**Solution:** Refine description to request "brief summary" or "one sentence". Be specific about length expectations. Consider using enum instead if values are predictable.
### Problem: Numbers Determined Incorrectly
**Solution:** Clarify in description what format numbers should be in. Example: "Rating from 1-5" vs. "Percentage from 0-100". Verify transcripts actually contain numeric values.
### Problem: Analysis Results Not in Webhook
**Solution:** Verify result webhook is configured. Check analysis is enabled. Ensure call completed successfully (analysis only runs for completed calls). Review webhook logs for delivery issues.
## Integration Examples
> [accordion] CRM Integration
>
> Use webhook to update CRM when calls complete:
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> // Webhook receiver
> app.post('/call-result-webhook', (req, res) => {
> const { call_id, analysis_results } = req.body;
>
> const analysis = analysis_results["Support Call Analysis"];
>
> // Update CRM
> crm.updateTicket({
> callId: call_id,
> sentiment: analysis.customer_sentiment,
> resolved: analysis.issue_resolved,
> category: analysis.issue_category,
> followUpNeeded: analysis.follow_up_needed
> });
>
> res.sendStatus(200);
> });
> ```
> [accordion] Escalation Workflow
>
> Trigger manager alerts for negative calls:
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> if (analysis.customer_sentiment === "negative" && !analysis.issue_resolved) {
> notificationService.alertManager({
> priority: "high",
> subject: "Negative call requiring follow-up",
> callId: call_id
> });
> }
> ```
> [accordion] Analytics Pipeline
>
> Stream analysis data to analytics warehouse:
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> analyticsDB.insert({
> timestamp: new Date(),
> callId: call_id,
> sentiment: analysis.customer_sentiment,
> resolved: analysis.issue_resolved,
> category: analysis.issue_category
> });
> ```
## Next steps
> [card] [Webhooks](/docs/webhooks-and-events/webhooks-overview)
>
> Receive analysis results automatically
> [card] [Tools & Functions](/docs/create/tools-and-functions)
>
> Extend agent capabilities during calls
> [card] [Knowledge Bases](/docs/advanced-features/knowledge-base)
>
> Improve response quality
> [card] [Call History](/docs/monitor/call-history)
>
> Track conversation metrics
# Play Audio Before Conversations Start
Source: https://blackbox.dasha.ai/docs/advanced-features/pre-conversation-media
Play a recorded message or audio file immediately when calls connect, before your AI agent speaks. Use for compliance disclosures, greetings, or branded intros.
Play an audio file the moment a call connects — before your agent says anything. Use it for compliance disclosures, branded greetings, or hold music that plays while the conversation initializes.
**What you'll learn:** How to configure pre-conversation media, enable it per call type, and upload custom audio files.
***
## When to use pre-conversation media
| Use case | Example |
| - | - |
| **Compliance disclosures** | "This call may be recorded for quality assurance" |
| **Branded greetings** | Company jingle or professional intro |
| **Legal notices** | Privacy or terms acknowledgment |
| **Hold music** | Brief audio while the agent initializes |
The audio plays once, immediately when the call connects, and cannot be interrupted by the caller.
***
## Configure pre-conversation media
> [tab] Dashboard
>
> 1. Open your agent's configuration
> 2. Navigate to the **Features** tab
> 3. Find **Pre-Conversation Media** and toggle it on
> 4. Select a media file from your uploaded files
> 5. Enable for specific call types (inbound, outbound, web)
> 6. Save your agent
> [tab] API
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> 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: 'Support Agent',
> config: {
> features: {
> preConversationMedia: {
> isEnabled: true,
> mediaFilename: 'compliance-disclosure.mp3',
> enabledForInbound: true,
> enabledForOutbound: true,
> enabledForWebCall: false
> }
> }
> // ... other config
> }
> })
> });
> ```
***
## Configuration options
| Field | Type | Default | Description |
| - | - | - | - |
| `isEnabled` | boolean | `false` | Master toggle for the feature |
| `mediaFilename` | string | `null` | Filename of uploaded media to play |
| `enabledForInbound` | boolean | `false` | Play media on incoming calls |
| `enabledForOutbound` | boolean | `false` | Play media on outgoing calls |
| `enabledForWebCall` | boolean | `false` | Play media on browser-based calls |
***
## Upload media files
Before using pre-conversation media, upload your audio file:
> [tab] Dashboard
>
> 1. Navigate to **Media** in the sidebar
> 2. Click **Upload** and select your audio file
> 3. The filename will appear in the pre-conversation media dropdown
> [tab] API
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> const formData = new FormData();
> formData.append('file', audioFile);
>
> const response = await fetch('https://blackbox.dasha.ai/api/v1/media/upload', {
> method: 'POST',
> headers: {
> 'Authorization': 'Bearer YOUR_API_KEY'
> },
> body: formData
> });
>
> const { filename } = await response.json();
> // Use this filename in preConversationMedia.mediaFilename
> ```
**Supported formats:** MP3, WAV, OGG
**Recommended specs:**
* Duration: 3–10 seconds (keep it brief)
* Sample rate: 44.1kHz or 48kHz
* Bit depth: 16-bit minimum
***
## Call type behavior
Enable pre-conversation media independently for each call type:
| Call type | When it plays | Typical use |
| - | - | - |
| **Inbound** | When customer calls your agent | "Thank you for calling..." |
| **Outbound** | When agent calls a customer | "This is an automated call from..." |
| **Web call** | When user starts browser call | Branded intro for web widget |
> [accordion] Example: Inbound-only compliance
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> preConversationMedia: {
> isEnabled: true,
> mediaFilename: 'recording-notice.mp3',
> enabledForInbound: true,
> enabledForOutbound: false, // Outbound calls skip the intro
> enabledForWebCall: false
> }
> ```
> [accordion] Example: All call types
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> preConversationMedia: {
> isEnabled: true,
> mediaFilename: 'welcome-message.mp3',
> enabledForInbound: true,
> enabledForOutbound: true,
> enabledForWebCall: true
> }
> ```
***
## Troubleshooting
### Audio doesn't play
| Symptom | Fix |
| - | - |
| No audio on any calls | Check `isEnabled` is `true` and media file exists |
| No audio on specific call type | Enable the call type flag (`enabledForInbound`, etc.) |
| 404 error on media | Re-upload the file and update the filename |
### Audio quality issues
| Issue | Fix |
| - | - |
| Clipping or distortion | Re-encode at lower volume (-3dB headroom) |
| Too quiet | Normalize audio before upload |
| Wrong format | Convert to MP3, WAV, or OGG |
***
## Next steps
> [card] [Talk First](/docs/advanced-features/talk-first)
>
> Control agent's opening greeting
> [card] [Ambient Noise](/docs/advanced-features/ambient-noise)
>
> Add background sounds
> [card] [Voice & Speech](/docs/create/voice-and-speech)
>
> Configure TTS voice
> [card] [Inbound Calls](/docs/deploy/inbound-calls)
>
> Set up incoming call handling
# Handle Caller Silence with Reminders and Timeouts
Source: https://blackbox.dasha.ai/docs/advanced-features/silence-management
Automatically handle caller silence with configurable reminders and timeouts. When callers go silent, your agent prompts ('Are you still there?') and gracefully ends calls after no response. Prevents calls from hanging indefinitely when callers walk away, put phones down, or lose connection.
Handle abandoned calls gracefully. When callers go silent, your agent prompts them with reminders and eventually ends the call — preventing indefinite waits that waste resources.
**What you'll learn:** Reminder configuration, silence thresholds, timeout actions, and re-engagement strategies.
## Why Use Silence Management?
### Prevents Indefinite Calls
Callers sometimes walk away from calls without hanging up, causing agents to wait indefinitely. Silence management detects inactivity and ends these abandoned calls.
### Maintains Caller Engagement
Reminders can re-engage callers who are distracted or temporarily stepped away, giving them opportunities to continue the conversation.
### Improves Metrics
Automatically ending inactive calls provides accurate completion metrics and prevents inflated call duration statistics.
### Cost Control
Indefinitely waiting for silent callers wastes resources and incurs unnecessary costs. Silence management terminates these calls efficiently.
### Better User Experience
Polite reminders show attentiveness while timeouts provide closure instead of leaving calls in limbo.
## How to Configure Silence Management
### Step 1: Enable Silence Management
1. Open your agent's configuration
2. Navigate to the **Features** tab
3. Find **Silence Management** and toggle it on
### Step 2: Configure Reminder Settings
**Max Reminder Attempts** (0-10)
* Number of times agent will prompt caller before taking action
* 0 = No reminders, jump straight to timeout or end call
* 1-3 = Recommended for most use cases
* 4-6 = Moderate patience, multiple opportunities to re-engage
* 7-10 = Very patient, may feel excessive to callers
**Reminder Silence Threshold** (1-30 seconds)
* How long the caller must be silent before agent sends a reminder
* 5-10 seconds = Quick response to silence
* 10-15 seconds = Moderate patience (recommended)
* 15-30 seconds = Very patient, allows long pauses
**Example:** With threshold of 10 seconds and 3 max attempts:
1. Caller silent for 10 seconds → First reminder
2. Still silent for 10 more seconds → Second reminder
3. Still silent for 10 more seconds → Third reminder
4. Still silent → Action taken (end call or timeout)
### Step 3: Configure End Behavior
**End When Reminder Limit Exceeded**
* Toggle: Yes or No
* If enabled: Call ends after all reminder attempts are exhausted
* If disabled: Call continues indefinitely (not recommended)
**Recommended:** Enable to prevent indefinite calls
### Step 4: Configure Extended Silence Timeout (Optional)
**Extended Silence Timeout** (minimum 10 seconds, optional)
* Hard timeout for absolute silence regardless of reminders
* If caller is completely silent (no speech, no background noise), call ends after this duration
* Provides safety net even if reminder system doesn't trigger
**When to use:**
* Enable for outbound campaigns (prevents stuck calls)
* Consider disabling for inbound support (callers may need time to gather information)
**Recommended value:** 30-60 seconds for most use cases
## Configuration Examples
> [accordion] Example: Efficient Outbound Campaign
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "silenceManagement": "enabled",
> "maxReminderAttempts": 2,
> "reminderSilenceThreshold": 8,
> "endWhenLimitExceeded": true,
> "extendedSilenceTimeout": 30
> }
> ```
>
> **Rationale:** Quick, efficient handling. If caller is unresponsive after two prompts, end call and move on.
> [accordion] Example: Patient Customer Support
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "silenceManagement": "enabled",
> "maxReminderAttempts": 4,
> "reminderSilenceThreshold": 12,
> "endWhenLimitExceeded": true,
> "extendedSilenceTimeout": 60
> }
> ```
>
> **Rationale:** Give callers multiple opportunities to respond. They may be looking for information or thinking.
> [accordion] Example: Survey Collection
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "silenceManagement": "enabled",
> "maxReminderAttempts": 3,
> "reminderSilenceThreshold": 10,
> "endWhenLimitExceeded": true,
> "extendedSilenceTimeout": 45
> }
> ```
>
> **Rationale:** Balanced approach. Surveys need responses, but give reasonable time to think about answers.
> [accordion] Example: Aggressive Timeout (High Volume)
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "silenceManagement": "enabled",
> "maxReminderAttempts": 1,
> "reminderSilenceThreshold": 6,
> "endWhenLimitExceeded": true,
> "extendedSilenceTimeout": 20
> }
> ```
>
> **Rationale:** Maximize efficiency. Single prompt, then move on. Best for high-volume, low-engagement scenarios.
## Reminder Phrase Examples
Configure reminder phrases in your system prompt:
**Polite Reminders:**
* "I'm sorry, I didn't hear that. Are you still there?"
* "Hello? Can you hear me okay?"
* "Did you have any questions for me?"
* "I want to make sure I didn't lose you. Are you still with me?"
**Contextual Reminders:**
* "Take your time. Let me know when you're ready."
* "I'm here when you have that information."
* "No rush—I'll wait while you check."
**Final Attempt:**
* "I haven't heard from you in a while. Should we continue this conversation?"
* "I'll need to end the call soon if I don't hear back."
## Common Use Cases
### Outbound Appointment Reminders
* **Configuration:** 3 reminders, 10-second threshold, 45-second extended timeout
* **Why:** Give callers time to check schedules, but end efficiently if no response
### Inbound Customer Support
* **Configuration:** 5 reminders, 15-second threshold, 60-second extended timeout
* **Why:** Callers may be gathering information or multitasking; be patient
### Lead Qualification
* **Configuration:** 2 reminders, 8-second threshold, 30-second extended timeout
* **Why:** Uninterested leads often go silent; move on quickly
### Survey Collection
* **Configuration:** 3 reminders, 12-second threshold, 45-second extended timeout
* **Why:** Respondents need time to think, but surveys should progress
### Technical Support Triage
* **Configuration:** 4 reminders, 15-second threshold, no extended timeout
* **Why:** Users may be checking settings or restarting devices; be very patient
## Monitoring and Optimization
### Key Metrics
* **Silence-triggered endings** - What percentage of calls end due to silence?
* **Average reminders sent** - How many prompts before callers respond or call ends?
* **Re-engagement rate** - Do reminders successfully bring callers back?
* **Caller feedback** - Do callers mention feeling rushed or interrupted?
### Optimization Signals
**High silence ending rate** (>15%)
* Thresholds may be too aggressive
* Consider increasing silence threshold
* Add more reminder attempts
**Low re-engagement after reminders**
* Reminders may not be effective
* Review reminder phrasing
* Consider reducing attempts if they never work
**Caller complaints about interruptions**
* Threshold too short for use case
* Increase to 12-15 seconds
* Review types of questions requiring longer think time
**Many calls hitting extended timeout**
* Extended timeout may be too short
* Or indicates many abandoned/stuck calls
* Analyze call patterns to determine root cause
## Technical Considerations
### Audio Processing
Silence detection uses voice activity detection (VAD):
* Distinguishes speech from background noise
* Background noise alone counts as silence
* Brief utterances ("um", "uh") reset timer
### Reminder Timing
Reminders are sent by the agent naturally within conversation flow:
* Agent speaks reminder phrase
* Waits for caller response
* If still silent, timer continues
### Compatibility
Silence management works across:
* ✅ Outbound phone calls
* ✅ Inbound phone calls
* ✅ Web-based voice calls
* ✅ All agent configurations
## Troubleshooting
### Problem: Reminders Trigger During Long Pauses
**Solution:** Increase silence threshold to 15-20 seconds. Some questions require extended thinking time. Review question complexity.
### Problem: Calls Never End Despite Silence
**Solution:** Verify "End When Limit Exceeded" is enabled. Enable extended silence timeout as backup. Check that reminders are configured properly.
### Problem: Too Many Calls Ending Due to Silence
**Solution:** Increase silence threshold to give more time. Review call recordings to understand why callers go silent. Consider adding more context-aware reminder phrases.
### Problem: Reminders Feel Abrupt or Rude
**Solution:** Increase silence threshold before first reminder. Review reminder phrasing in system prompt for politeness. Consider contextual reminders ("Take your time").
### Problem: Extended Timeout Triggering Too Often
**Solution:** Increase timeout duration to 60-90 seconds. Or disable if reminder system is working well. Check for network issues causing false silence detection.
> [accordion] System Prompt Integration
>
> Include silence handling guidance:
>
> ```
> If the caller is silent for a while, politely check if they're still there or if
> they need more time. Use phrases like "Take your time" or "Are you still there?"
>
> If you send multiple reminders without response, explain that you'll need to end
> the call soon: "I'll need to end our call if I don't hear from you."
> ```
## Next steps
> [card] [Maximum Call Duration](/docs/advanced-features/max-call-duration)
>
> Set time-based call limits
> [card] [Fillers](/docs/advanced-features/fillers)
>
> Add verbal pauses during processing
> [card] [Talk First](/docs/advanced-features/talk-first)
>
> Control conversation initiation
> [card] [IVR Detection](/docs/advanced-features/ivr-detection)
>
> Handle voicemail and automated systems
# Configure Your Agent to Speak First on Calls
Source: https://blackbox.dasha.ai/docs/advanced-features/talk-first
Configure your Dasha BlackBox voice agent to speak first when calls connect instead of waiting for callers. Essential for outbound calls where callers don't know who's calling or why. Control opening greetings ('Hi, this is Alex from [Company]...'), timing, and interruptibility to set context and eliminate confusion.
Start conversations proactively. Configure your agent to greet callers first instead of waiting — essential for outbound campaigns where callers need immediate context.
**What you'll learn:** Opening phrase configuration, variable substitution, timing settings, and interruptibility options.
## Why Use Talk First?
### Establishes Professional Tone
Starting with a professional greeting immediately signals this is a legitimate, intentional call. Particularly important for outbound campaigns where callers might be uncertain who's calling.
### Sets Conversation Context
Proactively stating the call's purpose helps callers understand what to expect: "Hi, this is Alex calling about your appointment tomorrow."
### Reduces Caller Confusion
Especially on outbound calls, callers may be unsure why they're being contacted. An opening greeting eliminates this uncertainty immediately.
### Controls Conversation Flow
By speaking first, your agent establishes the conversational rhythm and can guide the interaction from the start.
### Saves Time
Instead of "Hello?" "Hello?" exchanges, the agent immediately states the purpose and moves the conversation forward.
## How to Configure Talk First
### Step 1: Enable Talk First
1. Open your agent's configuration
2. Navigate to the **Features** tab
3. Find **Talk First** and toggle it on
### Step 2: Configure Opening Phrase
Enter the text your agent should speak when the call connects.
> [accordion] Using Static Text
>
> ```
> Hi, this is Sarah from Acme Corp calling about your service appointment scheduled for tomorrow. Do you have a moment to confirm?
> ```
> [accordion] Using Variables
>
> Insert dynamic information into your greeting using double curly braces:
>
> ```
> Hello {{customer_name}}, this is {{agent_name}} calling from {{company_name}}. I'm following up on your recent inquiry about {{product_name}}.
> ```
**Supported variables:**
* Any custom variable passed when creating the call
* `{{agent_name}}` - The agent's configured name
* `{{customer_name}}` - Caller's name if provided
* `{{company_name}}` - Your company name
* `{{appointment_time}}` - Appointment details
* Any other data passed via API
### Step 3: Set Delay Before Speaking
Control when the agent begins speaking after the call connects:
**Delay Range:** 0-10 seconds (adjustable in 0.5 second increments)
**Recommended delays:**
* **0 seconds**: Immediate greeting, agent speaks instantly
* **0.5-1 second**: Brief pause, feels more natural (recommended for most cases)
* **2-3 seconds**: Longer pause, gives caller time to settle
* **4+ seconds**: Extended pause, rarely needed
**Why delay matters:**
* Very short delays (0-0.5s) can feel abrupt
* Moderate delays (0.5-1.5s) feel most natural to callers
* Long delays (2s+) may cause callers to speak first, defeating Talk First's purpose
**Recommended starting point:** 0.5 seconds
### Step 4: Configure Interruptibility
Choose whether callers can interrupt the opening greeting:
#### Interruptible (Enabled)
Callers can start speaking at any point during the greeting. The agent stops and listens.
**When to use:**
* Professional conversations where caller input is valued
* Scenarios where callers might need to quickly say "Wrong number" or "Not a good time"
* Most customer service applications
#### Non-Interruptible (Disabled)
Agent completes the entire greeting before listening for caller response.
**When to use:**
* Critical information that must be delivered completely
* Legal disclaimers or compliance statements
* Very brief greetings (under 5 seconds) where interruption is unnecessary
**Recommended:** Enable interruptibility for most use cases (gives callers control).
## Configuration Examples
> [accordion] Example: Appointment Reminder (Interruptible)
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "talkFirst": "enabled",
> "openingPhrase": "Hi {{customer_name}}, this is Alex from {{clinic_name}} calling to remind you about your appointment tomorrow at {{appointment_time}}. Can you confirm you'll be able to make it?",
> "delay": 0.5,
> "interruptible": true
> }
> ```
>
> **Result:** Professional, immediate greeting with dynamic personalization. Caller can interrupt if needed.
> [accordion] Example: Survey Call (Brief Greeting)
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "talkFirst": "enabled",
> "openingPhrase": "Hello, this is Jordan from Market Research Inc. Do you have 3 minutes for a brief survey?",
> "delay": 1,
> "interruptible": true
> }
> ```
>
> **Result:** Clear, concise purpose statement. Respects caller's time by stating duration upfront.
> [accordion] Example: Customer Follow-up (Personalized)
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "talkFirst": "enabled",
> "openingPhrase": "Hi {{customer_name}}, it's Taylor from {{company_name}}. I'm calling to follow up on your recent purchase of {{product_name}}. How has everything been working for you?",
> "delay": 0.5,
> "interruptible": true
> }
> ```
>
> **Result:** Warm, personalized greeting that immediately establishes context and shows care.
> [accordion] Example: Emergency Notification (Non-Interruptible)
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "talkFirst": "enabled",
> "openingPhrase": "This is an emergency notification from {{organization_name}}. Please listen carefully to the following important information.",
> "delay": 0.5,
> "interruptible": false
> }
> ```
>
> **Result:** Critical information delivered without interruption. Appropriate for urgent alerts.
## Common Use Cases
### Appointment Reminders
* **Configuration:** Brief greeting, caller's name, specific appointment details, confirmation question
* **Why:** Callers expect reminder calls to state appointment time immediately
### Sales Follow-ups
* **Configuration:** Friendly greeting, reference to previous interaction, value proposition
* **Why:** Establishes context for relationship and reason for follow-up
### Customer Service Callbacks
* **Configuration:** Personalized greeting, reference to support ticket or inquiry
* **Why:** Immediately reminds caller of their request and shows responsiveness
### Survey Invitations
* **Configuration:** Brief introduction, estimated time commitment, optional incentive mention
* **Why:** Respects caller's time by being upfront about what's being asked
### Emergency Notifications
* **Configuration:** Clear identification, urgency indicator, non-interruptible if critical
* **Why:** Ensures critical information is delivered completely and quickly
## Technical Considerations
### Call Connection Timing
Talk First activates when:
* Outbound calls: Call is answered
* Inbound calls: Connection is established
* Web calls: Session begins
The configured delay begins counting from the moment of connection.
### Variable Interpolation
Variables are replaced with actual values at call time:
* Variables must be passed when creating the call (via API or dashboard)
* Undefined variables render as empty strings
* Ensure all required variables are provided to avoid awkward gaps
### Multi-language Support
Talk First works with all configured agent languages:
* Opening phrase is spoken in the agent's primary language
* [Language Switching](/docs/advanced-features/language-switching) can occur after greeting
* Consider crafting opening phrases that work across languages if language is caller-selected
### Compatibility
Talk First works across all call types:
* ✅ Outbound phone calls (most common use case)
* ✅ Inbound phone calls
* ✅ Web-based voice calls
* ⚠️ Inbound calls: Callers may expect to speak first, use carefully
## Troubleshooting
### Problem: Caller Speaks Over Greeting
**Solution:** Reduce delay to 0.3-0.5 seconds so agent begins speaking faster. Verify interruptibility is enabled so agent can respond when interrupted.
### Problem: Greeting Feels Abrupt
**Solution:** Increase delay to 0.8-1.2 seconds. Very short delays can feel robotic.
### Problem: Greeting Too Long
**Solution:** Shorten opening phrase to under 15 seconds. Get to the point faster—long introductions lose caller attention.
### Problem: Variables Not Replacing
**Solution:** Verify variable names match exactly (case-sensitive). Ensure variables are passed when creating the call. Check for typos in variable names.
### Problem: Callers Confused About Call Purpose
**Solution:** Revise opening phrase to state purpose within first 5 seconds. Be explicit about why you're calling.
## Measuring Effectiveness
Track these metrics to evaluate Talk First impact:
* **Call completion rate** - Clear greetings may improve completions
* **Time to caller response** - Measure how quickly callers engage after greeting
* **Wrong number rate** - Clear identification reduces wrong number complaints
* **Caller satisfaction** - Survey whether callers appreciated knowing call purpose immediately
## Next steps
> [card] [Ambient Noise](/docs/advanced-features/ambient-noise)
>
> Background sounds improve professionalism
> [card] [Language Switching](/docs/advanced-features/language-switching)
>
> Adapt language after greeting if needed
> [card] [Fillers](/docs/advanced-features/fillers)
>
> Natural pauses during processing
> [card] [Voice & Speech](/docs/create/voice-and-speech)
>
> Configure voice settings
# Control Turn Taking with VAD Modes
Source: https://blackbox.dasha.ai/docs/advanced-features/turn-taking
Choose the voice activity detection (VAD) mode that decides when a caller has finished speaking. Compare asap_v1, asap_v2, and the Deepgram Flux pipeline.
Turn taking decides when the caller has finished speaking and the agent may reply. The `turnTaking` feature selects the voice activity detection (VAD) mode for the main customer call.
**What you'll learn:** What each VAD mode does, how to select one, and how the Flux mode falls back on unsupported languages.
## Configuration
Set the mode at `config.features.turnTaking`:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"config": {
"features": {
"turnTaking": {
"version": "v1",
"vad": "asap_v2"
}
}
}
}
```
In the UI, the setting lives on the **Voice & Speech** tab under **Turn Taking**.
## VAD modes
| Mode | Behavior |
| - | - |
| `asap_v1` | Legacy VAD behavior. |
| `asap_v2` | Improved VAD tuned for faster turn detection. **Default.** |
| `flux` | Runs speech recognition and turn detection on the Deepgram Flux pipeline, which models end of turn directly instead of relying on silence length. |
Omitting `turnTaking` or `vad` uses `asap_v2`.
## Flux language support and fallback
The Flux pipeline supports these languages: English, Spanish, French, German, Hindi, Russian, Portuguese, Japanese, Italian, and Dutch.
> [!NOTE]
>
> If the agent's language is not in this list, or the Flux connection fails at call start, the call automatically falls back to the legacy VAD pipeline. The call proceeds normally either way.
## Scope
The setting applies only to the main customer call. Warm-transfer and operator legs keep their own defaults.
# Search activity log
Source: https://blackbox.dasha.ai/docs/api-reference/activitylogs/search-activity-log
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/activity-logs/search
Searches activity log events with filtering by type, severity, caller, date range,
and free-text search on message and metadata. Returns paginated results with
aggregated counts for types, severities, and callers.
## Search Capabilities
* **Type filtering**: Filter by event type (Webhook, ToolCall, ApiRequest, McpCall, Scheduler, WebInterfaceCall)
* **Severity filtering**: Filter by severity level (Info, Warning, Error, Critical)
* **Caller filtering**: Filter by who initiated the action (User, System)
* **Date range filtering**: Filter by event timestamp
* **Agent/Call filtering**: Filter by specific agent IDs or call IDs
* **Full-text search**: Search across event messages and metadata
* **Aggregations**: Get counts grouped by type, severity, and caller
## Search Examples
```json Basic Search
{
"page": 0,
"size": 20,
"sortField": "timestamp",
"sortDirection": "Descending"
}
```
```json Filter by Type and Severity
{
"types": ["Webhook", "ToolCall"],
"severities": ["Error", "Critical"],
"size": 50
}
```
```json Filter by Agent and Date Range
{
"agentIds": ["agent-123"],
"fromDate": "2026-03-01T00:00:00Z",
"toDate": "2026-03-03T23:59:59Z"
}
```
```json Text Search
{
"searchText": "timeout",
"callers": ["System"],
"size": 100
}
```
# Clone agent
Source: https://blackbox.dasha.ai/docs/api-reference/agents/clone-agent
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/agents/{agentId}/clone
Creates a copy of an existing agent with a new name. The clone inherits the source agent's complete
configuration (voice, TTS, LLM, features, webhooks, tools) but is always created in a disabled state
and without inbound SIP config to avoid phone number routing conflicts.
**What is copied:**
- Voice and TTS configuration
- LLM and STT configuration
- Features (transfer settings, recording, ambient noise, RAG, etc.)
- Webhooks and MCP connections
- Custom tools
- Outbound SIP configuration
- Schedule
- AdditionalData (default prompt variables)
**What is NOT copied:**
- Inbound SIP config — each agent requires its own dedicated SIP endpoint; assign a phone number separately after cloning
- The clone is always created with `isEnabled: false` regardless of the source agent's state
**Response:** Returns only the new agent ID. Use the Get agent endpoint to retrieve the full configuration.
# Create agent
Source: https://blackbox.dasha.ai/docs/api-reference/agents/create-agent
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/agents
Creates a new AI voice agent with the specified configuration. The system automatically generates
a unique agent ID and assigns infrastructure resources. The response includes the created agent
with all assigned infrastructure details and generated identifiers.
ElevenLabs, Cartesia, Inworld and xAI voice IDs are checked with the provider. A confirmed missing voice returns 400;
unavailable checks do not prevent saving. Other providers are not checked.
## Before You Begin
> [!NOTE]
>
> Ensure all referenced resources exist before creating an agent:
* **Media files** for hold music or background sounds must be uploaded first
* **Pronunciation dictionaries** must be created if referenced
* **SIP configuration** must be set up if using warm transfer
## Required Configuration
At minimum, you must provide:
* Agent name (unique within your organization)
* Voice configuration (voice ID and language)
* TTS (Text-to-Speech) configuration
# Delete agent
Source: https://blackbox.dasha.ai/docs/api-reference/agents/delete-agent
https://blackbox.dasha.ai/swagger/v1/swagger.json delete /api/v1/agents/{agentId}
Permanently deletes an AI voice agent from your organization. This operation removes the agent
configuration and infrastructure assignments but preserves historical call records.
> [!WARNING]
>
> This operation permanently deletes the agent and cannot be undone.
## What Gets Deleted
* Agent configuration and all settings
* Infrastructure resource assignments
* Webhook configurations
* SIP configuration
## What Is Preserved
* **Call history** remains accessible with references to this agent ID
* **Media files** used by the agent are not deleted
* **Pronunciation dictionaries** used by the agent are not deleted
## Impact on Active Calls
Active calls using this agent will continue until completion but use the configuration snapshot from when the call started.
# Get agent
Source: https://blackbox.dasha.ai/docs/api-reference/agents/get-agent
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/agents/{agentId}
Retrieves detailed configuration for a specific AI voice agent using its unique identifier (UUID).
The response includes all agent settings: voice configuration, TTS settings, enabled features
(call transfer, recording, ambient noise), SIP configuration, webhook URLs, and infrastructure assignments.
**Agent Identifier Format:** UUID (e.g., "123e4567-e89b-12d3-a456-426614174000")
**Response Includes:**
- Agent name and description
- Voice and TTS configuration
- Feature flags (transfer, recording, etc.)
- Inbound and outbound SIP configuration
- Webhook configuration
- Infrastructure assignments (server regions)
# Get agents linked to knowledge base
Source: https://blackbox.dasha.ai/docs/api-reference/agents/get-agents-linked-to-knowledge-base
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/agents/knowledge-base/list
Retrieves a list of all agents in your organization that are connected to knowledge bases.
This endpoint helps you understand which agents have knowledge base integrations enabled.
**Query Options:**
- Without parameters: Returns all agents with any knowledge base links
- With knowledgeBaseId: Returns only agents linked to the specified knowledge base
**Response Format:**
Each item includes:
- Agent ID and name
- List of knowledge base IDs linked to the agent
- Link creation timestamps
**Use Cases:**
- Track which agents use specific knowledge bases
- Identify agents that need knowledge base configuration
- Manage knowledge base access across agents
# List agents
Source: https://blackbox.dasha.ai/docs/api-reference/agents/list-agents
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/agents
Retrieves a paginated list of all AI voice agents within your organization.
Each agent in the response includes complete configuration details including voice settings,
TTS configuration, features, and infrastructure assignments.
**Pagination Parameters:**
- Default page size: 20 agents
- Maximum page size: 1000 agents
- Minimum skip value: 0
**Use Cases:**
- Display agents in a management dashboard
- Export agent configurations
- Monitor agent inventory across your organization
# Update agent
Source: https://blackbox.dasha.ai/docs/api-reference/agents/update-agent
https://blackbox.dasha.ai/swagger/v1/swagger.json put /api/v1/agents/{agentId}
Updates an existing AI voice agent with a new configuration. This is a full replacement operation
where all fields in the request body replace the existing configuration.
ElevenLabs, Cartesia, Inworld and xAI voice IDs are checked with the provider. A confirmed missing voice returns 400;
unavailable checks do not prevent saving. Other providers are not checked.
> [!WARNING]
>
> This is a full replacement operation (PUT). All fields in the request body replace the existing configuration.
## Best Practice for Partial Updates
1. GET the current agent configuration
2. Modify only the fields you want to change
3. PUT the complete updated configuration back
## Important Notes
* Omitted fields will be set to their default values or null
* Active calls continue with the old configuration until completion
* Changes take effect immediately for new calls
# Search call results
Source: https://blackbox.dasha.ai/docs/api-reference/callresults/search-call-results
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/callresults/search
Searches historical call results with advanced filtering, full-text search, nested JSON queries,
and aggregations. Supports complex queries including date ranges, status filters, agent filtering,
and custom field searches within call additional data.
## Search Capabilities
* **Date range filtering**: Filter by creation or completion time
* **Status filtering**: Filter by call status (Completed, Failed, etc.)
* **Agent filtering**: Search calls for specific agents
* **Full-text search**: Search across call transcripts and metadata
* **Nested JSON queries**: Query custom fields in call additional data
* **Aggregations**: Get statistics grouped by custom fields
* **Sorting**: Sort by any field with ascending/descending order
## Search Examples
```json Basic Search
{
"page": 0,
"size": 20,
"fromDate": "2024-01-01T00:00:00Z",
"toDate": "2024-01-31T23:59:59Z",
"callStatuses": ["Completed", "Failed"],
"includeAggregations": true
}
```
```json Text Search
{
"searchText": "connection timeout",
"size": 50
}
```
```json Agent Filtering
{
"agentIds": ["agent-123", "agent-456"],
"endpoint": "sales-webhook",
"includeAggregations": true
}
```
```json Nested JSON Search
{
"additionalDataFilters": {
"result.postCallAnalysis.info.age": { "gt": 36 },
"result.postCallAnalysis.info.name": "Andrew",
"result.postCallAnalysis.sentiment": "positive"
}
}
```
```json Complex Search
{
"fromDate": "2024-01-01T00:00:00Z",
"callStatuses": ["Completed"],
"additionalDataFilters": {
"result.postCallAnalysis.info.age": { "gte": 25, "lte": 65 }
},
"includeAggregations": true,
"aggregationFields": ["result.postCallAnalysis.info.city", "result.postCallAnalysis.sentiment"],
"sortField": "completedTime",
"sortDirection": "Descending",
"size": 100
}
```
## Use Cases
* **Analytics dashboards**: Aggregate call data by custom metrics
* **Quality assurance**: Search calls by sentiment or specific keywords
* **Compliance tracking**: Filter calls by date range and status
* **Custom reporting**: Query nested JSON fields from post-call analysis
# Cancel call
Source: https://blackbox.dasha.ai/docs/api-reference/calls/cancel-call
https://blackbox.dasha.ai/swagger/v1/swagger.json delete /api/v1/calls/{callId}
Cancels a scheduled call and removes it from the queue. Triggers a webhook notification
with call deadline status. This operation cannot cancel calls that are already in progress.
> [!NOTE]
>
> This operation only cancels scheduled calls. Active calls in progress cannot be canceled through this endpoint.
## What Happens
1. Call is removed from the queue
2. Webhook notification is sent with deadline status
3. Call status is updated to canceled
## Impact
* **Scheduled calls**: Successfully canceled before execution
* **Active calls**: Cannot be canceled (use call control endpoints instead)
* **Completed calls**: Cannot be canceled
# Create bulk calls
Source: https://blackbox.dasha.ai/docs/api-reference/calls/create-bulk-calls
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/calls/bulk
Schedules multiple outbound voice calls with an AI agent in a single request.
Each call receives a unique ID and calculated schedule time. This endpoint is optimized
for batch operations and campaign management.
## Bulk Operations
Use this endpoint for:
* **Campaign management**: Schedule multiple calls for marketing campaigns
* **Batch notifications**: Send reminders or alerts to multiple recipients
* **List processing**: Process contact lists efficiently
## Performance
* Maximum recommended batch size: 1000 calls
* All calls use the same agent configuration
* Calls are processed and scheduled atomically
# Create call
Source: https://blackbox.dasha.ai/docs/api-reference/calls/create-call
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/calls
Schedules a new outbound voice call with an AI agent. The system assigns a unique call ID
and calculates the schedule time based on the provided deadline and timezone.
## Call Scheduling
Calls are scheduled based on:
* **Deadline**: Target time for call completion (ISO 8601 format)
* **Timezone**: Timezone for scheduling (default: UTC)
* **Priority**: Call priority level (affects queue ordering)
## Required Fields
* Agent ID (query parameter)
* Destination endpoint (phone number or SIP URI)
* Call deadline
## Response
The response includes the created call with assigned call ID and calculated next schedule time.
# Get call
Source: https://blackbox.dasha.ai/docs/api-reference/calls/get-call
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/calls/{callId}
Retrieves detailed information for a specific call including status, timestamps,
endpoint information, and additional data associated with the call.
# Get call queue
Source: https://blackbox.dasha.ai/docs/api-reference/calls/get-call-queue
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/calls/queue/list
Retrieves the current call queue for your organization with filtering options.
Shows scheduled and pending calls that have not yet been completed. Unlike the general
call list endpoint, this focuses on active queue items.
# Get call recording
Source: https://blackbox.dasha.ai/docs/api-reference/calls/get-call-recording
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/calls/media/{recordId}
Streams call recording audio as MP3. Supports both inline streaming for browser playback
and file downloads. This endpoint is publicly accessible without authentication.
## Playback Options
* **inBrowser=true** (default): Streams inline for browser playback
* **inBrowser=false**: Forces file download as `call_{recordId}.mp3`
## Public Access
> [!NOTE]
>
> This endpoint does not require authentication and can be accessed publicly.
## Use Cases
* Embed recordings in web applications
* Direct playback in audio players
* Download recordings for offline review
# Get call statistics
Source: https://blackbox.dasha.ai/docs/api-reference/calls/get-call-statistics
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/calls/statistics/statuses
Retrieves aggregated call statistics grouped by status. Combines data from both
the active queue and historical records to provide complete metrics.
# Get SIP traces
Source: https://blackbox.dasha.ai/docs/api-reference/calls/get-sip-traces
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/calls/{callId}/sip-traces
Retrieves SIP protocol traces for a specific call, identified by its blackbox call ID.
The system resolves the internal server job ID from the call record and fetches
SIP signaling data including INVITE, ACK, BYE messages and their
raw content, useful for debugging telephony connectivity issues.
# Register inbound call
Source: https://blackbox.dasha.ai/docs/api-reference/calls/register-inbound-call
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/calls/register
Registers an inbound call that your telephony already holds and returns the SIP destination to bridge it to.
Use this when you own the inbound call flow and decide per call which agent should answer. The call record is
created up front with the supplied variables, so the call ID you receive here is the same ID on the result
webhook, call results and recordings. Bridge the live call to the returned SIP URI and the agent starts.
## Register-then-bridge flow
1. Your telephony receives the inbound call and decides which agent should answer.
2. Call this endpoint with the agent ID, the caller number and any variables the agent needs.
3. Store the returned `callId` and bridge the live call to the returned `sipUri` (`sip:{callId}@sip-reg.blackbox.dasha.ai`).
4. The agent answers as soon as the call arrives. Results arrive on the agent's result webhook with the same `callId`.
## Deadline
`callDeadline` is how long the registration stays valid. If the call is not bridged by then, it is canceled and reported through the result webhook. Default is 10 minutes, maximum 24 hours.
## Response
The response includes the assigned `callId`, the `sipUri` to bridge to, and the stored settings. The call has status `Registered` until the audio arrives.
# End a chat session under the `user_end` reason.
Source: https://blackbox.dasha.ai/docs/api-reference/chats/end-a-chat-session-under-the-`user_end`-reason
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/chats/{id}/end
Runs the same lifecycle pipeline a voice call's completion does: post-call analysis,
completion webhook, Postgres CallResult, Elasticsearch index, audit event. Idempotent —
calling on an already-final session returns the current snapshot without re-running the
pipeline.
# List chat sessions matching the supplied filters.
Source: https://blackbox.dasha.ai/docs/api-reference/chats/list-chat-sessions-matching-the-supplied-filters
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/chats
Ordered by `last_activity` descending. Default filter is `state=active` —
pass `state=final` or `state=all` to broaden. `updated_after` is useful
for incremental sync.
# Open a new chat session.
Source: https://blackbox.dasha.ai/docs/api-reference/chats/open-a-new-chat-session
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/chats
Mints a server-side session bound to the named agent on the named channel. The agent is
frozen for the session's lifetime. `external_id` is optional but recommended for
channel-driven sessions (SMS, web widget) — it lets the server dedupe duplicate
open-session requests for the same external endpoint via a partial unique index.
## Sessions vs. completions
Stateful sessions (`/api/v1/chats`) are the **server-owned** counterpart of the stateless
`/api/v1/text-chat/completion` endpoint. Use sessions when the transport itself is asynchronous
(SMS, persistent web chat) and the client cannot reliably carry the encrypted state envelope
across turns.
# Retrieve a chat session — full transcript and lifecycle status.
Source: https://blackbox.dasha.ai/docs/api-reference/chats/retrieve-a-chat-session-—-full-transcript-and-lifecycle-status
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/chats/{id}
# Submit one user turn to an existing chat session.
Source: https://blackbox.dasha.ai/docs/api-reference/chats/submit-one-user-turn-to-an-existing-chat-session
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/chats/{id}/messages
Drives the agent through one LLM round-trip and returns only the new assistant turn(s)
(tool turns first, final reply last). The full transcript stays on the server. Supply
`idempotency_key` to make the submit safely retryable — a repeated request with the
same key (even after the original response finalised the session) replays the previous
assistant turn without re-running the LLM.
## Idempotency
Network retries (especially over SMS) can re-submit the same logical turn twice. Always send an
`idempotency_key` (any client-chosen unique value, e.g. UUID or `sessionId+turnNumber`) so the
server can dedupe. The retry returns the prior assistant response — including when the original
turn finalised the session.
# Delete a document
Source: https://blackbox.dasha.ai/docs/api-reference/document/delete-a-document
https://blackbox.dasha.ai/swagger/v1/swagger.json delete /api/v1/rag/document/{id}
# Download document content
Source: https://blackbox.dasha.ai/docs/api-reference/document/download-document-content
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/rag/document/{id}/download
# Get document chunk information
Source: https://blackbox.dasha.ai/docs/api-reference/document/get-document-chunk-information
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/rag/document/chunks/{chunkId}
# Get document chunks
Source: https://blackbox.dasha.ai/docs/api-reference/document/get-document-chunks
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/rag/document/{id}/chunks
# Get document details with status
Source: https://blackbox.dasha.ai/docs/api-reference/document/get-document-details-with-status
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/rag/document/{id}
# List documents in a knowledge base
Source: https://blackbox.dasha.ai/docs/api-reference/document/list-documents-in-a-knowledge-base
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/rag/document
# Update a document content in KB
Source: https://blackbox.dasha.ai/docs/api-reference/document/update-a-document-content-in-kb
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/rag/document/{id}
# Upload a document to a knowledge base
Source: https://blackbox.dasha.ai/docs/api-reference/document/upload-a-document-to-a-knowledge-base
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/rag/document
# Create a new knowledge base
Source: https://blackbox.dasha.ai/docs/api-reference/knowledgebase/create-a-new-knowledge-base
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/rag/kb
# Delete a knowledge base and all its content
Source: https://blackbox.dasha.ai/docs/api-reference/knowledgebase/delete-a-knowledge-base-and-all-its-content
https://blackbox.dasha.ai/swagger/v1/swagger.json delete /api/v1/rag/kb/{id}
# Get all knowledge
Source: https://blackbox.dasha.ai/docs/api-reference/knowledgebase/get-all-knowledge
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/rag/kb
# Get knowledge base details with statistics
Source: https://blackbox.dasha.ai/docs/api-reference/knowledgebase/get-knowledge-base-details-with-statistics
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/rag/kb/{id}
# Update knowledge base settings
Source: https://blackbox.dasha.ai/docs/api-reference/knowledgebase/update-knowledge-base-settings
https://blackbox.dasha.ai/swagger/v1/swagger.json put /api/v1/rag/kb/{id}
# Add a URL source to a knowledge base
Source: https://blackbox.dasha.ai/docs/api-reference/knowledgebasesource/add-a-url-source-to-a-knowledge-base
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/rag/kb/{kbId}/sources
Crawls the pages of a URL into the knowledge base and queues the first crawl at once. Each page becomes one
Markdown document that starts with "#
" and "Source: "; its URL is stored on the document,
and its metadata holds urlSourceId. Re-crawls skip unchanged pages, update changed ones, add new ones and delete the documents of
pages that are gone; when a crawl finds fewer than half as many pages as the previous one, nothing is removed
and lastRun.warning says why. Within a knowledge base a page is held by one URL source only. robots.txt is
respected.
# Crawl a URL source now
Source: https://blackbox.dasha.ai/docs/api-reference/knowledgebasesource/crawl-a-url-source-now
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/rag/kb/{kbId}/sources/{sourceId}/crawl
Queues a crawl whatever the re-crawl schedule. Follow it with the lastRun field of the source.
# Get a URL source
Source: https://blackbox.dasha.ai/docs/api-reference/knowledgebasesource/get-a-url-source
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/rag/kb/{kbId}/sources/{sourceId}
Returns the source, when its next automatic re-crawl starts, and its latest crawl with page counts. Poll it to
follow a crawl from "queued" through "running" to "completed" or "failed".
# Get the page usage of all URL sources
Source: https://blackbox.dasha.ai/docs/api-reference/knowledgebasesource/get-the-page-usage-of-all-url-sources
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/rag/sources/usage
Pages held by all your URL sources, across all knowledge bases, and the most they may hold together.
# List the pages of a URL source
Source: https://blackbox.dasha.ai/docs/api-reference/knowledgebasesource/list-the-pages-of-a-url-source
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/rag/kb/{kbId}/sources/{sourceId}/pages
Returns the pages found by crawls, sorted by URL, with the knowledge base document that holds each page and the
document's state. Pages that are gone from the site, or whose document was deleted, are listed as "removed".
# List the URL sources of a knowledge base
Source: https://blackbox.dasha.ai/docs/api-reference/knowledgebasesource/list-the-url-sources-of-a-knowledge-base
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/rag/kb/{kbId}/sources
# Remove a URL source
Source: https://blackbox.dasha.ai/docs/api-reference/knowledgebasesource/remove-a-url-source
https://blackbox.dasha.ai/swagger/v1/swagger.json delete /api/v1/rag/kb/{kbId}/sources/{sourceId}
Stops the source's crawls and deletes the documents of its pages, as deleting a file does.
# Update the settings of a URL source
Source: https://blackbox.dasha.ai/docs/api-reference/knowledgebasesource/update-the-settings-of-a-url-source
https://blackbox.dasha.ai/swagger/v1/swagger.json put /api/v1/rag/kb/{kbId}/sources/{sourceId}
Saves new settings without starting a crawl; the next crawl uses them. The URL of a source cannot change: add
a new URL source to crawl a different address. After narrowing the scope, the path patterns or the page limit,
the next completed crawl removes the pages left out even when they are more than half of the previous crawl.
# Verify MCP connection
Source: https://blackbox.dasha.ai/docs/api-reference/mcp/verify-mcp-connection
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/mcp/verify
Verifies a Model Context Protocol (MCP) connection and discovers available tools.
Use this endpoint to test MCP server connectivity before configuring an agent.
## Model Context Protocol (MCP)
MCP enables agents to connect to external services and data sources through a standardized protocol.
Verify connections before configuring them on agents to ensure proper connectivity and tool discovery.
## Verification Process
The verification:
1. Tests connectivity to the MCP server
2. Discovers available tools and resources
3. Returns connection status and available capabilities
## Use Cases
* Test MCP server configuration before adding to an agent
* Discover what tools an MCP server provides
* Troubleshoot MCP connection issues
# Delete media file
Source: https://blackbox.dasha.ai/docs/api-reference/media/delete-media-file
https://blackbox.dasha.ai/swagger/v1/swagger.json delete /api/v1/media/{id}
Permanently deletes a media file and automatically removes all references from agents
that use this file. The deletion is performed in two stages: first removing agent
references, then deleting the file itself.
> [!WARNING]
>
> This operation permanently deletes the media file and cannot be undone.
## Cascade Deletion
The deletion process follows this sequence:
1. **Remove agent references**: All agents using this media file are updated automatically
2. **Delete file**: The media file is permanently removed
## What Gets Updated
Agents are automatically updated if they use the media file for:
* Warm transfer hold music
* Cold transfer hold music
* Ambient noise/background sounds
## Error Handling
If removing agent references fails, the media file is **NOT** deleted to ensure data consistency. You can safely retry the operation.
# Download media file
Source: https://blackbox.dasha.ai/docs/api-reference/media/download-media-file
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/media/{id}/download
Downloads the media file content as a stream with appropriate Content-Disposition header
for file download.
# Get agents using media
Source: https://blackbox.dasha.ai/docs/api-reference/media/get-agents-using-media
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/media/{id}/affected-agents
Returns a list of agents that use the specified media file in their configuration.
Each agent entry includes the usage context (warmTransfer, coldTransfer, or ambientNoise)
indicating where the media is used.
# Get media file
Source: https://blackbox.dasha.ai/docs/api-reference/media/get-media-file
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/media/{id}
Retrieves metadata for a specific media file including file name, description,
upload timestamp, file size, and content type.
# List media files
Source: https://blackbox.dasha.ai/docs/api-reference/media/list-media-files
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/media
Retrieves all media files for your organization with pagination support.
Returns metadata including file names, descriptions, upload dates, and file sizes.
Set fileName to look up the file that an agent configuration references by its stored file name.
# Update media file
Source: https://blackbox.dasha.ai/docs/api-reference/media/update-media-file
https://blackbox.dasha.ai/swagger/v1/swagger.json patch /api/v1/media/{id}
Updates the description of an existing media file. This is a partial update (PATCH)
that only modifies the description field. Set description to null or empty string to clear it.
# Upload media file
Source: https://blackbox.dasha.ai/docs/api-reference/media/upload-media-file
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/media
Uploads a new audio file for use with AI agents. Only audio content types (audio/*) are accepted.
The uploaded file can be used for hold music, background sounds, or other audio features.
## Supported Formats
Only audio files are accepted. Supported formats include:
* MP3 (audio/mpeg)
* WAV (audio/wav)
* OGG (audio/ogg)
* Other audio/\* MIME types
## File Requirements
* File cannot be empty
* Content-Type header must start with `audio/`
* Maximum file size limits apply (contact support for details)
## Use Cases
Uploaded media files can be used for:
* **Hold music** during call transfers
* **Background sounds** for ambient noise
* **Custom audio prompts**
# Get agent template
Source: https://blackbox.dasha.ai/docs/api-reference/misc/get-agent-template
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/misc/agent-initial-data
Retrieves a template agent configuration with language-specific default values for creating a new agent.
Useful for initializing agent forms with appropriate defaults based on language.
# Get capabilities of available models
Source: https://blackbox.dasha.ai/docs/api-reference/misc/get-capabilities-of-available-models
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/rag/misc/capabilities
# Get concurrency limits
Source: https://blackbox.dasha.ai/docs/api-reference/misc/get-concurrency-limits
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/misc/concurrency
Retrieves the concurrent call limit for your organization and the current number of active calls.
Use this endpoint to monitor capacity and check if new calls can be initiated.
# Get current organization
Source: https://blackbox.dasha.ai/docs/api-reference/misc/get-current-organization
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/misc/me
Retrieves the organization ID associated with the current API key.
Useful for verifying authentication and organization context.
# Get platform capabilities
Source: https://blackbox.dasha.ai/docs/api-reference/misc/get-platform-capabilities
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/misc/capabilities
Retrieves platform capabilities for the current deployment instance.
Returns the list of available LLM models and IVR voice recognition availability.
Each model includes a provider field and a deprecated flag.
This endpoint is publicly accessible and does not require authentication.
# Get server configuration
Source: https://blackbox.dasha.ai/docs/api-reference/misc/get-server-configuration
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/misc
Retrieves server configuration information including authentication server URL and SIP server
settings. This public endpoint does not require authentication and provides essential
connectivity information for client initialization.
# List predefined background sounds
Source: https://blackbox.dasha.ai/docs/api-reference/misc/list-predefined-background-sounds
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/misc/background-sounds
Retrieves the list of predefined background sounds that can be configured for agents to play during calls.
Background sounds help create a more natural call environment by adding ambient audio.
# List predefined built-in tools
Source: https://blackbox.dasha.ai/docs/api-reference/misc/list-predefined-built-in-tools
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/misc/builtin-tools
Retrieves the list of predefined built-in tools that can be configured for agents.
Built-in tools provide standard functionality that agents can use during conversations.
# List predefined builtin media
Source: https://blackbox.dasha.ai/docs/api-reference/misc/list-predefined-builtin-media
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/misc/builtin-media
Retrieves the list of predefined builtin media files that can be used for agent features
like pre-conversation media playback. These are pre-uploaded to the platform.
# Add pronunciation rules
Source: https://blackbox.dasha.ai/docs/api-reference/pronunciationdictionaries/add-pronunciation-rules
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/pronunciation-dictionaries/{providerId}/add-rules
Adds new pronunciation rules to an existing dictionary. After adding rules,
automatically updates all agents using this dictionary with the new configuration.
## Provider Restrictions
Some providers have restrictions on rule types:
* Certain providers may only support alias rules
* Phoneme rules may require specific phonetic alphabet formats
If you attempt to add an unsupported rule type, you will receive a 400 Bad Request error.
# Create pronunciation dictionary
Source: https://blackbox.dasha.ai/docs/api-reference/pronunciationdictionaries/create-pronunciation-dictionary
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/pronunciation-dictionaries
Creates a new pronunciation dictionary with pronunciation rules for specific words.
Supports alias rules (word substitutions) and phoneme rules (phonetic pronunciations).
Provider-specific rule restrictions may apply.
## Rule Types
Pronunciation dictionaries support two types of rules:
**Alias Rules** (word substitutions):
* Replace one word with another
* Example: "CEO" → "Chief Executive Officer"
**Phoneme Rules** (phonetic pronunciations):
* Specify exact pronunciation using IPA (International Phonetic Alphabet)
* Example: "Kubernetes" → "kjˈuːbənˌiːts"
> [!NOTE]
>
> Some providers only support alias rules. Check provider-specific documentation for rule type restrictions.
# Delete pronunciation dictionary
Source: https://blackbox.dasha.ai/docs/api-reference/pronunciationdictionaries/delete-pronunciation-dictionary
https://blackbox.dasha.ai/swagger/v1/swagger.json delete /api/v1/pronunciation-dictionaries/{providerId}
Permanently deletes a pronunciation dictionary and automatically removes all references
from agents that use this dictionary.
> [!WARNING]
>
> This operation permanently deletes the pronunciation dictionary and cannot be undone.
## Cascade Deletion
The deletion process automatically:
1. Deletes the pronunciation dictionary
2. Removes references from all agents using this dictionary
3. Updates affected agent configurations
Check affected agents before deletion using the `/affected-agents` endpoint.
# Get agents using pronunciation dictionary
Source: https://blackbox.dasha.ai/docs/api-reference/pronunciationdictionaries/get-agents-using-pronunciation-dictionary
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/pronunciation-dictionaries/{providerId}/affected-agents
Returns a list of agents that use the specified pronunciation dictionary.
Use this endpoint to check which agents will be affected before modifying or deleting a dictionary.
## Use Cases
Check affected agents before:
* **Deleting a dictionary**: Understand which agents will lose pronunciation customizations
* **Removing rules**: Identify agents that rely on specific pronunciation rules
* **Planning updates**: Coordinate dictionary changes with agent configurations
# Get pronunciation dictionary
Source: https://blackbox.dasha.ai/docs/api-reference/pronunciationdictionaries/get-pronunciation-dictionary
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/pronunciation-dictionaries/{providerId}
Retrieves a specific pronunciation dictionary by its identifier including
all pronunciation rules and metadata.
# List pronunciation dictionaries
Source: https://blackbox.dasha.ai/docs/api-reference/pronunciationdictionaries/list-pronunciation-dictionaries
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/pronunciation-dictionaries
Retrieves all pronunciation dictionaries for your organization. Pronunciation dictionaries
customize how agents pronounce specific words during conversations.
# Remove pronunciation rules
Source: https://blackbox.dasha.ai/docs/api-reference/pronunciationdictionaries/remove-pronunciation-rules
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/pronunciation-dictionaries/{providerId}/remove-rules
Removes pronunciation rules from an existing dictionary. After removing rules,
automatically updates all agents using this dictionary with the new configuration.
# Delete provider
Source: https://blackbox.dasha.ai/docs/api-reference/providers/delete-provider
https://blackbox.dasha.ai/swagger/v1/swagger.json delete /api/v1/providers/{id}
Deletes a provider integration and performs complete cascade cleanup including:
removal of all associated phone numbers, SIP credentials, and external resources (SIP trunks, credential lists).
This operation is irreversible and will affect any agents using phone numbers from this provider.
> [!WARNING]
>
> This operation is irreversible and will permanently delete the provider and all associated resources.
## Cascade Deletion
When you delete a provider, the following resources are also deleted:
* **Phone Numbers**: All phone numbers imported from this provider are removed
* **SIP Credentials**: Auto-configured SIP credentials for the provider are deleted
* **External Resources**: SIP trunks and credential lists in the provider's account are cleaned up
## Impact on Agents
If any agents are using phone numbers from this provider:
* Their inbound call routing will stop working
* Outbound calls using these phone numbers will fail
* You may need to reconfigure agents with new phone numbers
## Before Deleting
Consider using the provider's phone numbers endpoint to review what will be affected before proceeding.
# Get provider
Source: https://blackbox.dasha.ai/docs/api-reference/providers/get-provider
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/providers/{id}
Retrieves a specific provider integration by its unique identifier.
Returns the appropriate derived type based on the provider type, including provider-specific configuration details.
The response uses polymorphic serialization with the providerType discriminator.
# List providers
Source: https://blackbox.dasha.ai/docs/api-reference/providers/list-providers
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/providers
Retrieves all VoIP provider integrations for your organization with support for pagination.
Returns polymorphic responses with provider-specific details based on the provider type.
The providerType field acts as a discriminator to identify the specific provider implementation.
# Verify provider
Source: https://blackbox.dasha.ai/docs/api-reference/providers/verify-provider
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/providers/{id}/verify
Triggers a comprehensive verification of the provider integration.
Validates credentials, checks SIP trunk configuration, verifies credential lists, and confirms phone number attachments.
Updates the provider's verification status and returns detailed check results for troubleshooting.
## Verification Checks
The verification process performs the following checks:
* **Credentials**: Validates that the provider's API credentials are still valid and have sufficient permissions
* **Trunk**: Verifies the SIP trunk exists and is properly configured
* **Credential List**: Confirms the credential list is attached to the trunk
* **Phone Numbers**: Checks that imported phone numbers are still attached to the trunk
## Verification Status
Based on the check results, the provider status is updated to one of:
| Status | Description |
| - | - |
| **verified** | All checks passed successfully |
| **warning** | Non-critical issues detected (e.g., phone detached from trunk) |
| **failed** | Critical failure (e.g., invalid credentials, trunk not found) |
## Automatic Verification
Providers are automatically verified on an hourly schedule. Use this endpoint to trigger an immediate verification when needed.
# Search within a multi knowledge bases
Source: https://blackbox.dasha.ai/docs/api-reference/search/search-within-a-multi-knowledge-bases
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/rag/search
# Create SIP credential
Source: https://blackbox.dasha.ai/docs/api-reference/sipcredentials/create-sip-credential
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/sip-credentials
Creates new SIP credentials for authenticating with a SIP trunk provider. The credentials
can be associated with phone numbers to enable inbound and outbound calling through
the SIP provider's infrastructure.
## SIP Credential Components
SIP credentials typically include:
* **Server address**: The SIP trunk provider's server hostname or IP
* **Authentication username**: Username for SIP authentication (some providers call this "Account" or "Account ID")
* **Password**: Password for SIP authentication
* **Transport protocol**: TCP, UDP, or TLS for SIP signaling
* **TLS settings**: Optional TLS configuration for encrypted connections
## Transport Protocols
Choose the appropriate transport protocol based on your provider's requirements:
* **UDP**: Standard SIP protocol, lightweight but unencrypted
* **TCP**: Reliable transport with connection management
* **TLS**: Encrypted transport for secure SIP signaling
# Delete SIP credential
Source: https://blackbox.dasha.ai/docs/api-reference/sipcredentials/delete-sip-credential
https://blackbox.dasha.ai/swagger/v1/swagger.json delete /api/v1/sip-credentials/{id}
Deletes a SIP credential from your organization. If the credential is associated with phone numbers,
use the force parameter to automatically delete all associated phone numbers before deleting the credential.
## Deletion Modes
**Normal deletion** (force=false):
* Fails if credential has associated phone numbers
* Returns 409 Conflict if phone numbers are using this credential
**Force deletion** (force=true):
* Automatically deletes all associated phone numbers
* Updates affected agents to remove phone number references
* Completes deletion even if phone numbers were using the credential
> [!WARNING]
>
> Force deletion will permanently delete all phone numbers associated with this credential, which may affect agents configured to use those numbers for inbound or outbound calls.
> [!WARNING]
>
> Credentials managed by a VoIP provider (such as Twilio) are read-only and cannot be deleted directly. To remove provider-managed credentials, delete the provider integration instead.
## Best Practice
Check affected agents before deletion using the `/affected-agents` endpoint to understand the impact.
# Get agents using SIP credential
Source: https://blackbox.dasha.ai/docs/api-reference/sipcredentials/get-agents-using-sip-credential
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/sip-credentials/{id}/affected-agents
Returns a list of agents that use phone numbers associated with this SIP credential,
grouped by phone number. Also includes the count of calls currently in queue that
use these credentials.
## Response Information
This endpoint returns:
* **Agents grouped by phone number**: Shows which agents use each phone number for inbound/outbound calls
* **Queued calls count**: Number of calls currently in queue that use phone numbers with these credentials
## Relationship Hierarchy
SIP credentials are used through this hierarchy:
1. **SIP Credentials** → authenticate with SIP trunk provider
2. **Phone Numbers** → use credentials to enable calling
3. **Agents** → use phone numbers for inbound/outbound calls
## Use Cases
* **Before updating credentials**: Check which agents and queued calls will be affected
* **Before deleting credentials**: Understand the full impact on agents and active operations
* **Troubleshooting**: Identify all resources using a specific SIP provider
# Get SIP credential
Source: https://blackbox.dasha.ai/docs/api-reference/sipcredentials/get-sip-credential
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/sip-credentials/{id}
Retrieves a specific SIP credential by its unique identifier including
server configuration, authentication details, and associated phone numbers.
# List SIP credentials
Source: https://blackbox.dasha.ai/docs/api-reference/sipcredentials/list-sip-credentials
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/sip-credentials
Retrieves all SIP credentials for your organization with support for pagination and search.
SIP credentials store authentication information for connecting to SIP trunk providers,
including server addresses, usernames, passwords, and optional TLS settings.
# Update SIP credential
Source: https://blackbox.dasha.ai/docs/api-reference/sipcredentials/update-sip-credential
https://blackbox.dasha.ai/swagger/v1/swagger.json put /api/v1/sip-credentials/{id}
Updates an existing SIP credential configuration. This is a full replacement
operation (PUT) that updates all credential settings including server address,
authentication details, and transport protocol.
## Automatic Updates
When you update SIP credentials, all phone numbers associated with these credentials automatically use the updated authentication settings for all future calls. No additional configuration is required.
> [!WARNING]
>
> Credentials managed by a VoIP provider (such as Twilio) are read-only and cannot be modified. To remove provider-managed credentials, delete the provider integration instead.
# Add custom SIP domain
Source: https://blackbox.dasha.ai/docs/api-reference/sipdomains/add-custom-sip-domain
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/sip-domains
Registers a hostname you control as a SIP domain for registered inbound calls. The domain starts in
PendingVerification. Publish the DNS records from the response, then call verify. Once Active, pass its id as
sipDomainId when registering a call to receive sip:{callId}@{your-domain}.
## DNS records
The response contains two kinds of records:
* **Verification** — a `TXT` record at `_dasha-verify.{domain}` proving you control the hostname. Required before the domain can be verified.
* **Routing** — a `CNAME` from the domain to the Dasha SIP host, so that calls placed to `sip:{callId}@{domain}` reach Dasha. SIP phones and PBXs resolve the host with A records, which the CNAME provides. Use a dedicated hostname: a CNAME cannot share its name with other records.
DNS changes can take a few minutes to propagate. Call the verify endpoint once the TXT record is visible.
# Delete custom SIP domain
Source: https://blackbox.dasha.ai/docs/api-reference/sipdomains/delete-custom-sip-domain
https://blackbox.dasha.ai/swagger/v1/swagger.json delete /api/v1/sip-domains/{id}
Removes the domain from the Dasha platform and from your organization. Calls already registered on the domain can no longer be bridged.
# Get custom SIP domain
Source: https://blackbox.dasha.ai/docs/api-reference/sipdomains/get-custom-sip-domain
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/sip-domains/{id}
# List custom SIP domains
Source: https://blackbox.dasha.ai/docs/api-reference/sipdomains/list-custom-sip-domains
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/sip-domains
Returns every custom SIP domain of your organization with its verification status and the DNS records to publish.
# Update inbound routing of a custom SIP domain
Source: https://blackbox.dasha.ai/docs/api-reference/sipdomains/update-inbound-routing-of-a-custom-sip-domain
https://blackbox.dasha.ai/swagger/v1/swagger.json patch /api/v1/sip-domains/{id}
Sets the agent that answers every inbound call on the domain whose SIP user part is not a registered call id, so
your PBX or carrier can send calls to sip:anything@your-domain and the agent picks up. Registered calls keep
precedence. Pass null to stop routing such calls (they are rejected with SIP 404).
# Verify custom SIP domain
Source: https://blackbox.dasha.ai/docs/api-reference/sipdomains/verify-custom-sip-domain
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/sip-domains/{id}/verify
Looks up the DNS TXT verification record. When it matches, the domain is registered on the Dasha platform and
becomes Active. When it does not, the domain stays PendingVerification and lastError explains what was expected;
the call still returns 200. The response also reports whether routing records already point at Dasha.
# Create phone number
Source: https://blackbox.dasha.ai/docs/api-reference/sipphonenumbers/create-phone-number
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/sip-phone-numbers
Creates a new SIP phone number in your organization. The phone number can be linked
to an agent for inbound call handling.
## Phone Number Uniqueness
Phone numbers have specific uniqueness constraints:
* **Same phone number in multiple organizations**: The same phone number can exist across different organizations
* **Organization-level uniqueness**: Within your organization, each phone number and credential ID pair must be unique
This allows different organizations to use the same phone number with different SIP providers.
# Delete phone number
Source: https://blackbox.dasha.ai/docs/api-reference/sipphonenumbers/delete-phone-number
https://blackbox.dasha.ai/swagger/v1/swagger.json delete /api/v1/sip-phone-numbers/{id}
Deletes a SIP phone number from your organization. If the phone number is linked to agents,
use the force parameter to automatically remove the link before deletion.
## Deletion Modes
**Normal deletion** (force=false):
* Fails if phone number is linked to any agents
* Returns 409 Conflict if agents are using this number
**Force deletion** (force=true):
* Automatically unlinks phone number from all agents
* Updates affected agents to remove the phone number reference
* Completes deletion even if agents were using the number
## Best Practice
Check affected agents before deletion using the `/affected-agents` endpoint to understand the impact.
# Get agents using phone number
Source: https://blackbox.dasha.ai/docs/api-reference/sipphonenumbers/get-agents-using-phone-number
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/sip-phone-numbers/{id}/affected-agents
Returns a list of agents that use this SIP phone number. Phone numbers can be used for
both inbound call routing (linked agent) and outbound calls (agents configured to use
this number for making calls).
## Usage Types
Phone numbers can be used by agents in two ways:
**Inbound (Linked Agent):**
* One agent can be linked to receive inbound calls on this number
* Incoming calls are automatically routed to the linked agent
**Outbound:**
* Multiple agents can use this number for making outbound calls
* The number appears as caller ID when agents make calls
This endpoint returns all agents using the phone number for either inbound or outbound purposes.
# Get phone number
Source: https://blackbox.dasha.ai/docs/api-reference/sipphonenumbers/get-phone-number
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/sip-phone-numbers/{id}
Retrieves a specific SIP phone number by its unique identifier including
linked agent information if applicable.
# Link phone number to agent
Source: https://blackbox.dasha.ai/docs/api-reference/sipphonenumbers/link-phone-number-to-agent
https://blackbox.dasha.ai/swagger/v1/swagger.json put /api/v1/sip-phone-numbers/{id}/agent-link
Links a SIP phone number to an agent for handling inbound or outbound calls.
If the phone number was previously linked to another agent for inbound, it will
automatically unlink from the previous agent and link to the new one.
For outbound, replaces the agent's current outbound phone number (only one supported).
> [!WARNING]
>
> If the phone number is already linked to a different agent for inbound, the previous agent link will be automatically removed and replaced with the new agent link.
> [!NOTE]
>
> When linking a phone number to an agent for inbound, the phone number must be globally unique across the entire system for this operation. If the same phone number is already linked in another organization, the linking operation will fail.
## Inbound Call Routing (mode=inbound)
When a phone number is linked to an agent for inbound:
* Inbound calls to this number are automatically routed to the agent
* The agent handles the conversation using its configured voice and behavior
* Only one agent can be linked to a phone number at a time for inbound
## Outbound Calling (mode=replaceOutbound)
When a phone number is linked to an agent for outbound:
* The agent can use this phone number as caller ID when making outbound calls
* Replaces any existing outbound phone number for the agent (only one supported)
## Use Cases
* Dedicated customer support lines (mode=inbound)
* Campaign-specific tracking numbers (mode=inbound)
* Outbound calling with specific caller ID (mode=replaceOutbound)
# List phone numbers
Source: https://blackbox.dasha.ai/docs/api-reference/sipphonenumbers/list-phone-numbers
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/sip-phone-numbers
Retrieves all SIP phone numbers for your organization with support for pagination and filtering.
Filter by phone number, linked agent, or unlinked status.
# Unlink phone number from agent
Source: https://blackbox.dasha.ai/docs/api-reference/sipphonenumbers/unlink-phone-number-from-agent
https://blackbox.dasha.ai/swagger/v1/swagger.json delete /api/v1/sip-phone-numbers/{id}/agent-link
Removes the link between a SIP phone number and its associated agent.
After unlinking inbound, calls to this number will not be routed to any agent.
After unlinking outbound, the agent will no longer use this number for outbound calls.
## After Unlinking
Once unlinked:
* If mode=inbound: Inbound calls to this number will not be routed to any agent
* If mode=replaceOutbound: The specified agent will no longer use this number for making outbound calls
* The phone number becomes available to link to a different agent
# Update phone number
Source: https://blackbox.dasha.ai/docs/api-reference/sipphonenumbers/update-phone-number
https://blackbox.dasha.ai/swagger/v1/swagger.json put /api/v1/sip-phone-numbers/{id}
Updates an existing SIP phone number configuration. This is a full replacement
operation (PUT) that updates all phone number settings.
## Phone Number Uniqueness
Phone numbers have specific uniqueness constraints:
* **Same phone number in multiple organizations**: The same phone number can exist across different organizations
* **Organization-level uniqueness**: Within your organization, each phone number and credential ID pair must be unique
# Run one stateless text-chat completion turn.
Source: https://blackbox.dasha.ai/docs/api-reference/textchat/run-one-stateless-text-chat-completion-turn
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/text-chat/completion
Statelessness: the client carries an opaque encrypted `state` blob between turns.
The server decodes the state, drives the agent's orchestration loop (OpenAI ChatCompletions +
tool calls — built-in, agent-defined webhook, or MCP), and returns the new messages plus a
fresh encrypted state. The conversation transcript is owned by the client.
# Create Twilio provider
Source: https://blackbox.dasha.ai/docs/api-reference/twilioprovider/create-twilio-provider
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/providers/twilio
Creates a new Twilio provider integration with automatic SIP trunk configuration.
Validates credentials with Twilio, creates a SIP trunk, sets up credential lists,
and generates SIP credentials for call routing. All credentials are encrypted before storage.
## Automatic SIP Trunk Setup
When you create a Twilio provider, the following resources are automatically configured:
1. **SIP Trunk**: A new trunk is created in your Twilio account with termination URI
2. **Credential List**: A credential list is created and attached to the trunk
3. **SIP Credentials**: Username/password credentials are generated for call authentication
4. **Local Records**: Provider and SIP credentials are stored securely in your organization
## Credential Requirements
Your Twilio credentials must have the following permissions:
* Read access to account information
* Create/manage SIP trunking resources
* Create/manage credential lists
* Read incoming phone numbers
## Security
* Auth Token is encrypted before storage
* Account SID is stored as plain text (it's a non-sensitive identifier)
* Auth Token is never exposed in API responses
* SIP passwords are randomly generated (32 characters)
## After Creation
Once the provider is created:
1. Use the `/available-numbers` endpoint to see phone numbers in your Twilio account
2. Import desired phone numbers using the `/import-numbers` endpoint
3. Link imported phone numbers to agents for call handling
# Get Twilio provider
Source: https://blackbox.dasha.ai/docs/api-reference/twilioprovider/get-twilio-provider
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/providers/twilio/{id}
Retrieves a specific Twilio provider integration with all Twilio-specific configuration details.
Returns the complete provider configuration including AccountSid, TrunkSid, TerminationUri, Region, and call transfer settings.
For a generic provider response without Twilio-specific fields, use the GET /api/v1/providers/{id} endpoint.
## Twilio-Specific Response
This endpoint returns Twilio-specific configuration details not available in the generic provider endpoint:
| Field | Description |
| - | - |
| **accountSid** | Your Twilio Account SID (non-sensitive identifier) |
| **trunkSid** | SID of the auto-configured SIP trunk |
| **terminationUri** | SIP termination URI for the trunk |
| **region** | Twilio region for the trunk (us1, us2, ie1, de1, etc.) |
| **supportsCallTransfer** | Whether call transfer is enabled |
## Security Note
The Auth Token is **never** exposed in API responses for security reasons. Only the Account SID is returned as it is a non-sensitive identifier used for display purposes.
## Related Endpoints
* **Generic provider**: `GET /api/v1/providers/{id}` - Returns polymorphic response with base provider fields
* **Update provider**: `PUT /api/v1/providers/twilio/{id}` - Update Twilio-specific configuration
* **Available numbers**: `GET /api/v1/providers/twilio/{id}/available-numbers` - List phone numbers in Twilio account
# Import phone numbers
Source: https://blackbox.dasha.ai/docs/api-reference/twilioprovider/import-phone-numbers
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/providers/twilio/{id}/import-numbers
Imports phone numbers from Twilio into the system for use with agents.
Attaches each number to the provider's SIP trunk and creates local records for call routing.
Supports partial success - continues importing remaining numbers if some fail.
## Import Process
For each phone number SID provided:
1. Validates the SID exists in your Twilio account
2. Checks for duplicate imports (already imported numbers are skipped with error)
3. Attaches the phone number to the provider's SIP trunk in Twilio
4. Creates a local phone number record linked to the provider
## Partial Success
The import operation continues even if some numbers fail. The response includes:
| Field | Description |
| - | - |
| **successCount** | Number of successfully imported phone numbers |
| **failedCount** | Number of phone numbers that failed to import |
| **errors** | Detailed error information for each failure |
## Common Errors
| Error | Cause |
| - | - |
| **Not found** | Phone number SID doesn't exist in Twilio account |
| **Already imported** | Phone number was previously imported for this provider |
| **Trunk attachment failed** | Twilio API error when attaching to trunk |
## After Import
Imported phone numbers can be:
* Listed via the phone numbers API
* Linked to agents for inbound call handling
* Used for outbound call caller ID
# List available phone numbers
Source: https://blackbox.dasha.ai/docs/api-reference/twilioprovider/list-available-phone-numbers
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/providers/twilio/{id}/available-numbers
Retrieves all phone numbers from the connected Twilio account.
Each number includes an imported flag indicating whether it has already been imported into the system.
Use this endpoint to discover numbers before importing them.
## Phone Number Discovery
This endpoint connects to your Twilio account and retrieves all incoming phone numbers.
## Response Fields
Each phone number includes:
| Field | Description |
| - | - |
| **sid** | Twilio Phone Number SID (used for import) |
| **phoneNumber** | E.164 formatted phone number |
| **friendlyName** | Human-readable name set in Twilio |
| **imported** | Whether the number has already been imported |
## Import Workflow
1. Call this endpoint to see available numbers
2. Note the `sid` values of numbers you want to import
3. Use the `/import-numbers` endpoint with those SIDs
## Already Imported Numbers
Numbers marked with `imported: true` are already in your system and linked to this provider. Attempting to import them again will result in a duplicate error.
# Remove phone number
Source: https://blackbox.dasha.ai/docs/api-reference/twilioprovider/remove-phone-number
https://blackbox.dasha.ai/swagger/v1/swagger.json delete /api/v1/providers/twilio/{id}/phone-numbers/{phoneNumberId}
Removes an imported phone number from the provider.
Detaches the phone number from the Twilio SIP trunk and deletes it from the system.
The phone number remains in your Twilio account and can be imported again later.
## Removal Process
When you remove a phone number from a provider:
1. The phone number is detached from the Twilio SIP trunk
2. Local records are deleted from the system
3. Any agent links are removed (if force=true)
## Force Removal
If the phone number is linked to agents or used in their outbound configuration:
* Without `force=true`: Returns 409 Conflict with affected agent details
* With `force=true`: Removes the phone number from all affected agents before deletion
## After Removal
The phone number:
* Remains in your Twilio account
* Can be imported again via the `/import-numbers` endpoint
* Will no longer route calls through this provider
## Impact on Calls
* **Inbound calls**: Will no longer be routed to agents
* **Outbound calls**: Agents using this number for caller ID will fail
# Update Auth Token
Source: https://blackbox.dasha.ai/docs/api-reference/twilioprovider/update-auth-token
https://blackbox.dasha.ai/swagger/v1/swagger.json patch /api/v1/providers/twilio/{id}/auth-token
Updates the Auth Token for an existing Twilio provider. The new token is validated with Twilio
before being saved to ensure it is correct. If validation fails, an error is returned and
no changes are made.
## Auth Token Update
This endpoint allows you to update the Auth Token for an existing Twilio provider without recreating the entire integration.
## Validation
Before saving, the new Auth Token is validated by calling the Twilio API with the existing Account SID and new Auth Token:
* If validation succeeds, the token is encrypted and saved
* If validation fails, an error is returned and no changes are made
## When to Use
Use this endpoint when:
* Your Twilio Auth Token has been rotated
* You need to update credentials without losing phone number configurations
* You want to verify new credentials before committing them
## Security
* The new Auth Token is encrypted before storage
* The old Auth Token is overwritten and cannot be recovered
* Auth Tokens are never exposed in API responses
# Update Twilio provider
Source: https://blackbox.dasha.ai/docs/api-reference/twilioprovider/update-twilio-provider
https://blackbox.dasha.ai/swagger/v1/swagger.json put /api/v1/providers/twilio/{id}
Updates an existing Twilio provider configuration. Only provided fields are updated.
Credentials (Account SID, Auth Token) cannot be updated through this endpoint for security reasons.
Create a new provider if you need to change credentials.
## Updatable Fields
The following fields can be updated:
| Field | Description |
| - | - |
| **name** | Display name for the provider |
| **region** | Twilio region for SIP trunk (us1, us2, ie1, de1, etc.) |
| **supportsCallTransfer** | Enable/disable call transfer support |
## Credential Updates
For security reasons, Account SID and Auth Token cannot be updated. If you need to change credentials:
1. Create a new provider with the new credentials
2. Import phone numbers to the new provider
3. Delete the old provider
## Partial Updates
This endpoint supports partial updates. Only include the fields you want to change in the request body.
# Clone voice from audio
Source: https://blackbox.dasha.ai/docs/api-reference/voice/clone-voice-from-audio
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/voice/clone
Creates a custom cloned voice from audio samples. The system analyzes the audio
characteristics and generates a synthetic voice that mimics the original speaker.
The cloned voice becomes available in your organization's voice library for use in agents.
## Audio Requirements
* **Format**: WAV, MP3, or FLAC
* **Quality**: Minimum 16kHz sample rate (44.1kHz recommended)
* **Duration**: 30 seconds to 10 minutes of clear speech
* **Content**: Clean speech without background noise or music
* **Speaker**: Single speaker with consistent tone
* **Total size**: Maximum 15MB combined
## Voice Cloning Process
1. **Audio analysis**: Extracts vocal characteristics and speech patterns
2. **Model training**: Creates custom voice model
3. **Quality validation**: Ensures voice meets quality standards
4. **Library storage**: Voice added to organization's library
## Use Cases
* Branded voices for customer service
* Personalized voice assistants
* Multilingual deployment with consistent identity
* Executive voice replication for announcements
# Delete cloned voice
Source: https://blackbox.dasha.ai/docs/api-reference/voice/delete-cloned-voice
https://blackbox.dasha.ai/swagger/v1/swagger.json delete /api/v1/voice/clone/{voiceId}
Permanently deletes a custom cloned voice from your organization's voice library.
The voice will become unavailable for use in agent configurations and synthesis requests.
> [!WARNING]
>
> This operation permanently deletes the cloned voice and cannot be undone.
## Impact
* Voice immediately unavailable for new synthesis
* Agents using this voice will need reconfiguration
* Storage quota freed for new voice creation
* Ongoing calls using this voice are not affected
# Get built-in sound audio
Source: https://blackbox.dasha.ai/docs/api-reference/voice/get-built-in-sound-audio
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/voice/builtin-media
Returns the audio of a built-in sound as MP3 so it can be previewed before it is used.
Accepts only the URIs listed by `GET /api/v1/misc/builtin-media` and
`GET /api/v1/misc/background-sounds`.
# List available voices
Source: https://blackbox.dasha.ai/docs/api-reference/voice/list-available-voices
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/voice
Retrieves all available Text-to-Speech (TTS) voices for your organization including
both public voices and custom cloned voices. Each voice includes metadata such as
language, gender, description, and audio preview URLs for agent configuration.
## Voice Categories
**Public Voices**:
* Pre-trained voices available to all users
* Wide variety of languages, accents, and characteristics
**Cloned Voices**:
* Custom voices created from audio samples
* Organization-specific and private
## Voice Selection
Consider these factors when selecting a voice:
* **Language**: Match your target audience's language
* **Characteristics**: Gender, age, accent, tone
* **Quality**: Audio clarity and naturalness
* **Performance**: Latency and real-time suitability
# Synthesize text to speech
Source: https://blackbox.dasha.ai/docs/api-reference/voice/synthesize-text-to-speech
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/voice/synthesize
Converts text to speech audio using the specified voice configuration. Returns MP3 audio
ready for playback or download. Useful for voice preview during agent configuration and
testing voice quality before deployment.
# Update cloned voice
Source: https://blackbox.dasha.ai/docs/api-reference/voice/update-cloned-voice
https://blackbox.dasha.ai/swagger/v1/swagger.json patch /api/v1/voice/clone/{voiceId}
Updates the metadata of an existing cloned voice without changing the underlying voice model.
Only provided fields are updated while others remain unchanged.
## Updatable Fields
* **Name**: Voice identifier for display
* **Description**: Voice characteristics and usage notes
* **Language**: Primary language setting
* **Labels**: Custom metadata tags
> [!NOTE]
>
> The actual voice model and audio characteristics cannot be changed. Only metadata can be updated.
# Test webhook endpoint
Source: https://blackbox.dasha.ai/docs/api-reference/webhooktest/test-webhook-endpoint
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/webhooks/test
Tests a webhook endpoint with realistic payload simulation. Sends a test payload to the webhook URL
and validates the response. Returns test results including HTTP status, response data, and execution time.
## Webhook Types
**Start Webhook**:
* Called when a call begins
* Can modify agent configuration dynamically
* Returns start webhook response with optional config overrides
**Tool Webhook**:
* Called when agent uses a custom tool
* Requires tool name and arguments
* Returns tool execution results
**Transfer Webhook**:
* Called before transferring a call
* Returns transfer destination information
**Result Webhooks** (Completed, Failed, Deadline):
* Fire-and-forget notifications
* No response data expected
## Test Response
The test returns:
* **Success**: Whether the webhook responded successfully
* **HTTP status**: Status code from webhook endpoint
* **Response data**: Parsed response from webhook
* **Validation result**: Schema validation for start webhooks
* **Time taken**: Execution time in milliseconds
* **Error**: Error message if test failed
# Create integration token
Source: https://blackbox.dasha.ai/docs/api-reference/webintegrations/create-integration-token
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/web-integrations/{integrationId}/tokens
Generates a new access token for the web integration. Tokens are used to authenticate
external systems accessing the integration.
# Create web integration
Source: https://blackbox.dasha.ai/docs/api-reference/webintegrations/create-web-integration
https://blackbox.dasha.ai/swagger/v1/swagger.json post /api/v1/web-integrations
Creates a new web integration for an agent with configured features and access tokens.
Web integrations allow external systems to interact with agents through APIs.
## Integration Features
Web integrations support various features:
* **Web calls**: Allow browser-based voice calls to agents
* **Phone calls**: Enable phone call initiation through the API
* **Origin restrictions**: Control which domains can access the integration
## Configuration Requirements
* **Web call feature**: Agents with cold transfer can accept browser calls; cold transfer attempts are declined without connecting anyone
* **Phone call feature**: Requires outbound SIP configuration on the agent
# Delete integration token
Source: https://blackbox.dasha.ai/docs/api-reference/webintegrations/delete-integration-token
https://blackbox.dasha.ai/swagger/v1/swagger.json delete /api/v1/web-integrations/{integrationId}/tokens/{tokenId}
Revokes and removes an access token from the web integration. External systems
using this token will immediately lose access.
# Delete web integration
Source: https://blackbox.dasha.ai/docs/api-reference/webintegrations/delete-web-integration
https://blackbox.dasha.ai/swagger/v1/swagger.json delete /api/v1/web-integrations/{integrationId}
Permanently deletes a web integration and revokes all associated access tokens.
> [!WARNING]
>
> This operation permanently deletes the web integration and revokes all associated tokens.
External systems using this integration will immediately lose access.
# Get web integration
Source: https://blackbox.dasha.ai/docs/api-reference/webintegrations/get-web-integration
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/web-integrations/integration
Retrieves a specific web integration by its identifier including
configuration settings and associated tokens.
# Get web integrations by agent
Source: https://blackbox.dasha.ai/docs/api-reference/webintegrations/get-web-integrations-by-agent
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/web-integrations/agent
Retrieves all web integrations associated with a specific agent.
# List web integrations
Source: https://blackbox.dasha.ai/docs/api-reference/webintegrations/list-web-integrations
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/web-integrations
Retrieves all web integrations configured for your organization including
configuration settings and associated tokens.
# Update web integration
Source: https://blackbox.dasha.ai/docs/api-reference/webintegrations/update-web-integration
https://blackbox.dasha.ai/swagger/v1/swagger.json put /api/v1/web-integrations
Updates an existing web integration configuration including features, origins, and settings.
# Validate integration token
Source: https://blackbox.dasha.ai/docs/api-reference/webintegrations/validate-integration-token
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/web-integrations/discover
Validates an access token and retrieves the associated integration configuration.
This is a public endpoint used by external systems to discover integration settings.
Validates both token validity and origin restrictions.
## Public Endpoint
This endpoint does not require API key authentication. It is designed for external systems
to validate their integration tokens and discover configuration.
## Validation Checks
* Token validity and expiration
* Origin restrictions (CORS)
* Integration status
# Get WebSocket endpoint information
Source: https://blackbox.dasha.ai/docs/api-reference/websocket/get-websocket-endpoint-information
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/ws/info
Returns information about available WebSocket endpoints and their current status.
# WebSocket endpoint for web calls
Source: https://blackbox.dasha.ai/docs/api-reference/websocket/websocket-endpoint-for-web-calls
https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/ws/webCall
Establishes a WebSocket connection for real-time web-based calls. This is not a traditional HTTP endpoint - it upgrades to WebSocket protocol.
## Connection Types
**Chat** (`chat`):
* Text-based conversations without voice
* No WebRTC required
* Lower bandwidth usage
* Use cases: customer support chat, FAQ bots
**Web Call** (`webCall`):
* Browser-based voice calls using WebRTC
* Real-time audio streaming
* Requires HTTPS and microphone access
* Use cases: voice customer support, interactive demos
**Phone Call** (`onPhone`):
* Traditional phone calls via SIP
* External phone number required
* Works with landlines/mobile devices
* Use cases: outbound campaigns, call centers
## Message Format
All messages use JSON structure:
```json
{
"type": "message_type",
"timestamp": "2024-01-01T00:00:00.000Z",
"data": {},
"content": {}
}
```
## Client → Server Messages
* **initialize**: Start new conversation with call type
* **incomingChatMessage**: Send text message
* **sdpAnswer**: Respond to WebRTC SDP offer
* **websocketToolResponse**: Return tool execution result
* **terminate**: End conversation
## Server → Client Messages
* **event**: System events (connection, opened, closed)
* **text**: Text messages from agent or user
* **sdpInvite**: WebRTC SDP offer for voice calls
* **toolCall**: Agent requesting tool execution
* **conversationResult**: Final conversation summary
* **error**: Error messages
## Connection Flow
1. **Establish connection** to WebSocket endpoint
2. **Send initialize** message with call type and configuration
3. **Receive connection event** when agent is ready
4. **Exchange messages** bidirectionally
5. **Send terminate** to end session gracefully
# Build a Complete Agent in 10 Minutes
Source: https://blackbox.dasha.ai/docs/create/creating-your-first-agent
Build a working AI voice agent in 10 minutes with the dashboard wizard or API. Step-by-step configuration of system prompt, LLM, voice, tools, and scheduling.
Ready to build something real? This guide walks you through every setting, so by the end you'll have a fully configured agent ready to take calls.
Don't worry if some of this feels new — we'll explain everything as we go.
> [!NOTE]
>
> **New to Dasha BlackBox?** If you haven't tried the [Quickstart](/docs/introduction/quickstart) yet, start there. It takes 5 minutes and gives you a feel for how things work.
## Before you start
You'll need:
* A Dasha BlackBox account — [sign up here](https://blackbox.dasha.ai) if you haven't already
* An idea of what you want your agent to do (support calls? appointment booking? lead qualification?)
* A rough draft of what you want it to say
## What we're setting up
Here's everything you can configure. Don't let the list intimidate you — only the first three are required:
| Setting | What it does | Required? |
| - | - | :-: |
| **Basic Info** | Name, language, personality | ✓ |
| **AI Model** | The brain that powers conversations | ✓ |
| **Voice** | How your agent sounds | ✓ |
| **Tools** | Actions your agent can take (check orders, book appointments) | |
| **Schedule** | When your agent is available | |
| **Features** | Extra capabilities like call transfers, knowledge bases | |
| **Webhooks** | Get notified when calls happen | |
| **Phone Setup** | Connect to real phone numbers | |
Let's go through each one.
***
## Step 1: Basic information
This is where you give your agent an identity.
**1. Open the agent builder**
Sign in at [blackbox.dasha.ai](https://blackbox.dasha.ai) and click **Create Agent**.
**2. Give it a name**
Pick something descriptive — "Customer Support Agent" or "Appointment Scheduler" works well. You'll thank yourself later when you have multiple agents.
**3. Choose a language**
Select your agent's main language. Don't worry, you can add more languages later if you need them.
**4. Write the system prompt**
This is the most important part. Your system prompt tells the agent who it is and how to behave.
Start simple — something like:
> "You are a friendly customer support agent for \[Your Company]. Help customers with their questions. Be concise and helpful. If you don't know something, say so."
You'll refine this based on test conversations, so don't overthink it now.
**5. Enable the agent**
Toggle **Allow this agent to take calls** to ON.
> [!TIP]
>
> The best prompts come from iteration. Start simple, test with real conversations, then add details based on what you learn.
***
## Step 2: Choose your AI model
The AI model is your agent's brain — it determines how smart and natural the conversations feel.
**1. Pick a provider**
We support OpenAI, Groq, DeepSeek, and others. OpenAI is a safe choice if you're not sure.
**2. Select a model**
For most use cases, GPT-4.1-mini hits the sweet spot between quality and speed. If you need maximum intelligence, try GPT-4.1. If speed is critical, Groq models are lightning fast.
**3. Set the temperature**
This controls how creative vs. predictable your agent is. Start with **0.7** — it's a good balance. Lower (0.3) for strict factual responses, higher (0.9) for more creative ones.
> [card] [Dive deeper into LLM settings](/docs/create/llm-configuration)
>
> Learn about all the model options and when to use each one
***
## Step 3: Pick a voice
This is where your agent gets its sound. It's worth spending a few minutes here — the right voice makes a big difference.
**1. Choose a provider**
**ElevenLabs** has the most natural-sounding voices. **Cartesia** is the fastest. Try a few and see what feels right for your brand.
**2. Browse voices**
Click **Preview** on any voice to hear a sample. Look for one that matches the personality you want — professional, friendly, calm, energetic.
**3. Adjust the speed**
Leave it at **1.0x** unless you have a reason to change it. Slightly faster (1.1x) can feel more energetic; slightly slower (0.9x) can feel more thoughtful.
> [card] [Explore all voice options](/docs/create/voice-and-speech)
>
> Compare providers, preview voices, and learn about voice cloning
***
## Step 4: Add tools (optional)
Tools let your agent *do* things, not just talk. Want it to check order status? Book appointments? Look up customer info? That's what tools are for.
**1. Add a tool**
Click **Add Tool** and give it a name like `check_order_status` or `book_appointment`.
**2. Describe what it does**
Write a clear description — this helps the AI know when to use it. Example: "Use this when the customer asks about their order status."
**3. Connect it to your system**
Enter the webhook URL that handles the actual work. When the agent decides to use this tool, we'll call your URL and pass along the details.
Don't have tools set up yet? That's fine — you can always add them later. Your agent will work without them; it just won't be able to take actions.
> [card] [Learn how tools work](/docs/create/tools-and-functions)
>
> Full guide to setting up tools, webhooks, and integrations
***
## Step 5: Set a schedule (optional)
By default, your agent is available 24/7. If you want it to follow business hours, set that up here.
**1. Set your timezone**
Pick your business timezone so the hours make sense.
**2. Configure your hours**
Toggle days on or off, and set the time range for each day.
What happens outside business hours? You can have the agent:
* Tell callers your hours and end the call
* Take a message
* Transfer to an after-hours number
> [card] [Scheduling options](/docs/create/scheduling-availability)
>
> Set up business hours, holidays, and after-hours handling
***
## Step 6: Enable features (optional)
These are extra capabilities you can turn on:
* **Fillers** — Add natural "um" and "uh" sounds while thinking
* **Call transfers** — Hand off to humans when needed
* **Knowledge base** — Give your agent documents to reference
* **Silence management** — Handle awkward pauses gracefully
Each feature has its own settings. Browse them and enable what makes sense for your use case.
> [card] [Explore all features](/docs/advanced-features/overview)
>
> Full list of available features and how to configure them
***
## Step 7: Set up webhooks (optional)
Webhooks notify your systems when things happen — a call starts, a call ends, the agent needs help.
**1. Add a start webhook**
Get notified when a call begins. Useful for logging or pulling up customer info.
**2. Add a result webhook**
Get the full transcript and outcome when a call ends. This is how most people integrate with their CRM.
> [card] [Webhook setup guide](/docs/webhooks-and-events/configuring-webhooks)
>
> Learn about webhook events, payloads, and security
***
## Step 8: Save and test
Almost there! Let's make sure everything works.
**1. Check for errors**
Look through each tab for any validation warnings. Fix anything that's flagged.
**2. Save your agent**
Click **Save Agent**. Your configuration is now live.
**3. Test it**
Click **Test** to start a conversation in your browser. Talk to it like a real customer would.
**4. Review the results**
After your test call, go to **Calls** to see the transcript and timing details. This is where you'll spot things to improve.
**Congratulations!** You've built a complete voice agent. From here, it's all about testing, learning, and refining.
***
## Building with the API?
If you prefer code, here's how to create an agent programmatically:
> [accordion] API example: Create an agent
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> 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: "Customer Support Agent",
> isEnabled: true,
> config: {
> primaryLanguage: "en-US",
> llmConfig: {
> vendor: "openai",
> model: "gpt-4.1-mini",
> prompt: "You are a helpful customer support agent...",
> options: { temperature: 0.7 }
> },
> ttsConfig: {
> vendor: "ElevenLabs",
> model: "eleven_flash_v2_5",
> voiceId: "21m00Tcm4TlvDq8ikWAM",
> speed: 1.0
> }
> }
> })
> });
>
> const agent = await response.json();
> console.log('Created agent:', agent.agentId);
> ```
***
## What's next?
> [card] [Test your agent](/docs/test/dashboard-testing)
>
> Learn testing strategies and how to debug issues
> [card] [Get a phone number](/docs/deploy/phone-numbers)
>
> Put your agent on a real phone line
> [card] [Add to your website](/docs/deploy/web-widget-embedding)
>
> Embed your agent as a web widget
> [card] [Go to production](/docs/deploy/production-checklist)
>
> Everything to check before going live
# Choose and Configure Language Models
Source: https://blackbox.dasha.ai/docs/create/llm-configuration
Choose and configure language models from Dasha Reflex-1, OpenAI, Groq, xAI Grok, DeepSeek, or custom providers for your AI voice agents.
Your agent's language model determines how it understands context, generates responses, and makes decisions. Dasha BlackBox supports multiple LLM providers, each with different strengths for voice conversations.
**What you'll learn:** Choosing a provider, configuring temperature, using custom endpoints, and optimizing for voice.
> [!NOTE]
>
> LLM latency typically accounts for 40–60% of total response time. We've measured this across millions of production calls — choosing the right provider and settings directly impacts conversation quality and caller satisfaction.
***
## Recommended providers
| Provider | Best for |
| - | - |
| **Reflex-1** | Low-latency voice conversations, native Dasha optimization |
| **OpenAI** | Production reliability, industry-leading quality |
**Reflex-1** is Dasha's in-house model, built specifically for real-time voice.
OpenAI remains our primary third-party provider, fully tested and optimized for Dasha BlackBox voice conversations.
> [!TIP]
>
> **Priority Tier**: Enable priority tier for OpenAI to reduce latency at the cost of higher LLM pricing. This is recommended for latency-sensitive production deployments where response speed directly impacts conversation quality.
## Alternative providers
The following providers are supported through OpenAI-compatible APIs. While functional, they have not been extensively tested on our platform. We recommend thorough testing before production use.
| Provider | Notes |
| - | - |
| **Groq** | High throughput with open-source models |
| **Grok (xAI)** | Advanced reasoning capabilities |
| **DeepSeek** | Cost efficiency with high quality |
> [!WARNING]
>
> Alternative providers may exhibit different latency characteristics, response formats, or edge-case behaviors compared to OpenAI. Test extensively with your specific use cases before deploying to production.
***
## Configuration
> [tab] Dashboard
>
> 1. Go to the **LLM Config** tab
> 2. Select your vendor from the dropdown
> 3. Choose a model
> 4. Configure temperature
> 5. Save your agent
> [tab] API
>
> > [accordion] API example: LLM configuration
> >
> > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> > llmConfig: {
> > vendor: "openai",
> > model: "gpt-4.1-mini",
> > prompt: "You are a helpful assistant...",
> > options: {
> > temperature: 0.7,
> > topP: 0.9
> > }
> > }
> > ```
***
## LLM parameters
All LLM vendors support standard configuration parameters that control response behavior.
### Temperature
Controls randomness and creativity in responses.
| Range | Behavior | Use when |
| - | - | - |
| **0.0–0.5** | Focused, deterministic, consistent | FAQs, factual information, structured workflows |
| **0.6–0.9** | Balanced creativity and consistency | General conversation, customer support |
| **1.0–2.0** | Creative, varied, unpredictable | Rarely used for voice agents |
**For production voice agents, use temperature between 0.6–0.8.** In our testing across thousands of calls, this range produces consistent yet natural-sounding responses. Lower values feel robotic; higher values risk hallucinations and off-topic tangents.
### Top P (nucleus sampling)
Alternative to temperature for controlling randomness via probability mass.
| Value | Effect |
| - | - |
| **0.9** | Only considers tokens in top 90% probability — more focused |
| **1.0** | Considers all tokens — standard behavior |
**OpenAI recommends using either temperature or topP, not both.** If you set both, temperature takes precedence.
***
## Enhanced tooling
**Enhanced tooling** makes tool calling more accurate: the agent calls a tool when it is needed and does not keep the caller waiting for the result. Tool calling runs on the platform's default model for it, or on an OpenAI model you pick.
> [!WARNING]
>
> Enhanced tooling uses more LLM calls per turn, so LLM usage cost is higher. Turn it on where tool accuracy matters more than LLM cost.
> [tab] Dashboard
>
> 1. Go to the **LLM Config** tab
> 2. Turn on **Enhanced tooling**
> 3. Optionally pick a **Tool calling model**; keep **Platform default** otherwise
> 4. Save your agent
> [tab] API
>
> > [accordion] API example: enhanced tooling
> >
> > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> > llmConfig: {
> > vendor: "dasha",
> > model: "reflex-2",
> > prompt: "You are a helpful assistant...",
> > enhancedTooling: {
> > isEnabled: true,
> > // Optional: pick the OpenAI model for tool calling. Omit it to use the platform default.
> > model: "gpt-5.6-luna"
> > }
> > }
> > ```
| Field | Type | Default | Description |
| - | - | - | - |
| `enhancedTooling.isEnabled` | boolean | false | Turns enhanced tooling on. When off, the agent behaves exactly as before. |
| `enhancedTooling.model` | string | platform default | OpenAI model used for tool calling. One of `gpt-6-luna`, `gpt-6-sol`, `gpt-5.6-luna`, `gpt-5.6-terra`, `gpt-4.1-mini`, `gpt-4.1`. Leave empty to use the platform's default model for tool calling. |
> [!NOTE]
>
> With enhanced tooling on, the slow marks on custom tools (`isLongRunning`, `longRunningAdditionalInstructions`) and MCP connections (`isLongRunning`, `longRunningTools`) are not used. With enhanced tooling off, they keep working as described in [Tools and Functions](/docs/create/tools-and-functions#slow-tools) and [MCP Connections](/docs/create/mcp-connections#slow-tools).
***
## Custom compatible provider
Use any OpenAI-compatible API endpoint, including self-hosted models or alternative providers.
### When to use custom providers
* Self-hosted models for data privacy
* Alternative providers with OpenAI-compatible APIs
* Custom fine-tuned models
* On-premise deployments
### Configuration
> [tab] Dashboard
>
> 1. Select **Custom Compatible** as your vendor
> 2. Enter the **Endpoint URL** (e.g., `https://api.yourprovider.com/v1`)
> 3. Enter your **API Key** (minimum 10 characters)
> 4. Enter the **Model ID** as recognized by your provider
> 5. Configure standard LLM parameters
> 6. Save your agent
> [tab] API
>
> > [accordion] API example: Custom provider configuration
> >
> > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> > llmConfig: {
> > vendor: "customCompatible",
> > model: "your-model-name",
> > endpoint: "https://api.yourprovider.com/v1",
> > apiKey: "your-provider-api-key",
> > prompt: "You are a custom AI assistant.",
> > options: {
> > temperature: 0.7
> > }
> > }
> > // Latency: Depends on your provider infrastructure
> > ```
> [!WARNING]
>
> Custom providers must implement the OpenAI Chat Completions API format. Incompatible APIs cause agent failures. Test thoroughly before production use.
***
## Testing and optimization
### A/B testing LLMs
Compare different vendors for your specific use case:
1. Create identical agents with different LLM configs
2. Run parallel test calls with the same scenarios
3. Measure response quality, speed, length, and success rate
4. Compare costs over 100–1000 calls
### Parameter tuning
**Temperature tuning:**
1. Start at 0.7 (balanced)
2. Test with real conversation scenarios
3. Adjust based on observations:
* Too robotic/repetitive → Increase to 0.8–0.9
* Too creative/inconsistent → Decrease to 0.5–0.6
* Hallucinating information → Decrease to 0.3–0.5
***
## Next steps
> [card] [Voice & Speech](/docs/create/voice-and-speech)
>
> Configure text-to-speech providers
> [card] [Tools & Functions](/docs/create/tools-and-functions)
>
> Enable agents to call external APIs
> [card] [Test Your Agent](/docs/test/dashboard-testing)
>
> Validate agent responses
> [card] [Production Checklist](/docs/deploy/production-checklist)
>
> Pre-deployment verification
# Connect to MCP Servers for Pre-Built Tools
Source: https://blackbox.dasha.ai/docs/create/mcp-connections
Connect Model Context Protocol servers to expand your agent's capabilities with pre-built tools and external data sources.
Connect your agent to MCP servers for pre-built tool integrations. Instead of writing custom webhooks, you plug into standardized servers that expose databases, calendars, CRMs, and other systems.
**What you'll learn:** How MCP works, configuring connections, authentication options, tool filtering, and when to use MCP vs custom webhooks.
> [!NOTE]
>
> Think of MCP as a "USB-C port for AI applications" — a universal way to connect AI agents to external systems.
## Overview
MCP standardizes how AI agents interact with external tools. Instead of building custom integrations for each system, MCP provides a unified interface.
**Key benefits:**
* One protocol for all tool integrations
* Automatic tool discovery from MCP servers
* Standardized authentication and error handling
* Growing ecosystem of pre-built MCP servers
***
> [accordion] How MCP works
>
> ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
> sequenceDiagram
> participant Agent as Your Agent
> participant Platform as Dasha BlackBox
> participant MCP as MCP Server
> participant External as External System
>
> Agent->>Platform: User requests data
> Platform->>MCP: Call tool via MCP
> MCP->>External: Execute operation
> External-->>MCP: Return result
> MCP-->>Platform: Return formatted data
> Platform-->>Agent: Present to user
> ```
1. **Connection setup:** Configure your agent to connect to an MCP server
2. **Tool discovery:** Platform automatically discovers available tools
3. **Runtime invocation:** Agent calls tools during conversations
4. **Secure execution:** MCP server executes operations with authentication
5. **Result integration:** Tool results are incorporated into responses
***
## Set up MCP connections
> [tab] Dashboard
>
> Navigate to the **MCP Connections** tab when creating or editing an agent.
>
> **1. Add new connection**
>
> Click **Add MCP Connection** to create a new connection.
>
> **2. Configure details**
>
> * **Name:** Descriptive identifier (e.g., "GitHub API", "Company Database")
> * **Server URL:** HTTP/HTTPS endpoint of your MCP server
> * **Description:** Optional notes about purpose
>
> **3. Set up authentication**
>
> Choose authentication method:
>
> * **No Authentication:** For public/internal servers
> * **API Key:** Include API key in custom header
> * **Bearer Token:** OAuth 2.0 or similar token-based auth
>
> **4. Select transport**
>
> * **SSE** (Server-Sent Events): For streaming connections (default)
> * **StreamableHTTP:** For HTTP-based request/response
>
> **5. Test connection**
>
> Click **Test Connection** to verify server is reachable and tools are discoverable.
>
> **6. Enable connection**
>
> Toggle the connection status to enable it. Only enabled connections are used at runtime.
> [tab] API
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> const agent = 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: "Customer Support Agent with CRM Access",
> config: {
> primaryLanguage: "en-US",
> llmConfig: {
> vendor: "openai",
> model: "gpt-4.1",
> prompt: "You are a customer support agent with CRM access..."
> },
> ttsConfig: {
> vendor: "ElevenLabs",
> voiceId: "zmcVlqmyk3Jpn5AVYcAL",
> model: "eleven_flash_v2_5"
> },
> mcpConnections: [
> {
> name: "Customer CRM",
> serverUrl: "https://mcp.example.com/crm",
> description: "Access to customer records",
> authentication: {
> type: "apiKey",
> headerName: "X-API-Key",
> apiKey: "YOUR_CRM_API_KEY"
> },
> transport: "StreamableHTTP",
> isEnabled: true,
> whiteListTools: [
> "get_customer_info",
> "get_order_history"
> ]
> }
> ]
> }
> })
> });
> ```
***
## Configuration reference
### Required fields
| Field | Type | Description |
| - | - | - |
| `name` | string | Unique identifier for this connection |
| `serverUrl` | string (URL) | HTTP/HTTPS endpoint of the MCP server |
### Optional fields
| Field | Type | Default | Description |
| - | - | - | - |
| `description` | string | null | Human-readable description |
| `authentication` | object | null | Authentication configuration |
| `customHeaders` | object | null | Additional HTTP headers |
| `isEnabled` | boolean | true | Whether connection is active |
| `transport` | enum | "SSE" | `"SSE"` or `"StreamableHTTP"` |
| `whiteListTools` | string\[] | null | Tools to include exclusively |
| `blackListTools` | string\[] | null | Tools to exclude |
| `isLongRunning` | boolean | false | Treat every tool of this connection as slow |
| `longRunningTools` | object\[] | null | Individual slow tools: `{ "name", "additionalInstructions" }` |
***
## Authentication types
> [accordion] No authentication
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "authentication": {
> "type": "none"
> }
> }
> ```
> [accordion] API key
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "authentication": {
> "type": "apiKey",
> "headerName": "X-API-Key",
> "apiKey": "your-api-key-here"
> }
> }
> ```
If `headerName` is omitted, the key is sent in the `Authorization` header as a raw value (no `Bearer` prefix). Common custom header names: `X-API-Key`, `X-Auth-Token`, `API-Key`
> [accordion] Bearer token
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "authentication": {
> "type": "bearer",
> "token": "your-bearer-token-here"
> }
> }
> ```
> [accordion] Custom headers
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "customHeaders": {
> "X-Organization-ID": "org-12345",
> "X-Environment": "production"
> }
> }
> ```
***
## Transport types
| Transport | Connection | Best for | Latency |
| - | - | - | - |
| **SSE** (default) | Persistent | Real-time tools, streaming data | Lower |
| **StreamableHTTP** | Per-request | REST APIs, batch operations | Higher |
**Choose SSE when:**
* Your MCP server supports SSE
* You need real-time tool responses
* Low latency is important
**Choose StreamableHTTP when:**
* Your MCP server doesn't support SSE
* You're integrating with REST-based implementations
* Tools are simple request/response operations
***
## Tool filtering
Control which MCP tools are available to your agent.
> [!NOTE]
>
> Tool whitelisting and blacklisting are currently available only through the API. The dashboard UI does not expose these options.
> [accordion] Whitelist tools
>
> Include ONLY specified tools:
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "whiteListTools": ["search", "calendar", "query_customers"]
> }
> ```
> [accordion] Blacklist tools
>
> Exclude specific tools:
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "blackListTools": ["admin_tool", "delete_customer", "export_database"]
> }
> ```
### Precedence rules
> [!WARNING]
>
> When both `whiteListTools` and `blackListTools` are specified, **whitelist takes precedence** and blacklist is ignored.
| Configuration | Result |
| - | - |
| Only whitelist | Only whitelisted tools available |
| Only blacklist | All tools except blacklisted |
| Both specified | Whitelist wins, blacklist ignored |
| Neither | All discovered tools available |
***
## Slow tools
By default the agent waits for an MCP tool to answer before it says anything, so a slow server leaves the caller listening to silence. Mark a tool as slow and it runs in the background instead: the agent gets an immediate acknowledgement, keeps the conversation going, and the result is added to the conversation history the moment the server answers.
> [accordion] Mark the whole connection as slow
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "isLongRunning": true
> }
> ```
> [accordion] Mark individual tools as slow
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "longRunningTools": [
> {
> "name": "search_orders",
> "additionalInstructions": "Tell the caller the order lookup usually takes about a minute."
> }
> ]
> }
> ```
**How it behaves during a call:**
1. The agent calls the tool and immediately receives a pending acknowledgement instead of the result, together with the `additionalInstructions` you configured.
2. The agent keeps talking to the caller — it can answer other questions or fill the wait.
3. When the server answers, the outcome is written into the conversation history as `Result of tool () = `, and the agent takes one extra speaking turn to tell the caller about it.
4. The result carries a short instruction with it: tell the caller the outcome in the next reply, casually and in passing if the conversation has moved on, and leave it unsaid only when it is no longer needed at all.
> [!NOTE]
>
> `additionalInstructions` is guidance for what the agent should say *while waiting*, not a description of the tool. Repeating the same call with the same arguments while one is still pending does not start a second request.
> [!WARNING]
>
> The result does not interrupt the agent mid-sentence. It is written into the conversation history and the agent takes one extra speaking turn as soon as it is free, so the caller hears the answer without having to ask again.
> [!NOTE]
>
> With [Enhanced tooling](/docs/create/llm-configuration#enhanced-tooling) enabled in the LLM configuration, `isLongRunning` and `longRunningTools` are not used.
***
## Test connections
> [accordion] Via API
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> const result = await fetch('https://blackbox.dasha.ai/api/v1/mcp/verify', {
> method: 'POST',
> headers: {
> 'Authorization': 'Bearer YOUR_API_KEY',
> 'Content-Type': 'application/json'
> },
> body: JSON.stringify({
> name: "Test Connection",
> serverUrl: "https://mcp.example.com/api",
> authentication: {
> type: "apiKey",
> headerName: "X-API-Key",
> apiKey: "test-key"
> },
> transport: "StreamableHTTP"
> })
> });
>
> const verification = await result.json();
> console.log('Connection status:', verification.success);
> // Output: true
>
> console.log('Tools found:', verification.availableTools.length);
> // Output: 5
> ```
> [accordion] Verification response
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "success": true,
> "message": "Connection successful",
> "availableTools": [
> {
> "name": "get_customer_info",
> "description": "Retrieve customer information by ID",
> "schema": { ... },
> "isEnabled": true
> }
> ],
> "responseTimeMs": 145.2
> }
> ```
***
## Common use cases
> [accordion] CRM integration
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "name": "Salesforce CRM",
> "serverUrl": "https://mcp.yourcompany.com/salesforce",
> "authentication": {
> "type": "bearer",
> "token": "YOUR_SALESFORCE_TOKEN"
> },
> "whiteListTools": [
> "get_customer_by_email",
> "get_open_cases",
> "create_case"
> ]
> }
> ```
> [accordion] Database access
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "name": "Analytics Database",
> "serverUrl": "https://mcp.yourcompany.com/postgres",
> "authentication": {
> "type": "apiKey",
> "headerName": "X-DB-Key",
> "apiKey": "YOUR_DB_API_KEY"
> },
> "whiteListTools": [
> "query_sales_data",
> "query_user_metrics"
> ]
> }
> ```
> [accordion] Knowledge base
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "name": "Knowledge Base",
> "serverUrl": "https://mcp.yourcompany.com/docs",
> "transport": "SSE",
> "authentication": {
> "type": "none"
> }
> }
> ```
***
## MCP vs custom webhooks
| Feature | MCP tools | Custom webhooks |
| - | - | - |
| Setup | Requires MCP server | Direct webhook endpoint |
| Tool discovery | Automatic | Manual configuration |
| Authentication | Standardized | Custom per endpoint |
| Best for | Multiple related tools | Single-purpose actions |
**Use MCP when:**
* Multiple related tools from same system
* Dynamic tool discovery needed
* Standardized authentication
**Use custom webhooks when:**
* Single-purpose tool/action
* Legacy systems without MCP support
* Custom execution logic required
***
## Best practices
### Security
* Use whitelisting to expose only necessary tools
* Avoid granting access to destructive operations
* Always use authentication for production servers
* Rotate API keys regularly
* Use HTTPS for all MCP server URLs
### Performance
* Aim for under 500ms tool response times
* Use caching on MCP server for frequent data
* Consider async operations for long-running tasks
### Reliability
* Return descriptive error messages
* Implement retries for transient failures
* Monitor tool invocation success rates
***
## Troubleshooting
> [accordion] Connection failures
>
> * Verify `serverUrl` is correct and accessible
> * Check authentication credentials
> * Ensure MCP server is running
> * Verify network connectivity (firewalls, proxies)
> [accordion] Authentication errors (401/403)
>
> * Verify authentication type matches server expectations
> * Check API key or token is not expired
> * Ensure `headerName` matches what server expects
> * Test authentication with curl or Postman
> [accordion] No tools discovered
>
> * Verify MCP server implements tool listing correctly
> * Check `whiteListTools` isn't too restrictive
> * Ensure tools aren't disabled on server side
> * Check for server-side errors
> [accordion] Tool invocation failures
>
> * Verify tool schemas match parameter requirements
> * Check external system is accessible
> * Monitor MCP server logs
> * Test tools independently outside conversation flow
***
## Next steps
> [card] [Tools & functions](/docs/create/tools-and-functions)
>
> Configure custom webhook-based tools
> [card] [Create Agent](/docs/create/creating-your-first-agent)
>
> Core agent configuration
> [card] [Dashboard testing](/docs/test/dashboard-testing)
>
> Test MCP tools in conversations
> [card] [Troubleshooting](/docs/troubleshooting/common-issues)
>
> Debug tool invocation issues
# Set Business Hours and Availability
Source: https://blackbox.dasha.ai/docs/create/scheduling-availability
Configure business hours, timezone settings, and availability rules to control when your agent handles calls.
Set when your agent accepts calls. Configure business hours, timezone, and how calls outside those hours are handled.
**Scheduling is optional.** If no schedule is configured, your agent is available 24/7 when enabled.
***
## Configure business hours
> [tab] Dashboard
>
> Navigate to the **Schedule** tab when creating or editing an agent.
>
> **1. Set timezone**
>
> Select your timezone from the dropdown (e.g., "America/New\_York", "Europe/London").
>
> **2. Configure daily hours**
>
> For each day (Monday–Sunday):
>
> 1. Toggle the day ON to enable it
> 2. Adjust **Start Time** and **End Time**
> 3. Click **+** to add additional time blocks (split shifts)
>
> **3. Save changes**
>
> Click **Save Agent** to apply your schedule.
> [tab] API
>
> > [accordion] API example: Schedule configuration
> >
> > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> > 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: "Customer Support Agent",
> > isEnabled: true,
> > config: { /* ... */ },
> > schedule: {
> > timezone: "America/New_York",
> > mon: [{ start: { hour: 9, minute: 0 }, end: { hour: 17, minute: 0 } }],
> > tue: [{ start: { hour: 9, minute: 0 }, end: { hour: 17, minute: 0 } }],
> > wed: [{ start: { hour: 9, minute: 0 }, end: { hour: 17, minute: 0 } }],
> > thu: [{ start: { hour: 9, minute: 0 }, end: { hour: 17, minute: 0 } }],
> > fri: [{ start: { hour: 9, minute: 0 }, end: { hour: 17, minute: 0 } }],
> > sat: [],
> > sun: []
> > }
> > })
> > });
> > ```
***
## Call routing behavior
### During business hours
* Agent accepts calls immediately
* Call proceeds normally
* Full conversation capabilities available
### Outside business hours
**Inbound calls:**
* Platform does not automatically reject based on schedule
* Use a start webhook to handle after-hours calls
* Alternative: Disable agent entirely during after-hours
**Scheduled outbound calls:**
* Calls are queued and wait for business hours
* Scheduler calculates next available time
* If deadline passes before working hours resume, call is canceled
### Queue behavior
| Situation | Result |
| - | - |
| Call scheduled outside hours | Queued until business hours resume |
| Deadline exceeded while queued | Call canceled |
| Multiple calls queued | Processed in priority order |
***
## What's next
> [card] [Create Your Agent](/docs/create/creating-your-first-agent)
>
> Configure agent with schedule
> [card] [Outbound Calls](/docs/deploy/outbound-calls)
>
> Schedule outbound calls with deadlines
> [card] [Webhooks](/docs/webhooks-and-events/webhooks-overview)
>
> Handle after-hours calls with webhooks
> [card] [Call History](/docs/monitor/call-history)
>
> Monitor call queue
# Add External API Integrations
Source: https://blackbox.dasha.ai/docs/create/tools-and-functions
Enable agents to call external APIs, query databases, and perform actions during conversations using function calling.
Give your agent the ability to take action. Tools let the LLM call external APIs, query databases, book appointments, and check order status — anything your webhook can handle.
**What you'll learn:** How to define tools with JSON Schema, configure webhooks, handle responses, and test tool execution.
***
## Quick start: Add a tool
**1. Navigate to Tools tab**
When creating or editing an agent, select the **Tools** tab.
**2. Add a new tool**
Click **Add Tool** to create a new tool configuration.
**3. Configure settings**
* **Tool Name**: Unique identifier (e.g., `get_weather`)
* **Description**: What the tool does and when to use it
* **Schema**: Define parameters using JSON Schema
* **Webhook URL**: Your endpoint
* **Headers**: Authentication and custom headers
**4. Test your tool**
Click **Test Tool**, enter sample arguments, and verify the response.
**5. Save and enable**
Save the agent and toggle **Allow this agent to take calls**.
> [accordion] How function calling works
>
> When you configure tools, the LLM gains awareness of available functions and autonomously decides when to call them during conversation. Dasha BlackBox sends requests to your webhook, your webhook executes the function, and the LLM incorporates results into its response.
>
> **Key capabilities:** JSON Schema for tool definitions, call metadata (callId, agentId, orgId) in webhook requests, automatic retry with exponential backoff, and built-in testing.
***
## Define a tool
> [accordion] Tool structure
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "name": "get_weather",
> "description": "Get current weather for a city",
> "schema": {
> "type": "object",
> "properties": {
> "city": {
> "type": "string",
> "description": "City name"
> },
> "units": {
> "type": "string",
> "enum": ["celsius", "fahrenheit"]
> }
> },
> "required": ["city"]
> },
> "webhook": {
> "url": "https://api.example.com/tools/weather",
> "headers": {
> "Authorization": "Bearer your-api-key"
> }
> },
> "fallBackResult": {
> "temperature": "unknown",
> "conditions": "unavailable"
> }
> }
> ```
### Required fields
| Field | Type | Description |
| - | - | - |
| `name` | string | Unique identifier. Pattern: `^[a-zA-Z_][a-zA-Z0-9_]*$`. No hyphens. |
| `description` | string | Clear explanation of what the tool does. Helps LLM decide when to use it. |
| `schema` | object | JSON Schema defining parameters. |
| `webhook` | object | URL and headers for the endpoint. |
### Optional fields
| Field | Type | Description |
| - | - | - |
| `fallBackResult` | any | Default result if webhook fails. Allows conversation to continue gracefully. |
| `timeoutSeconds` | integer | Max wait time (1–300). Note: Currently uses fixed 60s HTTP timeout. |
| `retryCount` | integer | Retry attempts (0–5). Uses global retry policy with exponential backoff. |
| `isLongRunning` | boolean | Run the tool in the background instead of making the agent wait for it. |
| `longRunningAdditionalInstructions` | string | What the agent should say while a slow call is still pending. |
***
## Slow tools
By default the agent waits for the webhook to answer before it says anything, so a slow endpoint leaves the caller listening to silence. Set `isLongRunning` and the call runs in the background instead: the agent gets an immediate acknowledgement, keeps the conversation going, and the result is added to the conversation history the moment the webhook answers.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"name": "check_order_status",
"isLongRunning": true,
"longRunningAdditionalInstructions": "Tell the caller the order lookup usually takes about a minute."
}
```
**How it behaves during a call:**
1. The agent calls the tool and immediately receives a pending acknowledgement instead of the result, together with your `longRunningAdditionalInstructions`.
2. The agent keeps talking to the caller — it can answer other questions or fill the wait.
3. When the webhook answers, the outcome is written into the conversation history as `Result of tool () = `, and the agent takes one extra speaking turn to tell the caller about it.
4. The result carries a short instruction with it: tell the caller the outcome in the next reply, casually and in passing if the conversation has moved on, and leave it unsaid only when it is no longer needed at all.
> [!NOTE]
>
> `longRunningAdditionalInstructions` is guidance for what the agent should say *while waiting*, not a description of the tool. Repeating the same call with the same arguments while one is still pending does not start a second request.
> [!WARNING]
>
> The result does not interrupt the agent mid-sentence. It is written into the conversation history and the agent takes one extra speaking turn as soon as it is free, so the caller hears the answer without having to ask again.
> [!NOTE]
>
> With [Enhanced tooling](/docs/create/llm-configuration#enhanced-tooling) enabled in the LLM configuration, `isLongRunning` and `longRunningAdditionalInstructions` are not used.
***
## JSON Schema examples
> [accordion] Simple parameters
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "name": "send_sms",
> "description": "Send an SMS message",
> "schema": {
> "type": "object",
> "properties": {
> "phone_number": {
> "type": "string",
> "pattern": "^\\+[1-9]\\d{1,14}$",
> "description": "Phone in E.164 format"
> },
> "message": {
> "type": "string",
> "maxLength": 160,
> "description": "Message content"
> }
> },
> "required": ["phone_number", "message"]
> }
> }
> ```
> [accordion] Nested objects
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "name": "book_appointment",
> "description": "Schedule an appointment",
> "schema": {
> "type": "object",
> "properties": {
> "customer": {
> "type": "object",
> "properties": {
> "name": { "type": "string" },
> "email": { "type": "string", "format": "email" },
> "phone": { "type": "string" }
> },
> "required": ["name", "email"]
> },
> "appointment": {
> "type": "object",
> "properties": {
> "datetime": { "type": "string", "format": "date-time" },
> "duration_minutes": { "type": "integer", "minimum": 15 },
> "service_type": {
> "type": "string",
> "enum": ["consultation", "follow-up", "emergency"]
> }
> },
> "required": ["datetime", "service_type"]
> }
> },
> "required": ["customer", "appointment"]
> }
> }
> ```
> [accordion] Arrays
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "name": "search_products",
> "description": "Search product catalog",
> "schema": {
> "type": "object",
> "properties": {
> "keywords": {
> "type": "array",
> "items": { "type": "string" },
> "minItems": 1
> },
> "categories": {
> "type": "array",
> "items": {
> "type": "string",
> "enum": ["electronics", "clothing", "home", "books"]
> }
> },
> "in_stock_only": {
> "type": "boolean",
> "default": true
> }
> },
> "required": ["keywords"]
> }
> }
> ```
> [accordion] Enumerations
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "name": "update_ticket_status",
> "description": "Update support ticket status",
> "schema": {
> "type": "object",
> "properties": {
> "ticket_id": {
> "type": "string",
> "pattern": "^TKT-[0-9]{6}$"
> },
> "status": {
> "type": "string",
> "enum": ["open", "in_progress", "waiting_customer", "resolved", "closed"]
> },
> "priority": {
> "type": "string",
> "enum": ["low", "medium", "high", "urgent"]
> }
> },
> "required": ["ticket_id", "status"]
> }
> }
> ```
***
## Configure webhooks
> [accordion] Request format
>
> When your tool is invoked, Dasha BlackBox sends a POST request:
>
> ```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
> POST https://api.example.com/webhooks/tools
> Content-Type: application/json
> Authorization: Bearer sk-abc123...
>
> {
> "type": "ToolWebHookPayload",
> "status": "Running",
> "callId": "67890abcdef123456789",
> "agentId": "12345abcdef67890",
> "orgId": "org_abc123xyz",
> "toolName": "get_weather",
> "arguments": {
> "city": "San Francisco",
> "units": "fahrenheit"
> },
> "callAdditionalData": {
> "campaign_id": "summer_outreach"
> },
> "agentAdditionalData": {
> "department": "sales"
> }
> }
> ```
> [!NOTE]
>
> Only headers configured in your tool definition are sent. The `callAdditionalData`, `agentAdditionalData`, `serverJobId`, and `sip` fields are optional.
> [accordion] Response format
>
> Return a JSON response within the timeout period:
>
> **Success (200 OK):**
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "temperature": 68,
> "conditions": "sunny",
> "humidity": 65
> }
> ```
> [accordion] Error Response (4xx/5xx)
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "error": "Invalid city name",
> "errorCode": "INVALID_CITY"
> }
> ```
If your webhook returns an error, the `fallBackResult` is used (if configured).
### Use call data in the URL and headers
The webhook URL and header values accept variables, so a tool can call a REST-style API with data you already have instead of asking the language model to repeat it:
| Field | Example |
| - | - |
| Webhook URL | `https://api.example.com/customers/{{callAdditionalData.customerId}}/orders` |
| Header value | `X-Call-Id: {{callId}}` |
| Query parameter | `status` = `{{arguments.status}}` |
Click **`{ }`** in a field to pick a variable: the tool's arguments, call fields such as `callId` and `endpoint`, SIP fields, and your own `callAdditionalData` and `agentAdditionalData` keys. Open **Advanced request settings** to change the HTTP method, add query parameters or build a custom request body.
> [!TIP]
>
> Identifiers such as customer or order IDs are more reliable from `callAdditionalData` than from a tool argument. The language model cannot mishear or invent them.
See [Request Templating](/docs/webhooks-and-events/webhook-request-templating) for every variable, the rendering rules and the API reference.
### Response best practices
* **Return structured data** with clear field names
* **Include context** for the LLM to formulate complete responses
* **Handle errors gracefully** — return error objects instead of crashing
* **Be concise** — avoid massive datasets, summarize when possible
* **Respond quickly** — aim for sub-second responses
***
## Test webhooks
### Via dashboard
1. Navigate to agent's Tools tab
2. Click **Test Tool** on the tool card or in the tool editor. Arguments are generated from the tool's schema.
3. If the webhook uses `callAdditionalData` or `agentAdditionalData` variables, test from the tool editor and fill in **Test values for custom data** first. Sample values are not saved.
4. Review the response and **Request Sent**, the exact URL, headers and body that were sent
> [accordion] Via API
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> const response = 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://api.example.com/webhooks/tools',
> headers: {
> 'Authorization': 'Bearer your-webhook-key'
> }
> },
> webhookType: 'ToolWebHookPayload',
> toolName: 'get_weather',
> toolArguments: {
> city: 'San Francisco',
> units: 'fahrenheit'
> }
> })
> });
>
> const result = await response.json();
> console.log(result);
> // Output:
> // {
> // "success": true,
> // "httpStatus": 200,
> // "httpStatusText": "OK",
> // "responseData": { "temperature": 68, "conditions": "sunny" },
> // "validationResult": { "isValid": true, "errors": [] },
> // "timeTaken": 145
> // }
> ```
***
## Tool webhooks vs event webhooks
| Feature | Tool webhooks | Event webhooks |
| - | - | - |
| **Purpose** | Execute functions during conversation | Receive call lifecycle notifications |
| **Trigger** | LLM decides to invoke a tool | Specific events (call start, result, failure) |
| **Response** | Returns result to LLM | Acknowledgment only |
| **Timeout** | 60 seconds | 30 seconds |
| **Configure in** | Tools tab | Webhooks tab |
See [Webhook Events](/docs/webhooks-and-events/webhook-events) for event webhook details.
***
## MCP tools
Dasha BlackBox integrates with Model Context Protocol (MCP) servers for pre-built tools without custom webhook development.
### MCP vs custom webhooks
| Feature | Custom webhooks | MCP servers |
| - | - | - |
| Setup | Write webhook handler | Connect to existing server |
| Tool discovery | Manual definition | Automatic from server |
| Hosting | Self-hosted or cloud | MCP server provider |
| Customization | Full control | Limited to server capabilities |
**Use custom webhooks** for full control or proprietary system integration.
**Use MCP connections** for standard integrations like databases, calendars, or public APIs.
See [MCP Connections](/docs/create/mcp-connections) for setup instructions.
***
## Common use cases
> [accordion] CRM integration
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "name": "lookup_customer",
> "description": "Retrieve customer information by email or phone",
> "schema": {
> "type": "object",
> "properties": {
> "identifier": {
> "type": "string",
> "description": "Customer email or phone number"
> }
> },
> "required": ["identifier"]
> },
> "webhook": {
> "url": "https://crm.example.com/api/webhooks/lookup",
> "headers": {
> "Authorization": "Bearer crm-api-key"
> }
> }
> }
> ```
> [accordion] Calendar booking
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "name": "check_availability",
> "description": "Check available appointment slots",
> "schema": {
> "type": "object",
> "properties": {
> "start_date": {
> "type": "string",
> "format": "date",
> "description": "Start date (YYYY-MM-DD)"
> },
> "end_date": {
> "type": "string",
> "format": "date",
> "description": "End date (YYYY-MM-DD)"
> },
> "service_type": {
> "type": "string",
> "description": "Type of service"
> }
> },
> "required": ["start_date", "end_date"]
> }
> }
> ```
> [accordion] Knowledge base search
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> "name": "search_knowledge_base",
> "description": "Search company knowledge base",
> "schema": {
> "type": "object",
> "properties": {
> "query": {
> "type": "string",
> "description": "Search query"
> },
> "category": {
> "type": "string",
> "enum": ["products", "policies", "troubleshooting"]
> },
> "max_results": {
> "type": "integer",
> "minimum": 1,
> "maximum": 10,
> "default": 5
> }
> },
> "required": ["query"]
> }
> }
> ```
***
## Best practices
### Tool design
* **Keep tools focused** — one tool, one purpose
* **Write clear descriptions** — explain when the LLM should use the tool
* **Use strong typing** — precise schemas with proper types, enums, formats
* **Provide defaults** — sensible fallback results for error handling
> [accordion] Schema guidelines
>
> ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> // ✅ Good: Descriptive with constraints
> {
> "customer_email": {
> "type": "string",
> "format": "email",
> "description": "Customer's email for order confirmation"
> }
> }
>
> // ❌ Avoid: Vague and unconstrained
> {
> "email": {
> "type": "string",
> "description": "Email"
> }
> }
> ```
### Webhook implementation
**Security:**
* Always use HTTPS endpoints
* Implement authentication via headers
* Validate incoming requests
* Rate limit to prevent abuse
**Performance:**
* Respond within timeout (aim for \< 1 second)
* Use async processing for slow operations
* Implement caching where appropriate
**Reliability:**
* Use idempotent operations when possible
* Monitor webhook uptime
* Set up alerting for failures
***
## Troubleshooting
> [accordion] Tool not being called
>
> * Improve the tool description to be more specific
> * Mention the tool in system prompt if critical
> * Test with explicit user requests that should trigger the tool
> * Check that the tool name is clear and descriptive
> [accordion] Webhook timeouts
>
> * Optimize webhook processing time
> * Use async processing and return immediately
> * Configure appropriate `fallBackResult`
> [accordion] Schema validation errors
>
> * Review LLM-generated arguments in call logs
> * Simplify complex nested schemas
> * Add clear descriptions to all properties
> * Use enums to constrain values
> [accordion] Authentication failures
>
> * Verify header configuration in tool setup
> * Check that API keys are valid and not expired
> * Ensure webhook URL is correct and accessible
> * Test webhook independently with curl/Postman
***
## Next steps
> [card] [MCP connections](/docs/create/mcp-connections)
>
> Connect to MCP servers for pre-built tools
> [card] [Webhook events](/docs/webhooks-and-events/webhook-events)
>
> Configure call lifecycle notifications
> [card] [Test webhooks](/docs/webhooks-and-events/testing-webhooks)
>
> Validate webhook implementations
> [card] [Dashboard testing](/docs/test/dashboard-testing)
>
> Test tools in real conversations
# TTS Providers Reference
Source: https://blackbox.dasha.ai/docs/create/tts-providers
Detailed configuration for ElevenLabs, Cartesia, and Inworld text-to-speech providers.
Detailed configuration for each TTS provider. For basic setup, see [Voice & Speech](/docs/create/voice-and-speech).
***
## ElevenLabs
Industry-leading voice quality with extensive customization. [Browse voices →](https://elevenlabs.io/app/voice-library)
**Models:**
* `eleven_v4` — Most emotionally rich and expressive speech, 90+ languages
* `eleven_v4_turbo` — Most expressive real-time model (\~100 ms), 90+ languages. Default for new ElevenLabs configurations
* `eleven_v3` — Human-like, expressive speech, 70+ languages
* `eleven_v3_conversational` — Expressive real-time model (\~280 ms), 70+ languages
* `eleven_multilingual_v2` — Previous generation, 29+ languages
* `eleven_turbo_v2_5` — Deprecated, not recommended for new projects
* `eleven_flash_v2_5` — Previous generation, fastest inference
**Pace:** V4 and V4 Turbo have no supported pace control, including on caller request. Numeric `speed` has no effect, and audio tags can change delivery, including whispering, instead of pace. Use untagged speech for routine calls. Other ElevenLabs models retain the 0.70x to 1.20x speed control.
BlackBox adds [voice-output guidance](/docs/create/voice-and-speech#expressive-speech-and-pace-tags) at call time. V4 guidance preserves whisper, expressive-delivery and vocal-sound tags, but does not offer tags as a pace control. V3 guidance is unchanged. Names, placeholders, markdown and emoji must not become spoken stage directions.
### Configuration options
| Option | Range | Default | Effect |
| - | - | - | - |
| `similarity_boost` | 0.0–1.0 | 0.75 | Voice consistency with original |
| `stability` | 0.0–1.0 | 0.5 | Output consistency across generations |
| `style` | 0.0–1.0 | 0.3 | Speaker style exaggeration |
| `use_speaker_boost` | boolean | true | Enhanced clarity |
| `optimize_streaming_latency` | 0–4 | Omitted | Legacy models only; rejected by V4 |
### Example
> [accordion] ElevenLabs configuration example
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> ttsConfig: {
> vendor: "ElevenLabs",
> voiceId: "21m00Tcm4TlvDq8ikWAM",
> model: "eleven_v4_turbo",
> speedAdjustment: { version: "v1", strategy: "Disabled" },
> vendorSpecificOptions: {
> similarity_boost: 0.8,
> stability: 0.6,
> style: 0.4,
> use_speaker_boost: true
> }
> }
> ```
***
## Cartesia
Granular emotion control with wide speed range. [Browse voices →](https://play.cartesia.ai/)
**Models:**
* `sonic-3.6` — Latest generation (recommended). Default for new Cartesia configurations
* `sonic-3.5` — Previous generation
**Speed range:** 0x to 2.0x (values below 0.25x sent as 0.25x)
### Emotion system
Combine emotions for nuanced delivery:
| Dimension | Intensities |
| - | - |
| anger | lowest, low, high, highest |
| positivity | lowest, low, high, highest |
| surprise | lowest, low, high, highest |
| sadness | lowest, low, high, highest |
| curiosity | lowest, low, high, highest |
> [!TIP]
>
> Start with subtle emotions (`low` levels). Combining too many high-intensity emotions sounds unnatural.
### Example
> [accordion] Cartesia configuration example
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> ttsConfig: {
> vendor: "Cartesia",
> voiceId: "cartesia-voice-id",
> model: "sonic-3.6",
> speed: 1.2,
> vendorSpecificOptions: {
> emotions: [
> "positivity:high",
> "curiosity:low"
> ]
> }
> }
> ```
***
## Inworld
Character-focused voices for gaming and interactive media. [Browse voices →](https://platform.inworld.ai/)
**Models:**
* `inworld-tts-2` — Latest generation, highest quality
* `inworld-tts-2-flash` — Lower-latency variant of TTS 2 (recommended). Default for new Inworld configurations
* `inworld-tts-1.5-max` — Deprecated, not recommended for new projects
* `inworld-tts-1.5-mini` — Deprecated, not recommended for new projects
* `inworld-tts-1` — Deprecated, not recommended for new projects
> [!WARNING]
>
> `inworld-tts-1` and `inworld-tts-1-max` are deprecated and not recommended for new projects. Both were discontinued on June 15, 2026, and Inworld routes requests for them to newer models automatically.
> [!TIP]
>
> With `inworld-tts-2` or `inworld-tts-2-flash`, agents automatically use [delivery tags](/docs/create/voice-delivery-tags) — square-bracket directions like `[say warmly]` or `[laugh]` — for emotion, pacing, and non-verbal sounds, and you can steer them from your agent prompt.
**Speed range:** 0.80x to 1.50x
### Configuration options
| Option | Default | Effect |
| - | - | - |
| `temperature` | 0.8 | Voice expressiveness |
| `pitch` | 0.0 | Pitch adjustment (+/-) |
### Example
> [accordion] Inworld configuration example
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> ttsConfig: {
> vendor: "Inworld",
> voiceId: "inworld-voice-id",
> model: "inworld-tts-2",
> speed: 1.0,
> vendorSpecificOptions: {
> temperature: 0.9,
> pitch: 0.2
> }
> }
> ```
***
## Advanced settings
### Responsiveness
Controls how quickly the agent begins speaking after the user finishes.
| Value | Behavior |
| - | - |
| **1.0** | Most responsive — minimal delay (recommended) |
| **0.7** | Slight delay added |
| **0.5** | Moderate delay |
| **0.0** | Maximum delay |
> [accordion] Responsiveness configuration example
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> ttsConfig: {
> responsiveness: 1.0
> }
> ```
### Interruption sensitivity
Controls how easily users can interrupt the agent while it is speaking. Lower values require more user speech before the agent stops; higher values make it easier to cut in.
| Value | Behavior |
| - | - |
| **1.0** | Easiest to interrupt — agent yields quickly (default) |
| **0.5** | Moderate — more user speech required before the agent stops |
| **0.0** | Non-interruptible — the agent is not interrupted by normal speech |
When left unset, the agent uses its default interruptible behavior (equivalent to `1.0`).
> [accordion] Interruption sensitivity configuration example
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> ttsConfig: {
> interruptionSensitivity: 1.0
> }
> ```
### Dynamic speed adjustment
For models that support numeric speed, allow agents to adapt speech pace when users request it ("Can you speak more slowly?"). This does not apply to V4 or V4 Turbo.
> [accordion] Speed adjustment configuration example
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> ttsConfig: {
> speed: 1.0,
> speedAdjustment: {
> version: "v1",
> strategy: "OnRequest" // or "Disabled"
> }
> }
> ```
| Strategy | Behavior |
| - | - |
| `OnRequest` | Agent adjusts speed when user requests (default) |
| `Disabled` | Speed remains fixed |
***
## Speed ranges by provider
| Provider | Min | Max | Default | Recommended |
| - | - | - | - | - |
| ElevenLabs | 0.70x | 1.20x | 1.0x | 0.9x–1.2x |
| Cartesia | 0x (sent as 0.25x) | 2.0x | 1.0x | 0.8x–1.3x |
| Inworld | 0.80x | 1.50x | 1.0x | 0.9x–1.1x |
***
## Provider decision guide
**Choose ElevenLabs if:**
* You need highest voice quality
* Brand-specific voice cloning is important
* Advanced customization is required
**Choose Cartesia if:**
* Emotional expression is important
* You need wide speed range (0x-2.0x)
**Choose Inworld if:**
* You're building character-driven experiences
* Gaming or interactive media is your use case
***
## Pronunciation dictionary
Customize how your agent pronounces brand names, acronyms, and technical terms.
### Provider support
| Provider | Alias rules | Phoneme rules |
| - | - | - |
| ElevenLabs | Yes | No |
| Cartesia | Yes | Yes |
| Inworld | No | No |
**Alias rules** replace one word with another spelling. **Phoneme rules** specify exact pronunciation using IPA notation.
### Create a dictionary
> [accordion] API example: Create pronunciation dictionary
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> const response = await fetch('https://blackbox.dasha.ai/api/v1/pronunciation-dictionaries', {
> method: 'POST',
> headers: {
> 'Authorization': 'Bearer YOUR_API_KEY',
> 'Content-Type': 'application/json'
> },
> body: JSON.stringify({
> name: "Company Terms",
> provider: "Cartesia",
> rules: [
> {
> type: "alias",
> stringToReplace: "API",
> replacement: "A P I"
> },
> {
> type: "alias",
> stringToReplace: "SQL",
> replacement: "sequel"
> },
> {
> type: "phoneme",
> stringToReplace: "Dasha",
> phoneme: "ˈdɑːʃə",
> alphabet: "ipa"
> }
> ]
> })
> });
>
> const dictionary = await response.json();
> console.log('Dictionary ID:', dictionary.id);
> // Output: pd_abc123def456
> ```
### Reference in agent config
> [accordion] Pronunciation dictionary reference example
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> ttsConfig: {
> vendor: "Cartesia",
> voiceId: "your-voice-id",
> pronunciationDictionary: {
> id: "pd_abc123def456",
> hash: "a1b2c3d4e5f6"
> }
> }
> ```
> [!TIP]
>
> Create a single, comprehensive dictionary for your organization and reference it across all agents.
***
## Multilingual configuration
For agents that switch languages mid-conversation:
> [accordion] Multilingual configuration example
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> config: {
> primaryLanguage: "en-US",
> ttsConfig: {
> version: "v1",
> vendor: "ElevenLabs",
> voiceId: "multilingual-voice-id",
> model: "eleven_multilingual_v2",
> speed: 1.0
> },
> features: {
> languageSwitching: {
> isEnabled: true
> }
> }
> }
> ```
***
## Related
> [card] [Voice & Speech](/docs/create/voice-and-speech)
>
> Basic voice configuration
> [card] [Dashboard Testing](/docs/test/dashboard-testing)
>
> Test voice quality in the browser
# Configure Voice and Speech
Source: https://blackbox.dasha.ai/docs/create/voice-and-speech
Configure how your agent sounds. Choose a TTS provider, select a voice, and adjust speed settings.
Configure how your agent sounds. Choose a TTS provider, select a voice, and adjust speed.
**What you'll learn:** Provider selection, voice configuration, speed settings, and troubleshooting.
**Prerequisites:** An agent created in Dasha BlackBox. See [Create Your First Agent](/docs/create/creating-your-first-agent) if you haven't set one up yet.
> [!NOTE]
>
> **Default voice:** New English agents use ElevenLabs V4 Turbo. Existing agents keep their selected model, and Russian defaults are unchanged. Change the voice model in the agent editor.
## Overview
| Component | What it does | Configuration |
| - | - | - |
| **Text-to-Speech (TTS)** | Converts agent responses to speech | Manual — choose provider, voice, speed |
| **Speech-to-Text (STT)** | Transcribes user speech to text | Automatic — platform selects optimal provider |
***
## Provider comparison
| Provider | Best for | Speed range |
| - | - | - |
| **ElevenLabs** | Natural quality, expressive audio tags | V4 has no supported pace control; other models use numeric speed |
| **Cartesia** | Emotions, wide speed range | 0x–2.0x |
| **Inworld** | Character voices, gaming | 0.80x–1.50x |
For detailed provider configuration, see [TTS Providers Reference](/docs/create/tts-providers).
***
## Configure voice
**1. Open Voice & Speech tab**
Navigate to agent creation or editing, then select the Voice & Speech tab.
**2. Choose provider**
Select your TTS provider from the dropdown.
**3. Select voice**
Browse by name, language, or gender. Click preview to hear samples.
**4. Adjust speed**
V4 has no supported pace control, including when a caller asks to slow down. Numeric speed is ignored, and audio tags can change delivery instead of pace. Use untagged speech for routine calls. For models with numeric speed, set it within provider limits.
**5. Save**
Save your agent configuration.
***
## Expressive speech and pace tags
On V4 voice calls (`eleven_v4` and `eleven_v4_turbo`), BlackBox adds voice-output guidance for `[whispers]`, `[excited]` and `[sad]`, plus the vocal sounds `[laughs]`, `[sighs]` and `[clears throat]`. Requested demonstrations stay brief and focused. Neutral speech needs no tag. Write actual names in ordinary text, never as bracketed placeholders or stage directions.
For a requested whisper, repeat the delivery tag before each sentence of the requested content because sentences are synthesized separately. Sound tags perform one sound and do not carry into later sentences. V3 agents retain their existing voice-output guidance. These runtime instructions do not edit saved agent prompts or apply to text chat.
V4 has no supported pace control, including when a caller asks to slow down. Numeric `speed` is ignored, and delivery tags can whisper or change expression instead of controlling pace. The agent should explain this limitation rather than promise a pace change. The editor states the limitation, and the speed-adjustment tool is disabled during V4 calls. V4 also rejects `optimize_streaming_latency`; omit that option.
## Numeric speed settings
These settings apply to models that support numeric speed.
| Speed | Use case |
| - | - |
| **0.7x–0.9x** | Accessibility, complex information, legal disclosures |
| **1.0x** | General conversation, customer support |
| **1.1x–1.5x** | Time-sensitive scenarios, experienced users |
> [!WARNING]
>
> Avoid speeds below 0.7x or above 1.5x — they sound unnatural.
***
## Basic configuration
> [accordion] API example: TTS configuration
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> ttsConfig: {
> version: "v1",
> vendor: "ElevenLabs",
> voiceId: "zmcVlqmyk3Jpn5AVYcAL",
> model: "eleven_v4_turbo",
> speedAdjustment: { version: "v1", strategy: "Disabled" }
> }
> ```
***
## Troubleshooting
| Issue | Solution |
| - | - |
| Voice sounds robotic | Try different voice or switch to ElevenLabs |
| Speech too fast/slow | V4 has no supported pace control; adjust numeric speed on other models |
| Pronunciation errors | Configure pronunciation dictionary via API |
***
## Next steps
> [card] [TTS providers](/docs/create/tts-providers)
>
> Detailed provider configuration
> [card] [Dashboard Testing](/docs/test/dashboard-testing)
>
> Test voice quality in the browser
# Voice Delivery Tags
Source: https://blackbox.dasha.ai/docs/create/voice-delivery-tags
Control emotion, pacing, and non-verbal sounds in agent speech with inworld-tts-2 and inworld-tts-2-flash instruction tags.
When an agent uses Inworld with the `inworld-tts-2` or `inworld-tts-2-flash` model, its replies can carry **delivery tags** — natural-language directions in square brackets that the voice acts out:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
[sound concerned] I understand, that sounds really painful. [say warmly] Let me get you booked in today.
```
The platform handles the mechanics automatically. On every voice call with `inworld-tts-2` or `inworld-tts-2-flash`, the agent is taught how tags work, when a human would use them, and how to keep them in English regardless of the conversation language. You do not need to explain tags in your agent prompt — you only steer them.
> [!NOTE]
>
> This page describes Inworld tags. ElevenLabs v3 and v4 models also receive automatic [voice-output guidance](/docs/create/voice-and-speech#expressive-speech-and-pace-tags), with different tag examples such as `[laughs]` and `[sighs]`. Automatic tag guidance is not added to text chats.
***
## What the platform does for you
With `inworld-tts-2` or `inworld-tts-2-flash` selected, every voice conversation automatically gets:
* **Tag mechanics** — the agent knows the tag syntax, keeps tags in English even when speaking another language, and repeats tags on consecutive sentences (each sentence is synthesized separately, so an untagged sentence falls back to neutral delivery).
* **Human-like defaults** — warm greetings and farewells, a light playful touch when the caller jokes, an apologetic and measured delivery with irritated or busy callers, and clear articulation when confirming times, addresses, and numbers. Plain informational sentences stay untagged.
* **Speech-friendly writing** — numbers, dates, times, and phone numbers are written out in words, punctuation stays conversational, and markdown or special symbols are kept out of spoken text.
If that default behavior fits your use case, you are done — no prompt changes needed.
***
## Steering delivery from your agent prompt
There are three levels of control, from loose to exact. All of them work in any prompt language — the emitted tags stay in English.
### 1. Describe the voice
Add a short natural-language description of how your agent should sound. The agent maps it to tag moods on its own:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
VOICE
Warm and very friendly, with a light playful touch, but never overfamiliar.
When the caller jokes, it is fine to answer playfully with a soft laugh.
With an irritated or busy caller the playfulness switches off completely —
speak gently, apologetically, at a measured pace. Pronounce times, addresses,
and other key details clearly and warmly.
```
A persona described this way measurably changes which tags the agent picks — for example, playful tags appear on jokes only when the description allows playfulness, and never leak into conversations with irritated callers.
### 2. Map situations to tags
For precise control, write a policy in `situation → tag` form and include the tag literally. The agent uses your exact tag at the right moment:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
TAG POLICY
Greeting and discount pitch → [say warmly with a smile and a light playful tone]
Caller is irritated, busy, or asks where you got their number → [sound apologetic with a soft tone and measured pace]
Confirming a booking, time, or address → [articulate clearly with a warm tone]
Farewell after a refusal → [say warmly, without playfulness]
```
### 3. Script exact moments
Flow rules can trigger a specific delivery at a specific moment. Write the tag inline in the rule:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
SPECIAL SITUATIONS
If asked whether you are a robot — start the reply with [laugh] and say of course not.
If the caller says they already bought elsewhere — start the reply with [sigh] [sound sad], thank them, and wish them a good day.
```
A literal tag written in a rule passes through verbatim, every time. A loose stage direction ("laugh it off and deny it") also works, but only for the action itself: the agent will reliably emit `[laugh]`, while the surrounding delivery drifts toward the agent's persona. When the exact mood matters, write the delivery tag too — for example `[laugh] [say playfully]`.
Non-verbal tags are fixed sound effects: use them exactly as listed — `[laugh]`, `[sigh]`, `[breathe]` — without modifiers. A modified non-verbal like `[laugh sinisterly]` is not recognized. To color the moment, pair the bare non-verbal with a separate delivery tag for the sentence.
***
## Tag reference
Tags are free-form natural language, not a fixed list. These categories are good building blocks:
| Category | Examples |
| - | - |
| Emotion | `[say excitedly]`, `[sound sad]`, `[sound concerned]` |
| Articulation | `[say with force]`, `[articulate clearly]`, `[say with deliberate pauses]` |
| Intonation | `[say with a falling pitch]`, `[say with a rising pitch]` |
| Volume | `[very quiet]`, `[very loud]` |
| Pitch | `[say in a low tone]`, `[say in a high pitch]` |
| Range | `[say playfully]`, `[say with no pitch variation]` |
| Speed | `[very fast]`, `[very slow]` |
| Vocal style | `[whisper in a hushed style]`, `[give a nasal quality]` |
| Non-verbals | `[laugh]`, `[sigh]`, `[clear throat]`, `[breathe]`, `[cough]` |
Combining qualities in one instruction produces a more convincing performance than a bare tag: `[say sadly with deliberate pauses in a low voice]` layers mood, rhythm, and pitch.
> [!WARNING]
>
> Write non-verbal tags with spaces and without modifiers, exactly as documented — `[clear throat]`, not `[clear_throat]` or `[laugh sinisterly]`. Do not combine opposing directions in one tag (`[whisper in a hushed style]` together with `[very loud]`), and do not apply a tag that contradicts the text it introduces.
***
## Emphasis and stress
To stress a single word, capitalize it — the voice emphasizes capitalized words:
```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
It comes with the FULL warranty, no extra cost.
```
Use this sparingly, on whole words only. Inworld does not document accent-mark stress (for example, combining diacritics on Russian words), so verify such conventions on your actual voice before relying on them.
***
## Configuration
Delivery tags require no extra configuration beyond selecting the model:
> [accordion] Inworld TTS-2 configuration example
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> ttsConfig: {
> vendor: "Inworld",
> voiceId: "inworld-voice-id",
> model: "inworld-tts-2",
> speed: 1.0
> }
> ```
***
## Related
> [card] [TTS Providers](/docs/create/tts-providers)
>
> Full Inworld configuration reference
> [card] [Voice & Speech](/docs/create/voice-and-speech)
>
> Basic voice configuration
# Caller ID Configuration
Source: https://blackbox.dasha.ai/docs/deploy/caller-id
Configure caller ID for outbound calls. Set display names, follow compliance requirements, and improve answer rates.
Configure caller ID to control what recipients see when your agent calls. Proper caller ID improves answer rates and builds trust.
**What you'll learn:** Caller ID setup, display name configuration, compliance requirements, and answer rate optimization.
**Prerequisites:** [SIP trunk configured](/docs/deploy/sip-configuration) for outbound calls.
## Caller ID basics
Caller ID consists of two components:
| Component | Field | Example | Carrier support |
| - | - | - | - |
| **Phone number** | `fromUser` | `+14155551234` | Universal |
| **Display name** | `displayName` | `Acme Support` | Varies by carrier |
> [!NOTE]
>
> Display name support depends on the recipient's carrier. Some carriers show only the phone number regardless of your settings.
***
## Configure caller ID
### Via dashboard
1. Go to **Agents** → Select agent → **Edit**
2. Navigate to **Phone & SIP** tab
3. Set **From User** to your verified phone number (E.164 format)
4. Set **Display Name** to your business name
5. Click **Save Agent**
### Via API
> [accordion] API example: Configure caller ID
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> await fetch(`https://blackbox.dasha.ai/api/v1/agents/${agentId}`, {
> method: 'PUT',
> headers: {
> 'Authorization': 'Bearer YOUR_API_KEY',
> 'Content-Type': 'application/json'
> },
> body: JSON.stringify({
> config: {
> outboundSipConfig: {
> fromUser: "+14155551234",
> displayName: "Acme Support"
> }
> }
> })
> });
> ```
***
## Best practices
### Do
* **Use verified numbers** — Only use phone numbers you own or have explicit permission to use
* **Match local area codes** — Use numbers with area codes matching your recipients for higher answer rates
* **Set recognizable names** — Use your actual business name, not generic text
* **Register with CNAM** — Register your number with CNAM providers for caller name display
* **Be consistent** — Use the same caller ID across campaigns to build recognition
### Avoid
* **Spoofing numbers** — Using numbers you don't own is illegal in most jurisdictions
* **Frequent changes** — Changing caller ID often triggers spam filters
* **Blocked/private ID** — Hidden caller ID reduces answer rates significantly
* **Generic names** — Avoid "Unknown", "Wireless Caller", or blank display names
> [!WARNING]
>
> **Caller ID spoofing is illegal.** Using phone numbers you don't own or have permission to use can result in fines up to \$10,000 per violation (US) and service termination. Always use numbers registered to your business.
***
## Phone number types for caller ID
### Local numbers
Geographic numbers with specific area codes:
* **Example**: `+1 (415) 555-0123` (San Francisco)
* **Best for**: Regional businesses, local presence
* **Benefit**: 30-50% higher answer rates than toll-free
### Toll-free numbers
Free for recipients to call back:
* **US prefixes**: 800, 888, 877, 866, 855, 844, 833
* **Best for**: Customer support, national campaigns
* **Note**: Lower answer rates for outbound — often perceived as telemarketing
### International numbers
Numbers from specific countries:
* **Best for**: Global operations, country-specific campaigns
* **Consideration**: Use local numbers for each target country when possible
***
## CNAM registration
CNAM (Caller Name) databases store the business name associated with phone numbers.
### Register your number
1. Contact your SIP provider about CNAM registration
2. Provide your business name and phone number
3. Registration propagates within 24-72 hours
4. Verify by calling a landline (mobile support varies)
### CNAM limitations
* Mobile carriers may not display CNAM data
* Some carriers override with their own databases
* International CNAM support is limited
* Changes take 24-72 hours to propagate
***
## Answer rate optimization
### Strategies that work
| Strategy | Impact | Notes |
| - | - | - |
| Local area codes | +30-50% | Match recipient's location |
| Consistent caller ID | +15-25% | Build recognition over time |
| CNAM registration | +10-20% | Shows business name |
| Business hours calling | +20-30% | 9am-6pm local time |
| Verified/trusted status | +15-25% | Register with carriers |
### Avoid spam flags
* Don't exceed 50 calls/day from a single number
* Rotate multiple numbers for high-volume campaigns
* Monitor answer rates — sudden drops may indicate spam flagging
* Register with carrier spam verification services (STIR/SHAKEN)
***
## Compliance requirements
### US regulations
* **TCPA**: Consent required for automated calls to mobile phones
* **FCC**: Caller ID must accurately reflect your identity
* **Do Not Call**: Honor opt-outs and DNC registry
### STIR/SHAKEN
STIR/SHAKEN is a framework that verifies caller ID authenticity:
* **Attestation A**: You own the number and have rights to use it
* **Attestation B**: You're authorized to use the number
* **Attestation C**: Call originated from your network (lowest trust)
> [!TIP]
>
> Work with your SIP provider to ensure STIR/SHAKEN attestation. Higher attestation levels mean better deliverability and lower spam flagging.
***
## Troubleshooting
> [accordion] Wrong caller ID displayed
>
> **Causes**: Incorrect fromUser, carrier override, CNAM not registered
>
> **Solutions**:
>
> 1. Verify `fromUser` exactly matches your assigned number (E.164 format)
> 2. Check displayName is set correctly
> 3. Wait 24-72 hours for CNAM propagation
> 4. Contact provider about caller ID passthrough settings
> [accordion] Calls marked as spam
>
> **Causes**: High call volume, no STIR/SHAKEN, recipient complaints
>
> **Solutions**:
>
> 1. Reduce call volume from single numbers
> 2. Verify STIR/SHAKEN attestation with provider
> 3. Register with carrier spam verification services
> 4. Vary calling times and patterns
> 5. Ensure proper consent for all recipients
> [accordion] Low answer rates
>
> **Causes**: Unfamiliar caller ID, wrong timing, spam flagging
>
> **Solutions**:
>
> 1. Use local area codes matching recipients
> 2. Call during business hours (9am-6pm local)
> 3. Register CNAM for business name display
> 4. Check spam/blocking status with free lookup services
> 5. Rotate numbers if consistently flagged
> [accordion] Display name not showing
>
> **Causes**: Carrier doesn't support CNAM, not registered, mobile recipient
>
> **Solutions**:
>
> 1. Register with CNAM provider through your SIP trunk
> 2. Note that mobile carriers often don't display CNAM
> 3. Verify registration by calling a landline
> 4. Check with provider about CNAM passthrough
***
## Next steps
> [card] [Outbound Calls](/docs/deploy/outbound-calls)
>
> Schedule outbound campaigns
> [card] [Phone Numbers](/docs/deploy/phone-numbers)
>
> Phone number types overview
> [card] [Production Checklist](/docs/deploy/production-checklist)
>
> Pre-launch verification
# Deploy Voice Agents for Production
Source: https://blackbox.dasha.ai/docs/deploy/deployment-overview
Deploy voice agents for phone calls. Configure SIP trunks and production settings.
Get your agent live. Choose your deployment channel and follow the quick start guide.
**What you'll learn:** Available deployment channels and how to set up each one.
## Deployment channels
| Channel | Use case | Guide |
| - | - | - |
| **Inbound phone** | Receive calls via SIP trunk | [Inbound Calls](/docs/deploy/inbound-calls) |
| **Outbound phone** | Make calls via API | [Outbound Calls](/docs/deploy/outbound-calls) |
| **Web integration** | Embed voice/chat in your website | [Web Widget](/docs/deploy/web-widget-embedding) |
> [!NOTE]
>
> Test agents thoroughly before deployment. Enabled agents receive live traffic immediately.
***
## Quick start: Inbound calls
Receive calls on a phone number routed to your agent.
**1. Get SIP credentials**
Obtain credentials from your SIP provider (Bandwidth, Telnyx, etc.)
**2. Configure inbound**
Dashboard → **Connections** → **Telephony** → Add trunk
**3. Link agent**
Route incoming calls to your agent's SIP URI
**4. Test**
Call the number, verify agent answers
> [card] [Inbound Calls](/docs/deploy/inbound-calls)
>
> Complete guide with provider-specific setup
***
## Quick start: Outbound calls
Make calls from your agent via API.
**1. Configure SIP trunk**
Set up outbound credentials (server, auth, caller ID)
**2. Schedule call**
Use the API to schedule calls with priority and deadline
**3. Monitor**
Check status via API or dashboard
> [card] [Outbound Calls](/docs/deploy/outbound-calls)
>
> Complete guide with bulk scheduling and campaigns
***
## Quick start: Web integration
Embed voice or chat agents in your website.
**1. Create web integration**
Dashboard → **Connections** → **Web Integrations** → Create integration
**2. Configure settings**
Set allowed origins, features (voice/chat), and widget appearance
**3. Embed widget**
Add the generated script tag to your website
**4. Test**
Visit your site, verify widget appears and connects
> [card] [Web Widget Embedding](/docs/deploy/web-widget-embedding)
>
> Complete guide with customization options
***
## Pre-deployment checklist
Before going live, verify your configuration:
> [card] [Production Checklist](/docs/deploy/production-checklist)
>
> Complete pre-launch verification guide
***
## What's next
> [card] [Phone Numbers](/docs/deploy/phone-numbers)
>
> Configure SIP settings and caller ID
> [card] [Web Widget](/docs/deploy/web-widget-embedding)
>
> Embed agents in your website
> [card] [Production Checklist](/docs/deploy/production-checklist)
>
> Pre-launch verification
# Receive Inbound Calls on Your Agent
Source: https://blackbox.dasha.ai/docs/deploy/inbound-calls
Route phone calls to your AI agent. Link phone numbers for automatic call routing and handle business hours.
Route incoming phone calls to your agent. Link a phone number to an agent, and calls to that number automatically connect to the agent.
**What you'll learn:** How to link phone numbers for inbound routing and test incoming calls.
***
## How inbound calls work
When a phone number is linked to an agent:
1. Caller dials the phone number
2. Call routes through your SIP provider
3. Agent answers and starts the conversation
***
## Link a phone number for inbound calls
> [tab] Dashboard
>
> 1. Navigate to **Phone Numbers**
> 2. Click on the phone number you want to use
> 3. Select an agent from the **Inbound Agent** dropdown
> 4. Click **Save**
> [tab] API
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> // Link phone number to agent for inbound calls
> await fetch(
> `https://blackbox.dasha.ai/api/v1/sip-phone-numbers/${phoneNumberId}/agent-link?agentId=${agentId}&mode=inbound`,
> {
> method: 'PUT',
> headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
> }
> );
> ```
> [!NOTE]
>
> Each phone number can only be linked to one agent for inbound calls. Linking to a new agent automatically unlinks from the previous one.
***
## Route a whole SIP domain to an agent
If you run your own PBX or carrier trunk, you do not need phone numbers or SIP credentials in BlackBox. Point your telephony at a hostname you own and let one agent answer everything sent to it.
**1. Add and verify the domain**
Go to **Phone Numbers → SIP Domains**, add your hostname (for example `calls.yourcompany.com`), create the DNS records shown in the domain details, and click **Verify**. The DNS setup is described in [Register Call → Use your own domain](/docs/deploy/register-call#use-your-own-domain).
**2. Choose the agent**
> [tab] Dashboard
>
> Open the domain details and pick an agent under **Inbound routing**.
> [tab] API
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> await fetch(`https://blackbox.dasha.ai/api/v1/sip-domains/${domainId}`, {
> method: 'PATCH',
> headers: {
> 'Authorization': 'Bearer YOUR_API_KEY',
> 'Content-Type': 'application/json'
> },
> body: JSON.stringify({ defaultAgentId: agentId })
> });
> ```
**3. Send calls to the domain**
Configure your PBX or carrier to send calls to `sip:@calls.yourcompany.com`, for example `sip:+14155550100@calls.yourcompany.com`. The agent answers, and the caller number from the SIP From header becomes the call endpoint.
> [!NOTE]
>
> Registered calls (`sip:{callId}@calls.yourcompany.com`) always keep the agent they were registered with. The domain agent only handles user parts that are not a registered call id. A domain without an agent rejects such calls with SIP `404`.
***
## Configure greeting
> [card] [Talk First](/docs/advanced-features/talk-first)
>
> Configure the agent's first message when answering calls
***
## Set business hours
Control when your agent accepts inbound calls:
> [tab] Dashboard
>
> 1. Go to **Agents** → Select agent → **Edit**
> 2. Navigate to **Schedule** section
> 3. Set your business hours and timezone
> 4. Click **Save Agent**
> [tab] API
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> await fetch(`https://blackbox.dasha.ai/api/v1/agents/${agentId}`, {
> method: 'PUT',
> headers: {
> 'Authorization': 'Bearer YOUR_API_KEY',
> 'Content-Type': 'application/json'
> },
> body: JSON.stringify({
> schedule: {
> timezone: "America/New_York",
> mon: [{ start: { hour: 9, minute: 0 }, end: { hour: 17, minute: 0 } }],
> tue: [{ start: { hour: 9, minute: 0 }, end: { hour: 17, minute: 0 } }],
> wed: [{ start: { hour: 9, minute: 0 }, end: { hour: 17, minute: 0 } }],
> thu: [{ start: { hour: 9, minute: 0 }, end: { hour: 17, minute: 0 } }],
> fri: [{ start: { hour: 9, minute: 0 }, end: { hour: 17, minute: 0 } }]
> }
> })
> });
> ```
**No schedule configured = 24/7 availability.**
> [card] [Scheduling & Availability](/docs/create/scheduling-availability)
>
> Complete guide to business hours, holidays, and timezone configuration
***
## Test inbound calls
**1. Verify setup**
* Agent is enabled (`isEnabled: true`)
* Phone number is linked for inbound
* SIP credentials are valid (check registration status)
**2. Make a test call**
Call the phone number from your mobile phone
**3. Verify connection**
Agent should answer with configured greeting
**4. Review in dashboard**
Go to **Calls** → Verify call appears in history with transcript
***
## Check phone number status
Verify a phone number is correctly linked:
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const phoneNumber = await fetch(
`https://blackbox.dasha.ai/api/v1/sip-phone-numbers/${phoneNumberId}`,
{ headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());
console.log('Phone:', phoneNumber.phoneNumber);
console.log('Inbound agent:', phoneNumber.incomingCallsAgentId || 'Not linked');
console.log('Registration:', phoneNumber.registrationStatus);
```
***
## Unlink a phone number
Stop routing calls to an agent:
> [tab] Dashboard
>
> 1. Navigate to **Phone Numbers**
> 2. Click on the phone number
> 3. Clear the **Inbound Agent** dropdown (select "None")
> 4. Click **Save**
> [tab] API
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> await fetch(
> `https://blackbox.dasha.ai/api/v1/sip-phone-numbers/${phoneNumberId}/agent-link?mode=inbound`,
> {
> method: 'DELETE',
> headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
> }
> );
> ```
After unlinking, calls to this number will not be answered.
***
## Troubleshooting
### Calls not reaching agent
| Symptom | Fix |
| - | - |
| Call goes to voicemail | Verify phone number is linked to an agent |
| "Number not in service" | Check SIP registration status is successful |
| Ring but no answer | Verify agent is enabled |
### Agent not answering correctly
| Symptom | Fix |
| - | - |
| No greeting plays | Set `firstMessage` in agent config |
| Wrong agent answers | Check phone number is linked to correct agent |
| Agent unavailable | Check business hours schedule |
### Registration issues
| Symptom | Fix |
| - | - |
| Status: "Not registered" | Verify SIP credentials are correct |
| Status: "Failed" | Check server address and transport protocol |
| Intermittent failures | Enable registration if your provider requires it |
***
## What's next
> [card] [Outbound Calls](/docs/deploy/outbound-calls)
>
> Make calls via API
> [card] [Phone Numbers](/docs/deploy/phone-numbers)
>
> Add and manage phone numbers
> [card] [Business Hours](/docs/create/scheduling-availability)
>
> Configure availability schedule
> [card] [Call History](/docs/monitor/call-history)
>
> Monitor inbound calls
# Make Outbound Calls via API
Source: https://blackbox.dasha.ai/docs/deploy/outbound-calls
Schedule outbound calls through the API. Link phone numbers for caller ID, set priorities, and run campaigns at scale.
Make your agent call customers. Link a phone number for caller ID, then schedule calls via API with priority ordering and custom data.
**What you'll learn:** How to set up outbound calling, schedule calls via API, and monitor call status.
***
## Prerequisites
Before making outbound calls:
1. **Agent configured** and enabled
2. **Phone number added** with valid SIP credentials
3. **Phone number linked** to agent for outbound
> [card] [Phone Numbers](/docs/deploy/phone-numbers)
>
> Complete guide to adding phone numbers and SIP credentials
***
## Link a phone number for outbound calls
Set the caller ID your agent uses when making calls:
> [tab] Dashboard
>
> 1. Go to **Agents** → Select agent → **Edit**
> 2. Find **Outbound Phone Number** section
> 3. Select a phone number from the dropdown
> 4. Click **Save Agent**
> [tab] API
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> // Link phone number to agent for outbound calls
> await fetch(
> `https://blackbox.dasha.ai/api/v1/sip-phone-numbers/${phoneNumberId}/agent-link?agentId=${agentId}&mode=replaceOutbound`,
> {
> method: 'PUT',
> headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
> }
> );
> ```
> [!NOTE]
>
> Each agent can have one outbound phone number. Linking a new number replaces the previous one.
***
## Schedule a call
### Quick test from dashboard
Test your agent before running campaigns:
1. Go to your agent's page
2. Click **Test Call**
3. Enter the target phone number
4. Click **Call** — starts immediately
### Schedule via API
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch(
'https://blackbox.dasha.ai/api/v1/calls?agentId=YOUR_AGENT_ID',
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
endpoint: '+15551234567',
priority: 5,
additionalData: {
customerId: 'cust_123',
campaignId: 'spring_promo'
}
})
}
);
const call = await response.json();
console.log('Call scheduled:', call.callId);
```
***
## Schedule bulk calls
Schedule multiple calls in one request:
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch(
'https://blackbox.dasha.ai/api/v1/calls/bulk?agentId=YOUR_AGENT_ID',
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify([
{ endpoint: '+15551234567', priority: 5, additionalData: { name: 'John' } },
{ endpoint: '+15559876543', priority: 5, additionalData: { name: 'Jane' } },
{ endpoint: '+15555555555', priority: 5, additionalData: { name: 'Bob' } }
])
}
);
const result = await response.json();
console.log('Scheduled calls:', result);
```
***
## Monitor call status
### Check individual call
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const call = await fetch(
`https://blackbox.dasha.ai/api/v1/calls/${callId}`,
{ headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());
console.log('Status:', call.status);
// Created → Queued → Pending → InProgress → Completed/Failed
```
### View queue
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const queue = await fetch(
`https://blackbox.dasha.ai/api/v1/calls/queue/list?agentId=${agentId}`,
{ headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());
console.log(`Calls in queue: ${queue.totalCount}`);
queue.items.forEach(call => {
console.log(` ${call.endpoint} - Priority ${call.priority}`);
});
```
### Receive webhooks
Configure webhooks for real-time status updates:
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// When scheduling the call
{
endpoint: '+15551234567',
completedWebHook: 'https://your-server.com/call-completed',
failedWebHook: 'https://your-server.com/call-failed'
}
```
> [card] [Webhook Events](/docs/webhooks-and-events/webhook-events)
>
> Complete webhook payload reference
***
## Cancel a scheduled call
Cancel calls that haven't started yet:
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
await fetch(
`https://blackbox.dasha.ai/api/v1/calls/${callId}`,
{
method: 'DELETE',
headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}
);
```
> [!WARNING]
>
> Only calls in **Created**, **Queued**, or **Pending** status can be canceled. Calls already **InProgress** cannot be canceled via API.
***
## Call lifecycle
```
Created → Queued → Pending → InProgress → Completed
↘ Failed
```
| Status | Description |
| - | - |
| **Created** | Call record created, not yet queued |
| **Queued** | Waiting in queue based on priority |
| **Pending** | About to be dialed |
| **InProgress** | Call connected, agent speaking |
| **Completed** | Call finished successfully |
| **Failed** | Call failed (busy, no answer, error) |
***
## Troubleshooting
### Calls not scheduling
| Symptom | Fix |
| - | - |
| 400 Bad Request | Verify phone number format (E.164: +15551234567) |
| 404 Agent Not Found | Check agentId is correct |
| "No outbound config" | Link a phone number to the agent for outbound |
### Calls stuck in queue
| Symptom | Fix |
| - | - |
| Calls not processing | Check agent is enabled |
| Slow queue processing | Check business hours schedule |
| Hitting concurrency limit | Upgrade plan or reduce call volume |
### Low answer rates
| Symptom | Fix |
| - | - |
| Many "No Answer" | Call during optimal hours (10am-4pm local) |
| Calls marked spam | Use local area code numbers |
| Quick hang-ups | Improve greeting, reduce agent latency |
***
## What's next
> [card] [Phone Numbers](/docs/deploy/phone-numbers)
>
> Add phone numbers for caller ID
> [card] [Caller ID](/docs/deploy/caller-id)
>
> Configure display names
> [card] [Call History](/docs/monitor/call-history)
>
> Monitor call results
> [card] [Webhooks](/docs/webhooks-and-events/webhook-events)
>
> Handle call completion events
# Connect Phone Numbers to Your Agents
Source: https://blackbox.dasha.ai/docs/deploy/phone-numbers
Add phone numbers for inbound and outbound calls. Connect via Twilio integration or manually configure SIP credentials from any provider.
Connect phone numbers to receive inbound calls and make outbound calls. Use the Twilio integration for automatic setup, or manually configure SIP credentials from any provider.
**What you'll learn:** How to add phone numbers via Twilio or manual SIP configuration, link numbers to agents, and manage your telephony setup.
***
## Two ways to add phone numbers
| Method | Setup time | Best for |
| - | - | - |
| **Twilio integration** | 2 minutes | Quick setup, automatic SIP trunk configuration |
| **Manual SIP credentials** | 5-10 minutes | Any SIP provider (Telnyx, Bandwidth, Vonage, etc.) |
***
## Option 1: Twilio integration
Connect your Twilio account and import phone numbers with automatic SIP trunk configuration.
### Step 1: Create Twilio provider
> [tab] Dashboard
>
> 1. Navigate to **Phone Numbers** in the sidebar
> 2. Click **Add Provider** → **Twilio**
> 3. Enter your Twilio **Account SID** and **Auth Token**
> 4. Click **Connect**
> [tab] API
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> const response = await fetch('https://blackbox.dasha.ai/api/v1/providers/twilio', {
> method: 'POST',
> headers: {
> 'Authorization': 'Bearer YOUR_API_KEY',
> 'Content-Type': 'application/json'
> },
> body: JSON.stringify({
> name: 'My Twilio Account',
> accountSid: 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
> authToken: 'your-auth-token'
> })
> });
>
> const provider = await response.json();
> console.log('Provider created:', provider.id);
> ```
This automatically:
* Creates a SIP trunk in your Twilio account
* Generates SIP credentials for authentication
* Stores everything securely in your organization
### Step 2: Import phone numbers
> [tab] Dashboard
>
> 1. In your Twilio provider, click **Import Numbers**
> 2. Select the phone numbers you want to use
> 3. Click **Import Selected**
> [tab] API
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> // First, list available numbers
> const available = await fetch(
> `https://blackbox.dasha.ai/api/v1/providers/twilio/${providerId}/available-numbers`,
> { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
> ).then(r => r.json());
>
> console.log('Available numbers:', available);
>
> // Import selected numbers
> const result = await fetch(
> `https://blackbox.dasha.ai/api/v1/providers/twilio/${providerId}/import-numbers`,
> {
> method: 'POST',
> headers: {
> 'Authorization': 'Bearer YOUR_API_KEY',
> 'Content-Type': 'application/json'
> },
> body: JSON.stringify({
> phoneNumberSids: ['PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx']
> })
> }
> ).then(r => r.json());
>
> console.log(`Imported: ${result.successCount}, Failed: ${result.failedCount}`);
> ```
### Step 3: Link to agent
See [Link phone numbers to agents](#link-phone-numbers-to-agents) below.
***
## Option 2: Manual SIP credentials
Configure SIP credentials from any provider (Telnyx, Bandwidth, Vonage, or others).
### Step 1: Create SIP credentials
> [tab] Dashboard
>
> 1. Navigate to **Phone Numbers** → **Credentials** tab
> 2. Click **Add Credentials**
> 3. Enter your SIP provider details:
> * **Server**: SIP server address (e.g., `sip.telnyx.com`)
> * **Auth User**: Your SIP username
> * **Password**: Your SIP password
> * **Transport**: UDP, TCP, or TLS
> 4. Click **Save**
> [tab] API
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> const response = await fetch('https://blackbox.dasha.ai/api/v1/sip-credentials', {
> method: 'POST',
> headers: {
> 'Authorization': 'Bearer YOUR_API_KEY',
> 'Content-Type': 'application/json'
> },
> body: JSON.stringify({
> server: 'sip.telnyx.com',
> authUser: 'your-username',
> authPassword: 'your-password',
> transport: 'udp',
> description: 'Telnyx Production Trunk'
> })
> });
>
> const credentials = await response.json();
> console.log('Credentials ID:', credentials.id);
> ```
### Step 2: Add phone numbers
> [tab] Dashboard
>
> 1. Navigate to **Phone Numbers** → **Numbers** tab
> 2. Click **Add Number**
> 3. Enter the phone number and select credentials
> 4. Enable **Registration** if your provider requires it
> 5. Click **Save**
> [tab] API
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> const response = await fetch('https://blackbox.dasha.ai/api/v1/sip-phone-numbers', {
> method: 'POST',
> headers: {
> 'Authorization': 'Bearer YOUR_API_KEY',
> 'Content-Type': 'application/json'
> },
> body: JSON.stringify({
> phoneNumber: '+14155551234',
> credentialsId: 'your-credentials-id',
> displayName: 'Support Line',
> registration: true
> })
> });
>
> const phoneNumber = await response.json();
> console.log('Phone number ID:', phoneNumber.id);
> ```
### Step 3: Link to agent
See [Link phone numbers to agents](#link-phone-numbers-to-agents) below.
***
## Link phone numbers to agents
After adding phone numbers, link them to agents for inbound routing or outbound calling.
### For inbound calls
Link a phone number to an agent so incoming calls route to that agent:
> [tab] Dashboard
>
> 1. Go to **Phone Numbers** → **Numbers** tab
> 2. Click on a phone number
> 3. Select an agent from the **Inbound Agent** dropdown
> 4. Click **Save**
> [tab] API
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> await fetch(
> `https://blackbox.dasha.ai/api/v1/sip-phone-numbers/${phoneNumberId}/agent-link?agentId=${agentId}&mode=inbound`,
> {
> method: 'PUT',
> headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
> }
> );
> ```
### For outbound calls
Set a phone number as an agent's outbound caller ID:
> [tab] Dashboard
>
> 1. Go to **Agents** → Select agent → **Edit**
> 2. In the **Outbound Phone Number** section, select a number
> 3. Click **Save Agent**
> [tab] API
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> await fetch(
> `https://blackbox.dasha.ai/api/v1/sip-phone-numbers/${phoneNumberId}/agent-link?agentId=${agentId}&mode=replaceOutbound`,
> {
> method: 'PUT',
> headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
> }
> );
> ```
***
## SIP credentials reference
| Field | Required | Description |
| - | - | - |
| `server` | Yes | SIP server hostname with optional port (e.g., `sip.provider.com:5060`) |
| `authUser` | No | Authentication username |
| `authPassword` | No | Authentication password |
| `domain` | No | SIP domain for authentication realm |
| `transport` | No | Protocol: `udp` (default), `tcp`, or `tls` |
| `description` | No | Human-readable label |
| `cpsLimit` | No | Max calls per second through this trunk |
| `cpsKey` | No | Shared rate limit key across multiple credentials |
***
## Phone number reference
| Field | Required | Description |
| - | - | - |
| `phoneNumber` | Yes | Phone number (E.164 format recommended) |
| `credentialsId` | Yes | SIP credentials to use for this number |
| `displayName` | No | Caller ID display name |
| `description` | No | Human-readable label |
| `registration` | No | Enable SIP registration (default: false) |
***
## Check what's using a phone number
Before modifying or deleting, see which agents use a phone number:
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const affected = await fetch(
`https://blackbox.dasha.ai/api/v1/sip-phone-numbers/${phoneNumberId}/affected-agents`,
{ headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());
console.log('Inbound agent:', affected.inboundAgent);
console.log('Outbound agents:', affected.outboundAgents);
```
***
## Troubleshooting
### Registration failing
| Symptom | Fix |
| - | - |
| Status shows "Not registered" | Check credentials are correct; verify provider requires registration |
| 401 Unauthorized | Verify `authUser` and `authPassword` match provider exactly |
| Timeout errors | Check `server` address and port; try different `transport` |
### Inbound calls not connecting
| Symptom | Fix |
| - | - |
| Calls go to voicemail | Verify phone number is linked to an agent |
| 404 Not Found | Check the phone number exists and registration succeeded |
| Agent doesn't answer | Verify agent is enabled and has valid configuration |
### Outbound calls failing
| Symptom | Fix |
| - | - |
| "No outbound config" | Link a phone number to the agent for outbound |
| Authentication errors | Verify SIP credentials are correct |
| Invalid caller ID | Ensure phone number is verified with your provider |
***
## Next steps
> [card] [Inbound Calls](/docs/deploy/inbound-calls)
>
> Handle incoming calls
> [card] [Outbound Calls](/docs/deploy/outbound-calls)
>
> Make outbound calls via API
> [card] [Caller ID](/docs/deploy/caller-id)
>
> Configure display names
> [card] [SIP Configuration](/docs/deploy/sip-configuration)
>
> Advanced SIP settings
# Production Checklist
Source: https://blackbox.dasha.ai/docs/deploy/production-checklist
Essential verification steps before launching your voice AI agent to production.
Complete these checks before enabling your agent for production traffic.
> [!WARNING]
>
> Never enable an agent for production without completing all **Critical** items.
***
## Critical checks
### Agent configuration
* [ ] System prompt is production-ready (no placeholders or TODOs)
* [ ] Agent name and description are accurate (not "Test Agent")
* [ ] Agent is currently disabled (`isEnabled: false`)
### LLM and voice
* [ ] Model latency tested under 2 seconds
* [ ] Temperature set between 0.6-0.8
* [ ] TTS voice pronunciation verified for key terms
* [ ] Speech recognition tested with target accents
### Tools and integrations
* [ ] All tools tested in actual conversations
* [ ] Tool endpoints are production URLs (not localhost/staging)
* [ ] Tool authentication uses production credentials
* [ ] All URLs use HTTPS
### Security
* [ ] Production API keys configured and stored securely
* [ ] Web integration origins restricted (no wildcard `*`)
* [ ] Webhook endpoints use HTTPS with authentication
### Testing completed
* [ ] Core use case tested 10+ times with voice
* [ ] Multi-turn conversations maintain context
* [ ] Silence handling works (agent prompts after 5+ seconds)
* [ ] Interruption handling works (agent stops and listens)
### Monitoring
* [ ] Dashboard access verified for team
* [ ] Error alerts configured (alert when error rate > 5%)
* [ ] On-call rotation defined with escalation path
***
## Important checks
* [ ] System prompt reviewed by team member
* [ ] Edge cases tested (unclear input, out-of-scope requests)
* [ ] Tool timeout handling verified
* [ ] Support team trained on agent capabilities
* [ ] Incident response runbook created
***
## Launch procedure
### Pre-launch (1 hour before)
1. Verify all critical items completed
2. Run final end-to-end test
3. Confirm team is available and briefed
4. Confirm rollback plan is ready
### Go-live
1. Enable agent (`isEnabled: true`)
2. Review first 5 calls in real-time
3. Verify no errors or unexpected behavior
### First hour
* Active monitoring by team member
* Check error rate, latency, and webhook status
* Review early transcripts for issues
***
## Key metrics
| Metric | Target | Alert threshold |
| - | - | - |
| Error rate | \< 5% | > 10% |
| Call success rate | > 80% | \< 70% |
| Webhook success | > 95% | \< 90% |
| Latency | \< 2s | > 3s |
***
## When to disable immediately
* Error rate > 20% for 10+ minutes
* Security breach suspected
* Agent providing harmful responses
* Unexpected cost spike
***
## Emergency rollback
1. **Disable agent** — Set `isEnabled` to `false`
2. **Notify stakeholders** — Inform team of incident
3. **Preserve evidence** — Export transcripts and logs
4. **Investigate** — Review recent changes
5. **Fix and re-test** — Before re-enabling
> [!WARNING]
>
> Know how to disable your agent before going live. Practice the rollback procedure with your team.
***
## Related
> [card] [Call History](/docs/monitor/call-history)
>
> Monitor agent performance
> [card] [Call Inspector](/docs/test/call-inspector)
>
> Debug specific calls
# Register Inbound Calls and Bridge Them to Your Agent
Source: https://blackbox.dasha.ai/docs/deploy/register-call
Keep your own inbound call flow. Register a call with the agent and variables it needs, receive a call ID and SIP destination, and bridge the live call to it.
Register an inbound call that your telephony already holds, then bridge it to the SIP destination BlackBox returns. The agent answers with the variables you registered, and the call ID you stored is the correlation key on every webhook and result.
**What you'll learn:** When to use registration instead of linked phone numbers, how the register-then-bridge flow works, and how to handle results.
***
## When to use it
Use **Register Call** when:
* Your telephony (PBX, SIP provider, contact-center platform) receives the call first.
* You decide per call which agent should answer and which variables it needs.
* You need one call ID shared between your system and BlackBox for the complete call lifecycle.
Use [Inbound Calls](/docs/deploy/inbound-calls) instead when a phone number should always route to the same agent.
***
## How it works
1. Your telephony receives the inbound call.
2. You register the call: `POST /api/v1/calls/register?agentId=…`.
3. BlackBox creates the call record and returns `callId` and `sipUri` (`sip:{callId}@sip-reg.blackbox.dasha.ai`).
4. You store `callId` and bridge the live call to `sipUri`.
5. BlackBox recognizes the registered call and starts the agent with your variables.
6. The result reaches the agent's result webhook with the same `callId`.
> [!NOTE]
>
> The registration stays valid until `callDeadline` (default 10 minutes, maximum 24 hours). If the call is not bridged by then, it is canceled and reported through the result webhook with `status: "Canceled"`.
***
## Register a call
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const registration = await fetch(
`https://blackbox.dasha.ai/api/v1/calls/register?agentId=${agentId}`,
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
fromNumber: '+14155550100',
toNumber: '+14155550200',
additionalData: {
customerName: 'Jane Doe',
accountId: 'acct_123'
},
callDeadline: new Date(Date.now() + 5 * 60 * 1000).toISOString()
})
}
).then(r => r.json());
console.log('Call ID:', registration.callId);
console.log('Bridge to:', registration.sipUri);
// sip:6f1c2c9e-…@sip-reg.blackbox.dasha.ai
```
Response:
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"callId": "6f1c2c9e-5d0a-4b1e-9e7d-0d2c1f3a4b5c",
"sipUri": "sip:6f1c2c9e-5d0a-4b1e-9e7d-0d2c1f3a4b5c@sip-reg.blackbox.dasha.ai",
"orgId": "org_abc",
"agentId": "agent_123",
"fromNumber": "+14155550100",
"toNumber": "+14155550200",
"additionalData": { "customerName": "Jane Doe", "accountId": "acct_123" },
"status": "Registered",
"direction": "Inbound",
"callDeadline": "2026-09-04T10:15:00Z",
"createdTime": "2026-09-04T10:10:00Z"
}
```
| Field | Required | Description |
| - | - | - |
| `fromNumber` | Yes | Number of the original caller. Reported as the call endpoint. |
| `toNumber` | No | Number that received the call. Informational. |
| `additionalData` | No | Variables for prompts, referenced as `{{variableName}}`. Merged with the agent's own data. |
| `callDeadline` | No | ISO 8601 time until which the registration stays valid. Default 10 minutes, maximum 24 hours. |
***
## Bridge the call
Point your telephony at `sipUri`. Any system that can transfer or bridge a live call to a SIP URI works.
> [tab] Twilio (TwiML)
>
> ```xml theme={"theme":{"light":"github-light","dark":"github-dark"}}
>
>
> sip:6f1c2c9e-5d0a-4b1e-9e7d-0d2c1f3a4b5c@sip-reg.blackbox.dasha.ai
>
>
> ```
> [tab] Asterisk
>
> ```
> exten => _X.,1,Dial(PJSIP/6f1c2c9e-5d0a-4b1e-9e7d-0d2c1f3a4b5c@blackbox-register)
> ```
>
> Define `blackbox-register` as a PJSIP endpoint whose contact is `sip:sip-reg.blackbox.dasha.ai`.
> [tab] FreeSWITCH
>
> ```
>
> ```
> [!WARNING]
>
> Bridge each registration exactly once. A second INVITE for the same call ID is rejected with SIP `410 Gone`.
BlackBox answers the INVITE with a SIP status when it cannot take the call:
| SIP status | Meaning |
| - | - |
| `404 Not Found` | The user part of the URI is not a registered call ID. |
| `410 Gone` | The registration expired or was already used. |
| `603 Decline` | The agent is disabled or no longer exists. |
| `486 Busy Here` | Your organization has no free concurrency slot. |
***
## Receive the result
Configure a result webhook on the agent. The payload carries the same `callId`, your `additionalData` as `callAdditionalData`, the transcript, the recording URL and `callType: "InboundAudio"`.
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
app.post('/blackbox/result', (req, res) => {
const { callId, status, result, transcription, recordingUrl } = req.body;
// callId is the value you stored at registration
res.sendStatus(200);
});
```
> [card] [Webhook Events](/docs/webhooks-and-events/webhook-events)
>
> Complete webhook payload reference
***
## Use your own domain
Registered calls can use a hostname you own instead of `sip-reg.blackbox.dasha.ai`, so the URI you hand to your telephony or your customers reads `sip:{callId}@calls.yourcompany.com`. DNS sends the call directly to Dasha; you do not need a SIP proxy in the path.
**1. Add the domain**
> [tab] Dashboard
>
> Go to **Phone Numbers → SIP Domains**, click **Add Domain** and enter the hostname, for example `calls.yourcompany.com`.
> [tab] API
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> const domain = await fetch('https://blackbox.dasha.ai/api/v1/sip-domains', {
> method: 'POST',
> headers: {
> 'Authorization': 'Bearer YOUR_API_KEY',
> 'Content-Type': 'application/json'
> },
> body: JSON.stringify({ domain: 'calls.yourcompany.com' })
> }).then(r => r.json());
>
> console.log(domain.status); // PendingVerification
> console.log(domain.dns); // records to create, see below
> ```
**2. Create the DNS records**
The domain details list two kinds of records. Create them at your DNS provider.
| Purpose | Type | Name | Value |
| - | - | - | - |
| Prove ownership | `TXT` | `_dasha-verify.calls.yourcompany.com` | `dasha-domain-verification=` |
| Route calls to Dasha | `CNAME` | `calls.yourcompany.com` | `sip.us.dasha.ai` |
SIP phones and PBXs resolve the host with A records, which the CNAME provides. Use a dedicated hostname for the domain: a CNAME cannot share its name with other records, so `calls.yourcompany.com` must not carry any other record. The TXT record lives at `_dasha-verify.calls.yourcompany.com`, which is fine next to the CNAME.
**3. Verify**
> [tab] Dashboard
>
> Click **Verify** on the domain. It becomes **Active** when the TXT record is found. The details also show whether the routing records already point at Dasha.
> [tab] API
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> const verified = await fetch(
> `https://blackbox.dasha.ai/api/v1/sip-domains/${domain.id}/verify`,
> { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
> ).then(r => r.json());
>
> console.log(verified.status); // Active, or PendingVerification with lastError
> console.log(verified.routingRecordsDetected); // true when the domain already resolves to Dasha
> ```
DNS changes can take a few minutes to propagate; verify again if the record is not found yet.
**4. Register calls on the domain**
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const registration = await fetch(
`https://blackbox.dasha.ai/api/v1/calls/register?agentId=${agentId}`,
{
method: 'POST',
headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' },
body: JSON.stringify({
fromNumber: '+14155550100',
sipDomainId: domain.id
})
}
).then(r => r.json());
console.log(registration.sipUri);
// sip:6f1c2c9e-…@calls.yourcompany.com
```
> [!NOTE]
>
> Custom SIP domains are enabled per organization. A hostname can belong to one organization only, and ownership is proven by the TXT record, so any hostname you control works. Names starting with `sip` under `dasha.ai` are reserved by the Dasha platform and fail verification.
***
## Check a registered call
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const call = await fetch(
`https://blackbox.dasha.ai/api/v1/calls/${callId}`,
{ headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());
console.log(call.status); // Registered → Running → Completed
console.log(call.direction); // Inbound
```
To cancel a registration before it is bridged, delete the call: `DELETE /api/v1/calls/{callId}`.
# SIP Credentials and Trunk Configuration
Source: https://blackbox.dasha.ai/docs/deploy/sip-configuration
Configure SIP trunk credentials for connecting to any VoIP provider. Set up authentication, transport protocols, and rate limiting.
Configure SIP credentials to connect your organization to any VoIP provider. Credentials are shared across your organization — create them once, then link phone numbers to use them.
**What you'll learn:** How to configure SIP credentials, choose transport protocols, set up rate limiting, and troubleshoot connection issues.
***
## SIP credentials overview
SIP credentials store the authentication details for your SIP trunk provider. Create credentials once at the organization level, then link multiple phone numbers to use them.
***
## Create SIP credentials
> [tab] Dashboard
>
> 1. Navigate to **Phone Numbers** → **Credentials** tab
> 2. Click **Add Credentials**
> 3. Fill in the configuration fields
> 4. Click **Save**
> [tab] API
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> const response = await fetch('https://blackbox.dasha.ai/api/v1/sip-credentials', {
> method: 'POST',
> headers: {
> 'Authorization': 'Bearer YOUR_API_KEY',
> 'Content-Type': 'application/json'
> },
> body: JSON.stringify({
> server: 'sip.provider.com:5060',
> authUser: 'your-username',
> authPassword: 'your-password',
> domain: 'sip.provider.com',
> transport: 'udp',
> description: 'Production Trunk'
> })
> });
>
> const credentials = await response.json();
> ```
***
## Configuration fields
### Required
| Field | Format | Description |
| - | - | - |
| `server` | `hostname:port` | SIP server address. Include port if non-standard (default: 5060) |
### Authentication
| Field | Description |
| - | - |
| `authUser` | Username for SIP authentication (provided by your provider) |
| `authPassword` | Password for SIP authentication |
| `domain` | SIP domain/realm for authentication (often same as server hostname) |
### Transport
| Field | Values | Description |
| - | - | - |
| `transport` | `udp`, `tcp`, `tls` | Protocol for SIP signaling (default: `udp`) |
### Rate limiting
| Field | Description |
| - | - |
| `cpsLimit` | Maximum calls per second through this trunk |
| `cpsKey` | Shared key to combine rate limits across multiple credentials |
***
## Transport protocols
Choose the right transport based on your requirements:
| Protocol | Port | Encryption | Use when |
| - | - | - | - |
| **UDP** | 5060 | No | Standard setup, lowest latency |
| **TCP** | 5060 | No | Behind restrictive firewalls |
| **TLS** | 5061 | Yes | Security/compliance requirements |
> [accordion] Example: TLS configuration
>
> ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
> server: 'sip.provider.com:5061',
> authUser: 'your-username',
> authPassword: 'your-password',
> transport: 'tls'
> }
> ```
***
## Rate limiting
Control call pacing to avoid exceeding your provider's limits.
### Single trunk limit
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
server: 'sip.provider.com',
authUser: 'trunk-1',
cpsLimit: 10 // Max 10 calls/second
}
```
### Shared limit across trunks
When you have multiple trunks with a shared rate limit from your provider:
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Trunk 1
{
server: 'sip.provider.com',
authUser: 'trunk-1',
cpsLimit: 20,
cpsKey: 'provider-shared' // Share limit with trunk-2
}
// Trunk 2
{
server: 'sip.provider.com',
authUser: 'trunk-2',
cpsLimit: 20,
cpsKey: 'provider-shared' // Combined limit: 20 CPS total
}
```
***
## Provider-managed credentials
When you connect a Twilio provider, SIP credentials are created automatically:
* **Source**: Shows as `provider` instead of `manual`
* **Read-only**: Cannot modify provider-managed credentials
* **Lifecycle**: Deleted when the provider is deleted
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Response shows source type
{
id: 'cred-123',
source: 'provider', // Created by Twilio integration
providerId: 'prov-456', // Reference to Twilio provider
server: 'sip.twilio.com'
// ... other fields
}
```
***
## Check credential usage
Before modifying or deleting credentials, check which phone numbers and agents depend on them:
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const affected = await fetch(
`https://blackbox.dasha.ai/api/v1/sip-credentials/${credentialsId}/affected-agents`,
{ headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());
console.log('Phone numbers using these credentials:');
affected.phoneNumbers.forEach(pn => {
console.log(` ${pn.phoneNumber} → Agent: ${pn.linkedAgent?.name || 'none'}`);
});
console.log('Queued calls:', affected.queuedCallsCount);
```
***
## Delete credentials
> [!WARNING]
>
> Deleting credentials also deletes all associated phone numbers and updates affected agents.
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Check impact first
const affected = await fetch(
`https://blackbox.dasha.ai/api/v1/sip-credentials/${credentialsId}/affected-agents`,
{ headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
).then(r => r.json());
if (affected.queuedCallsCount > 0) {
console.log('Warning: calls in queue will fail');
}
// Delete with force flag if phone numbers exist
await fetch(
`https://blackbox.dasha.ai/api/v1/sip-credentials/${credentialsId}?force=true`,
{
method: 'DELETE',
headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}
);
```
***
## Troubleshooting
### Authentication failures
| Error | Cause | Fix |
| - | - | - |
| 401 Unauthorized | Wrong username/password | Verify credentials in provider portal |
| 403 Forbidden | IP not whitelisted | Add Dasha IPs to provider allowlist |
| Domain mismatch | Wrong `domain` value | Check provider's authentication realm |
### Connection issues
| Error | Cause | Fix |
| - | - | - |
| Timeout | Wrong server/port | Verify `server` address and port |
| Connection refused | Wrong transport | Try `tcp` instead of `udp` (or vice versa) |
| TLS handshake failed | Certificate issue | Check provider supports TLS; verify port 5061 |
### Rate limiting
| Error | Cause | Fix |
| - | - | - |
| 503 Service Unavailable | Exceeded provider CPS | Set `cpsLimit` below provider's limit |
| Calls dropping | Shared limit exceeded | Use `cpsKey` to combine trunk limits |
***
## Next steps
> [card] [Phone Numbers](/docs/deploy/phone-numbers)
>
> Add and link phone numbers
> [card] [Caller ID](/docs/deploy/caller-id)
>
> Configure display names
> [card] [Inbound Calls](/docs/deploy/inbound-calls)
>
> Handle incoming calls
> [card] [Outbound Calls](/docs/deploy/outbound-calls)
>
> Make outbound calls
# Embed Voice and Chat Widgets on Your Website
Source: https://blackbox.dasha.ai/docs/deploy/web-widget-embedding
Embed AI voice and chat widgets on your website. Add conversational AI to any page with a simple script tag.
Add your agent to any website. Users talk or chat with the agent directly in the browser — no phone number needed.
**What you'll learn:** Quick setup, embedding code, and platform-specific installation.
> [!TIP]
>
> The widget works on any HTTPS website. Voice calls require HTTPS; text chat works on HTTP.
***
## Quick start
**1. Create web integration**
Go to **Agents** → Select your agent → **Web Integrations** → **Add Integration**
**2. Add allowed origins**
Add your website domains: `https://example.com`, `https://www.example.com`
**3. Enable features**
Toggle AllowWebCall, AllowWebChat, or both
**4. Generate token**
Save → **Authentication** tab → **Generate Token** → Copy immediately (shown once)
**5. Embed on site**
Add before the closing `