# 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: <url>"; 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 <toolName>(<arguments>) = <result>`, 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 <toolName>(<arguments>) = <result>`, 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:<anything>@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"}} > <Response> > <Dial> > <Sip>sip:6f1c2c9e-5d0a-4b1e-9e7d-0d2c1f3a4b5c@sip-reg.blackbox.dasha.ai</Sip> > </Dial> > </Response> > ``` > [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 > > ``` > <action application="bridge" data="sofia/external/6f1c2c9e-5d0a-4b1e-9e7d-0d2c1f3a4b5c@sip-reg.blackbox.dasha.ai"/> > ``` > [!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=<token>` | | 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 `</body>` tag: ```html theme={"theme":{"light":"github-light","dark":"github-dark"}} <blackbox-agent server-url="https://blackbox.dasha.ai" token="YOUR_TOKEN" position="bottom-right" theme="dark" ></blackbox-agent> <script src="https://blackbox.dasha.ai/widget/blackbox-widget-v3.min.js" defer></script> ``` That's it. The widget appears on your site, ready for voice and chat conversations. *** ## Platform-specific installation > [card] [Widget Configuration](/docs/deploy/widget-configuration) > > Complete guide: React, Next.js, WordPress, attributes, features, and security *** ## Widget attributes | Attribute | Required | Description | | - | - | - | | `server-url` | Yes | Dasha BlackBox API server | | `token` | Yes | Web integration token | | `position` | No | `bottom-right`, `bottom-left`, `top-right`, `top-left` | | `theme` | No | `light` or `dark` | > [card] [Widget Customization](/docs/deploy/widget-customization) > > Complete guide: CSS variables, JavaScript API, and branding *** ## Security > [!WARNING] > > **Never use `*` wildcard** for all origins in production. This allows anyone to use your widget. Configure specific domains in the Origins tab: * `https://example.com` — exact match * `https://*.example.com` — all subdomains * `http://localhost:3000` — local development > [card] [Configuring Webhooks](/docs/webhooks-and-events/configuring-webhooks) > > Complete webhook configuration and security guide *** ## Troubleshooting | Issue | Solution | | - | - | | Widget not loading | Check token is correct, integration is enabled | | Origin blocked error | Add exact domain to origins (include `https://`) | | Voice not working | Verify site uses HTTPS, check mic permission | > [card] [Common Issues](/docs/troubleshooting/common-issues) > > Complete troubleshooting guide *** ## What's next > [card] [Widget Configuration](/docs/deploy/widget-configuration) > > Configure features, tokens, and security > [card] [Widget Customization](/docs/deploy/widget-customization) > > Customize styling and behavior > [card] [Production Checklist](/docs/deploy/production-checklist) > > Pre-launch verification > [card] [Call History](/docs/monitor/call-history) > > Track widget usage # Configure Widget Security and Features Source: https://blackbox.dasha.ai/docs/deploy/widget-configuration Configure web widget security, features, and appearance. Manage tokens, origin restrictions, and feature toggles. The dashboard provides five configuration tabs: Basic Info, Origins, Authentication, Features, and Test Widget. Complete them in order — some tabs depend on others. **What you'll learn:** Dashboard tabs walkthrough, origin patterns, token management, feature toggles, and allowed tools. ## Configuration tabs | Tab | Purpose | | - | - | | **Basic Info** | Name, description, enabled state | | **Origins** | Domain security (CORS) | | **Authentication** | Token generation and management | | **Features** | Capability toggles, allowed tools | | **Test Widget** | Live preview, embed code | **Complete tabs 1-2 first, save, then return to generate tokens in tab 3.** *** ## Basic settings ### Name and description Use clear, environment-specific names: | Do | Avoid | | - | - | | "Production Website Widget" | "Widget 1" | | "Staging - Support Chat" | "Test" | | "Mobile App - Voice Assistant" | "My Integration" | ### Enabled toggle | State | Effect | | - | - | | **Enabled** | Widget accepts connections | | **Disabled** | All connections rejected (even with valid token) | **Disable during maintenance or to immediately stop all widget access.** *** ## Origin restrictions Protect your widget from unauthorized use by whitelisting allowed domains. ### Add origins > [tab] Dashboard > > 1. Go to **Origins** tab > 2. Enter domain URL (e.g., `https://example.com`) > 3. Click **Add** or press Enter > 4. Repeat for additional domains > [tab] API > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > await fetch(`https://blackbox.dasha.ai/api/v1/web-integrations/${integrationId}`, { > method: 'PUT', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > origins: [ > 'https://example.com', > 'https://www.example.com', > 'https://*.example.com' > ] > }) > }); > ``` ### Origin patterns | Pattern | Matches | | - | - | | `https://example.com` | Exact domain only | | `https://www.example.com` | www subdomain only | | `https://*.example.com` | All subdomains (not root) | | `http://localhost:3000` | Local dev with specific port | ### Environment patterns > [tab] Production > > ``` > https://example.com > https://www.example.com > ``` > [tab] Multi-environment > > ``` > https://example.com > https://www.example.com > https://staging.example.com > http://localhost:3000 > ``` > [tab] All subdomains > > ``` > https://example.com > https://*.example.com > ``` > [!WARNING] > > **Never use `*`** to allow all origins in production. Remove `localhost` origins before deploying to production. *** ## Authentication Generate and manage access tokens for widget authentication. ### Generate token **1. Save integration first** Authentication tab is disabled until integration is saved **2. Open Authentication tab** Edit saved integration → **Authentication** tab **3. Enter token name** Use descriptive name: "Production Website Token" **4. Generate and copy** Click **Generate Token** → Copy immediately (shown once) ### Token security | Do | Avoid | | - | - | | Store in environment variables | Commit to Git | | Rotate every 90 days | Share across integrations | | Delete compromised tokens | Reuse deleted tokens | | Monitor "Last Used" timestamp | Use generic names | > [accordion] Store tokens securely > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > // .env (never commit) > BLACKBOX_WIDGET_TOKEN=bb_prod_abc123... > > // .gitignore > .env > .env.local > ``` ### Delete token 1. Click trash icon next to token 2. Confirm deletion 3. Token immediately revoked > [!WARNING] > > Deleting a token immediately breaks widgets using it. Update your site first. *** ## Feature toggles Control which capabilities are available in the widget. ### Available features | Feature | Description | When to enable | | - | - | - | | **AllowWebCall** | Voice calls via WebRTC | Voice-first support, demos | | **AllowWebChat** | Text chat messages | Universal (works everywhere) | | **AllowPhoneCall** | Phone call option | When phone backup needed | | **SendCallResult** | Return call data to page | Custom post-call UI | | **SendToolCallLogs** | Stream tool execution | Debugging only | | **SendTranscriptForAudioCall** | Real-time transcript | Accessibility, compliance | ### Feature combinations > [tab] Voice only > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > features: [ > { name: 'AllowWebCall', enabled: true }, > { name: 'SendTranscriptForAudioCall', enabled: true } > ] > ``` > > Best for: Sales calls, support requiring voice > [tab] Chat only > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > features: [ > { name: 'AllowWebChat', enabled: true } > ] > ``` > > Best for: FAQ bots, low-bandwidth users > [tab] Voice + Chat > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > features: [ > { name: 'AllowWebCall', enabled: true }, > { name: 'AllowWebChat', enabled: true }, > { name: 'SendCallResult', enabled: true } > ] > ``` > > Best for: Maximum flexibility ### Allowed tools Select which agent tools can be called via widget: 1. Go to **Features** tab 2. Click **Allowed Tools** dropdown 3. Select tools from agent and MCP sources 4. Only selected tools accessible from widget > [!TIP] > > Only expose safe, public-facing tools. Avoid administrative or sensitive operations. *** ## Appearance Configure visual presentation in the **Test Widget** tab. ### Theme | Theme | Use case | | - | - | | `light` | Light-colored websites | | `dark` | Dark-mode websites, tech products | ### Position | Position | Best for | | - | - | | `bottom-right` | Most websites (familiar pattern) | | `bottom-left` | Right side has other elements | | `top-right` | Dashboard interfaces | > [accordion] Embed code generation > > The Test Widget tab generates ready-to-use code: > > ```html theme={"theme":{"light":"github-light","dark":"github-dark"}} > <blackbox-agent > server-url="https://blackbox.dasha.ai" > token="YOUR_TOKEN" > position="bottom-right" > theme="dark" > skip-discovery > data-config='{"features":["AllowWebCall","AllowWebChat"]}' > ></blackbox-agent> > > <script src="https://blackbox.dasha.ai/widget/blackbox-widget-v3.min.js" defer></script> > ``` *** > [accordion] API configuration > > Update configuration programmatically: > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > await fetch(`https://blackbox.dasha.ai/api/v1/web-integrations/${integrationId}`, { > method: 'PUT', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > name: 'Production Website Widget', > enabled: true, > origins: ['https://example.com', 'https://www.example.com'], > features: [ > { name: 'AllowWebCall', enabled: true }, > { name: 'AllowWebChat', enabled: true }, > { name: 'SendCallResult', enabled: true } > ], > tools: ['check_order_status', 'schedule_callback'], > widgetAppearance: { > theme: 'dark', > position: 'bottom-right' > } > }) > }); > ``` *** ## Troubleshooting > [accordion] Token authentication failing > > **Causes**: Token deleted, integration disabled, token malformed > > **Solutions**: > > 1. Verify token exists in Authentication tab > 2. Check integration enabled toggle > 3. Re-copy token (no extra spaces) > 4. Generate new token if needed > [accordion] CORS errors in console > > **Causes**: Domain not in origins, protocol mismatch > > **Solutions**: > > 1. Add exact origin to allowed list > 2. Check `http://` vs `https://` > 3. Include port if non-standard > 4. Add both www and non-www > [accordion] Features not working > > **Causes**: Feature disabled, wrong data-config > > **Solutions**: > > 1. Enable feature in Features tab > 2. Check data-config JSON syntax > 3. Try without `skip-discovery` > 4. Verify feature appears in Test Widget > [accordion] Tools not executing > > **Causes**: Tool not in allowed list, tool deleted > > **Solutions**: > > 1. Add tool to Allowed Tools > 2. Verify tool exists in agent config > 3. Check MCP server connectivity > 4. Review tool error in Call Inspector *** ## What's next > [card] [Widget Customization](/docs/deploy/widget-customization) > > Advanced styling and JavaScript API > [card] [Web Widget Embedding](/docs/deploy/web-widget-embedding) > > Platform-specific installation > [card] [Production Checklist](/docs/deploy/production-checklist) > > Pre-launch verification > [card] [Webhook Events](/docs/webhooks-and-events/webhook-events) > > Handle widget events server-side # Customize Widget Appearance and Behavior Source: https://blackbox.dasha.ai/docs/deploy/widget-customization Customize widget appearance, themes, and behavior. Use CSS variables and JavaScript API for advanced control. Make the widget match your brand. Customize colors, themes, and position using CSS variables. Control behavior with the JavaScript API. **What you'll learn:** Theme and position options, feature gating, JavaScript API, event handling, CSS variables, and mobile optimization. ## Built-in customization > [accordion] Theme > > ```html theme={"theme":{"light":"github-light","dark":"github-dark"}} > <!-- Light theme --> > <blackbox-agent theme="light"></blackbox-agent> > > <!-- Dark theme --> > <blackbox-agent theme="dark"></blackbox-agent> > ``` | Theme | Best for | | - | - | | `light` | Light-colored websites, minimalist designs | | `dark` | Dark-mode sites, tech products, dashboards | > [accordion] Position > > ```html theme={"theme":{"light":"github-light","dark":"github-dark"}} > <!-- Bottom positions (recommended) --> > <blackbox-agent position="bottom-right"></blackbox-agent> > <blackbox-agent position="bottom-left"></blackbox-agent> > <blackbox-agent position="bottom-center"></blackbox-agent> > > <!-- Top positions --> > <blackbox-agent position="top-right"></blackbox-agent> > <blackbox-agent position="top-left"></blackbox-agent> > <blackbox-agent position="top-center"></blackbox-agent> > ``` > [!TIP] > > `bottom-right` is most familiar to users—it's where chat widgets typically appear. *** ## Feature gating Control which features appear in the widget UI. > [accordion] Configuration > > ```html theme={"theme":{"light":"github-light","dark":"github-dark"}} > <blackbox-agent > skip-discovery > data-config='{ > "features": ["AllowWebCall", "AllowWebChat"], > "enableFeatureGating": true, > "uiGatingMode": "hide" > }' > ></blackbox-agent> > ``` ### Gating modes | Mode | Behavior | | - | - | | `hide` | Completely remove disabled features | | `disable` | Show features grayed out | ### Common configurations > [tab] Voice only > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "features": ["AllowWebCall"], > "enableFeatureGating": true, > "uiGatingMode": "hide" > } > ``` > [tab] Chat only > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "features": ["AllowWebChat"], > "enableFeatureGating": true, > "uiGatingMode": "hide" > } > ``` > [tab] All features > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "features": [ > "AllowWebCall", > "AllowWebChat", > "SendCallResult", > "SendTranscriptForAudioCall" > ], > "enableFeatureGating": true, > "uiGatingMode": "disable" > } > ``` *** ## JavaScript API Control the widget programmatically for advanced integrations. > [accordion] Get widget reference > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const widget = document.querySelector('blackbox-agent'); > ``` > [accordion] Open and close > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > // Open widget > widget.open(); > > // Close widget > widget.close(); > > // Toggle > widget.toggle(); > ``` > [accordion] Trigger on events > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > // Open after scroll > window.addEventListener('scroll', () => { > if (window.scrollY > 500) widget.open(); > }); > > // Open on button click > document.getElementById('help-btn').addEventListener('click', () => { > widget.open(); > }); > > // Open for new visitors after delay > if (!localStorage.getItem('returning')) { > setTimeout(() => widget.open(), 5000); > localStorage.setItem('returning', 'true'); > } > ``` *** ## Event handling React to widget events in your application. > [accordion] Available events > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const widget = document.querySelector('blackbox-agent'); > > // Widget opened > widget.addEventListener('widget-opened', (e) => { > console.log('Widget opened'); > }); > > // Widget closed > widget.addEventListener('widget-closed', (e) => { > console.log('Widget closed'); > }); > > // Call started > widget.addEventListener('call-started', (e) => { > console.log('Call ID:', e.detail.callId); > console.log('Type:', e.detail.callType); // 'voice' or 'chat' > }); > > // Call ended > widget.addEventListener('call-ended', (e) => { > console.log('Duration:', e.detail.duration); > console.log('Status:', e.detail.status); > showFeedbackForm(); > }); > > // Error occurred > widget.addEventListener('widget-error', (e) => { > console.error('Error:', e.detail.error); > }); > > // Transcript update (if SendTranscriptForAudioCall enabled) > widget.addEventListener('transcript-update', (e) => { > console.log(`${e.detail.speaker}: ${e.detail.text}`); > }); > > // Tool executed (if SendToolCallLogs enabled) > widget.addEventListener('tool-executed', (e) => { > console.log('Tool:', e.detail.toolName); > console.log('Result:', e.detail.result); > }); > ``` > [accordion] Call result handling > > When `SendCallResult` is enabled: > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > widget.addEventListener('call-result', (e) => { > const result = e.detail; > > if (result.data.appointment) { > // Agent scheduled an appointment > addToCalendar(result.data.appointment); > } > > if (result.data.lead) { > // Agent captured lead info > sendToCRM(result.data.lead); > } > }); > ``` *** ## CSS customization Override CSS variables for custom styling. > [!WARNING] > > CSS variable names may change in future versions. Test after widget updates. > [accordion] Available variables > > ```css theme={"theme":{"light":"github-light","dark":"github-dark"}} > blackbox-agent { > /* Primary brand color */ > --widget-primary-color: #4F46E5; > > /* Backgrounds */ > --widget-background: #FFFFFF; > --widget-header-background: #F9FAFB; > > /* Text */ > --widget-text-primary: #111827; > --widget-text-secondary: #6B7280; > > /* Borders */ > --widget-border-color: #E5E7EB; > --widget-border-radius: 12px; > > /* Shadow */ > --widget-shadow: 0 10px 25px rgba(0, 0, 0, 0.1); > > /* Buttons */ > --widget-button-background: #4F46E5; > --widget-button-text: #FFFFFF; > --widget-button-hover: #4338CA; > > /* Size */ > --widget-width: 380px; > --widget-height: 600px; > > /* Position offset */ > --widget-offset-x: 20px; > --widget-offset-y: 20px; > } > ``` ### Brand examples > [tab] Blue Enterprise > > ```css theme={"theme":{"light":"github-light","dark":"github-dark"}} > blackbox-agent { > --widget-primary-color: #0066CC; > --widget-button-background: #0066CC; > --widget-button-hover: #0052A3; > --widget-border-radius: 8px; > } > ``` > [tab] Green Vibrant > > ```css theme={"theme":{"light":"github-light","dark":"github-dark"}} > blackbox-agent { > --widget-primary-color: #10B981; > --widget-button-background: #10B981; > --widget-button-hover: #059669; > --widget-border-radius: 16px; > } > ``` > [tab] Orange Energy > > ```css theme={"theme":{"light":"github-light","dark":"github-dark"}} > blackbox-agent { > --widget-primary-color: #FF5722; > --widget-button-background: #FF5722; > --widget-button-hover: #E64A19; > --widget-border-radius: 12px; > } > ``` > [accordion] Responsive sizing > > ```css theme={"theme":{"light":"github-light","dark":"github-dark"}} > /* Default desktop */ > blackbox-agent { > --widget-width: 380px; > --widget-height: 600px; > } > > /* Full screen on mobile */ > @media (max-width: 768px) { > blackbox-agent { > --widget-width: 100vw; > --widget-height: 100vh; > --widget-offset-x: 0; > --widget-offset-y: 0; > } > } > ``` *** > [accordion] Dynamic theme switching > > Match user preferences or site theme: > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const widget = document.querySelector('blackbox-agent'); > > // Follow system preference > const prefersDark = window.matchMedia('(prefers-color-scheme: dark)'); > widget.setAttribute('theme', prefersDark.matches ? 'dark' : 'light'); > > // Listen for changes > prefersDark.addEventListener('change', (e) => { > widget.setAttribute('theme', e.matches ? 'dark' : 'light'); > }); > ``` *** ## Mobile optimization The widget automatically adapts to mobile: * **Full-screen** when expanded * **Touch-optimized** buttons * **Prominent** microphone button * **Swipe gestures** to close ### Mobile best practices | Do | Avoid | | - | - | | Use bottom positions | Auto-open on load | | Prefer voice over typing | Use top-center (blocks nav) | | Test on actual devices | Make minimized button too small | | Allow easy dismissal | Require extensive typing | > [accordion] Mobile-specific config > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > function isMobile() { > return /Android|iPhone|iPad|iPod/i.test(navigator.userAgent) || > window.innerWidth < 768; > } > > if (isMobile()) { > const widget = document.querySelector('blackbox-agent'); > widget.setAttribute('position', 'bottom-center'); > } > ``` *** ## Use case examples > [accordion] Customer support > > ```html theme={"theme":{"light":"github-light","dark":"github-dark"}} > <style> > blackbox-agent.support { > --widget-primary-color: #2563EB; > --widget-border-radius: 8px; > } > </style> > > <blackbox-agent > class="support" > theme="light" > position="bottom-right" > data-config='{"features":["AllowWebCall","AllowWebChat"]}' > ></blackbox-agent> > > <script> > // Open if user is idle > let idle = 0; > setInterval(() => { > if (++idle > 30) { > document.querySelector('blackbox-agent').open(); > idle = 0; > } > }, 1000); > document.addEventListener('mousemove', () => idle = 0); > </script> > ``` > [accordion] Lead capture > > ```html theme={"theme":{"light":"github-light","dark":"github-dark"}} > <blackbox-agent > theme="dark" > position="bottom-center" > data-config='{"features":["AllowWebCall","SendCallResult"]}' > ></blackbox-agent> > > <script> > const widget = document.querySelector('blackbox-agent'); > > // Open after reading content > setTimeout(() => widget.open(), 45000); > > // Capture lead data > widget.addEventListener('call-result', (e) => { > if (e.detail.data?.lead) { > fetch('/api/leads', { > method: 'POST', > body: JSON.stringify(e.detail.data.lead) > }); > } > }); > </script> > ``` *** ## Accessibility The widget supports accessibility features: | Feature | Support | | - | - | | **Keyboard navigation** | Tab to focus, Enter to open | | **Screen readers** | ARIA labels on controls | | **Focus management** | Trapped when open | | **Escape key** | Closes widget | | **High contrast** | Supported | > [!TIP] > > Enable `SendTranscriptForAudioCall` to provide text alternatives for voice calls. *** ## What's next > [card] [Widget Configuration](/docs/deploy/widget-configuration) > > Configure security and features > [card] [Web Widget Embedding](/docs/deploy/web-widget-embedding) > > Installation guides > [card] [Webhooks](/docs/webhooks-and-events/webhooks-overview) > > Handle events server-side > [card] [Call History](/docs/monitor/call-history) > > Track widget performance # Account Settings Source: https://blackbox.dasha.ai/docs/introduction/account-settings Manage your Dasha BlackBox account, invite team members, and configure roles and permissions. Manage your workspace settings and team access. Invite developers, assign roles, and manage API keys — all from the Settings page. **Prerequisites:** Admin role in your Dasha BlackBox organization. ## Access settings Go to **Settings** in your dashboard sidebar to access account configuration. *** ## Roles and permissions Dasha BlackBox has two roles: | Role | Permissions | | - | - | | **Admin** | Full access including user management and organization settings | | **Developer** | Create agents, schedule calls, manage API keys — cannot manage users | The key difference: Developers cannot invite, remove, or manage other users. All other features are available to both roles. *** ## Invite team members **1. Open user settings** Go to **Settings** → **Users & Permissions** **2. Send invitation** Click **Invite User**, enter email, and select role (Admin or Developer) **3. User accepts** The invited user receives an email and signs in with Google SSO > [!NOTE] > > Removing a user doesn't delete their work. Agents and calls they created remain in the organization. *** ## Authentication Dasha BlackBox uses **Google SSO** for authentication. All users sign in through their Google account via Dasha.AI's authentication service. * No separate password to manage * Secure OAuth 2.0 authentication * Single sign-on across Dasha products *** ## API keys Generate API keys to authenticate API requests: **1. Open API settings** Go to **Settings** → **API Keys** **2. Create key** Click **Create API Key** and give it a descriptive name **3. Copy and store** Copy the key immediately — it won't be shown again > [!WARNING] > > Store API keys securely. Never commit them to version control or share them publicly. ### Using API keys Include the API key in the `Authorization` header: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X GET "https://blackbox.dasha.ai/api/v1/agents" \ -H "Authorization: Bearer YOUR_API_KEY" ``` *** ## Troubleshooting | Problem | Solution | | - | - | | Can't access settings | Verify you have Admin role | | Can't invite users | Only Admins can invite. Developers don't see the option | | Invitation not received | Check spam folder, verify email address, resend from dashboard | | Can't sign in | Ensure you're using the correct Google account | # Configure Your Voice Agent Source: https://blackbox.dasha.ai/docs/introduction/agents Learn how to configure AI voice agents in Dasha BlackBox — system prompts, LLM configuration, voice settings, and agent states. Each agent combines four components: a system prompt that defines behavior, an LLM for reasoning, a voice for speech, and optional tools for actions. Here's how they fit together. *** ## Agent components | Component | Required | What it does | | - | - | - | | System prompt | Yes | Defines personality, role, rules, knowledge | | LLM config | Yes | Which AI model powers the brain (OpenAI, Groq, etc.) | | Voice config | Yes | Which voice speaks the responses (ElevenLabs, Cartesia, etc.) | | Tools | No | External actions the agent can take mid-conversation | | Schedule | No | Business hours — when the agent accepts calls | | Webhooks | No | URLs to notify when things happen | *** ## Agent states An agent is either **enabled** or **disabled**. **Enabled** — Active and handling conversations. This is the default. Configuration changes apply immediately, even to active calls. **Disabled** — Paused. Won't accept new conversations. Existing calls complete normally. Configuration is preserved. No charges while disabled. > [accordion] API example: Disable an agent > > ```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({ isEnabled: false }) > }); > ``` > [!WARNING] > > Changes to enabled agents apply immediately. If you're making significant changes, disable the agent first, make changes, test, then re-enable. *** ## What's next > [card] [Conversations](/docs/introduction/conversations) > > Learn about conversation types and states > [card] [Tools](/docs/introduction/tools) > > Let your agent take actions > [card] [Create your first agent](/docs/create/creating-your-first-agent) > > Step-by-step guide > [card] [LLM Configuration](/docs/create/llm-configuration) > > Model selection and parameters # Understand Conversation Types and States Source: https://blackbox.dasha.ai/docs/introduction/conversations Learn about conversation types in Dasha BlackBox — inbound calls and outbound calls. Understand conversation states and what gets recorded. Every conversation progresses through defined states, generates a transcript, and produces metadata you can access via API or webhooks. This page covers how each type works. *** ## Conversation types | Type | How it starts | Use case | | - | - | - | | **Inbound phone** | Customer calls your phone number | Support lines, hotlines | | **Outbound phone** | Your agent calls a customer | Reminders, sales, notifications | | **Web voice** | User clicks widget on your website | Website support, embedded assistants | | **Web chat** | User types in widget on your website | Text-based support, live chat | | **Test** | You click "Test" in dashboard | Development, debugging | *** ## Conversation states | State | What's happening | | - | - | | **Created** | Call scheduled but not yet queued | | **Queued** | Waiting for available resources | | **Running** | Active conversation in progress | | **Completed** | Ended normally | | **Failed** | Error occurred (network, timeout, etc.) | | **Canceled** | Stopped before completion | *** ## What's recorded Every conversation automatically captures: * **Full transcript** — Everything said, timestamped * **Audio recording** — The actual audio (configurable) * **Post-call analysis** — Custom labels and insights extracted from the conversation * **Errors** — Any issues that occurred > [accordion] API example: Get conversation details > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const conversation = await fetch( > `https://blackbox.dasha.ai/api/v1/calls/${callId}`, > { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } > ); > // Returns: { transcription, durationSeconds, status, result, ... } > ``` *** ## What's next > [card] [Tools](/docs/introduction/tools) > > Let your agent take actions > [card] [Webhooks](/docs/introduction/webhooks) > > Get notified when things happen > [card] [Call Inspector](/docs/test/call-inspector) > > Analyze completed conversations > [card] [Inbound Calls](/docs/deploy/inbound-calls) > > Set up phone numbers # Understand Agents, Tools, and Webhooks Source: https://blackbox.dasha.ai/docs/introduction/core-concepts The four things you need to understand before building with Dasha BlackBox — agents, conversations, tools, and webhooks. Four concepts make up Dasha BlackBox. Understand these and everything else clicks into place. | Concept | What it is | One-liner | | - | - | - | | **Agent** | Your AI voice assistant | The thing that talks | | **Conversation** | A single interaction | One phone call or chat session | | **Tool** | An action the agent can take | "Check order status", "Book appointment" | | **Webhook** | A notification to your server | "Call just ended, here's the transcript" | *** ## Building Blocks ### [Agents](/docs/introduction/agents) Your AI voice assistant. Configure it once, deploy it, and it handles conversations autonomously. ### [Conversations](/docs/introduction/conversations) A single interaction between your agent and a person — an inbound or outbound phone call. ### [Tools](/docs/introduction/tools) Actions your agent can take mid-conversation. Check order status, book appointments, look up customer data. ### [Webhooks](/docs/introduction/webhooks) Notifications to your server when things happen. Call started, call ended, tool needs execution. *** ## How They Connect 1. You create an **Agent** with prompt, LLM, voice, and optionally tools 2. A **Conversation** starts via phone or API 3. **Tools** execute when the agent needs external data 4. **Webhooks** notify your systems at key moments 5. Everything is recorded in the **Transcript** *** ## Quick reference ### API resources | Resource | Endpoint | Purpose | | - | - | - | | Agents | `/api/v1/agents` | Create, update, delete agents | | Calls | `/api/v1/calls` | Schedule calls, get transcripts | | Voices | `/api/v1/voice` | List available voices | *** ## What's next > [card] [Quickstart](/docs/introduction/quickstart) > > Create your first agent in 5 minutes > [card] [Create your first agent](/docs/create/creating-your-first-agent) > > Detailed walkthrough of all options > [card] [Add tools](/docs/create/tools-and-functions) > > Let your agent take actions > [card] [Set up webhooks](/docs/webhooks-and-events/webhooks-overview) > > Integrate with your systems # Glossary Source: https://blackbox.dasha.ai/docs/introduction/glossary Definitions for Dasha BlackBox platform terminology. Quick reference for agents, conversations, tools, webhooks, and voice AI concepts. Quick reference for Dasha BlackBox platform terminology. *** ## Core Concepts ### Agent AI voice assistant that handles conversations autonomously. Configured with a system prompt, LLM, voice, and optionally tools. Agents can receive inbound calls and make outbound calls. ### Conversation Single interaction between an agent and a person. Each conversation has a unique ID and produces a transcript. ### Tool Action an agent can take mid-conversation. Tools call your API to perform operations like checking order status, booking appointments, or looking up customer data. Defined with JSON Schema for parameters. ### Webhook HTTP notification sent to your server when events occur. Events include call started, call ended, tool execution requested, and transcription updates. *** ## Voice & Speech ### TTS (Text-to-Speech) Technology that converts agent text responses into spoken audio. Dasha BlackBox supports multiple providers: ElevenLabs, Cartesia, Inworld, and more. ### STT (Speech-to-Text) Also called ASR (Automatic Speech Recognition). Converts caller speech into text that the agent can process. Handles accents, background noise, and real-time transcription. ### ASR (Automatic Speech Recognition) See STT. The technology that transcribes spoken words into text. ### Voice ID Identifier for a specific voice within a TTS provider. Each provider offers different voices with varying characteristics. ### Pronunciation Dictionary Custom rules for how the agent pronounces specific words. Useful for brand names, technical terms, and uncommon words. *** ## LLM Configuration ### LLM (Large Language Model) AI model that generates agent responses. Dasha BlackBox supports OpenAI, Anthropic, Google, Azure, Groq, and Reflex-1 models. ### Reflex-1 Dasha's in-house LLM optimized for real-time voice conversations with very fast response times. ### System Prompt Instructions that define agent behavior, personality, and capabilities. The foundation of agent configuration. ### Temperature LLM setting controlling response randomness. Lower values (0.3-0.5) produce consistent responses; higher values (0.7-0.9) produce more varied responses. *** ## Telephony ### SIP (Session Initiation Protocol) Standard protocol for voice calls over internet. Used for connecting to phone systems. ### SIP Trunk Connection between Dasha BlackBox and your phone system. Enables inbound and outbound calls through your existing phone numbers. ### SIP Credentials Organization-level authentication settings for your SIP trunk provider. Stores server address, username, password, and transport protocol. Multiple phone numbers can share the same credentials. ### Twilio Provider Managed SIP integration that automatically creates and configures SIP trunks. Simplifies setup by handling credential management and phone number provisioning through your Twilio account. ### CPS (Calls Per Second) Rate limit for simultaneous call attempts through a SIP trunk. Configured via `cpsLimit` to prevent overloading your telephony provider. ### E.164 Format International phone number format. Includes country code with + prefix: +12025551234. ### IVR (Interactive Voice Response) Automated phone menu system ("Press 1 for sales"). Dasha BlackBox agents can detect and navigate IVR systems during outbound calls. ### DTMF (Dual-Tone Multi-Frequency) Touch-tone signals generated when pressing phone keys. Used for navigating phone menus. *** ## Call Handling ### Inbound Call Call received by the agent. Caller dials a phone number connected to your agent. ### Outbound Call Call initiated by the agent. Scheduled via API to contact a recipient. ### Phone Number Linking Connecting a phone number to an agent. Use `inbound` mode for receiving calls or `replaceOutbound` mode for caller ID on outgoing calls. ### Caller ID Phone number displayed to recipients during outbound calls. Set by linking a phone number with `replaceOutbound` mode. ### Call Priority Number that orders queued outbound calls. Lower numbers are dialed first: `0`-`1` is high, `2`-`4` is normal, and `5` or more is low. Calls enqueued without a priority get `1`. Calls with the same priority are dialed in deadline order, earliest first. See [Concurrency monitoring](/docs/monitor/concurrency-monitoring#priority-during-capacity-constraints). ### Business Hours Schedule defining when an agent accepts inbound calls. Calls outside business hours can be rejected or handled differently. ### Warm Transfer Transfer where the agent briefs the human operator before connecting the caller. Operator receives context about the conversation. ### Three-Way Announcement Message played to the caller during warm transfer while the agent briefs the operator. Can be static text or dynamically generated using `smartV1` mode. ### Cold Transfer Direct transfer to a human operator without briefing. Faster but requires caller to re-explain their situation. ### HTTP Transfer Dynamic transfer routing via webhook. Your server determines the transfer destination based on real-time data. ### Call Recording Audio recording of the conversation. Enabled per-agent and stored for later review. ### Pre-Conversation Media Audio file played before the agent speaks. Configured separately for inbound, outbound, and web calls. Useful for greetings, disclaimers, or hold music. ### Noise Suppression Krisp-powered audio filtering that removes background noise from calls. Configured with a level from 0 (off) to 100 (maximum). Incurs additional per-minute fee. *** ## Integrations ### MCP (Model Context Protocol) Protocol for connecting external data sources and tools to agents. Enables dynamic capabilities without custom webhook development. ### Knowledge Base External information source connected to an agent. Agents can query knowledge bases to answer questions beyond their system prompt. *** ## Web Integrations ### Web Integration Configuration for embedding agents in websites. Includes allowed origins, enabled features (voice/chat), and widget appearance settings. ### Widget Embeddable UI component for your website. Provides voice or chat interaction with your agent directly in the browser. ### WebSocket Real-time communication protocol used for web voice calls and chat. Enables bidirectional streaming of audio and messages. ### Access Token Short-lived credential for authenticating WebSocket connections. Generated via API and passed to the widget for secure access. *** ## Monitoring ### Activity Logs System events tracked for debugging and auditing. Includes call events, tool executions, errors, and warnings. Searchable by event type, severity, agent, and date range. *** ## Events & Notifications ### StartWebHookPayload Webhook sent when a call begins. Can include custom data from the caller. ### CompletedWebHookPayload Webhook sent when a call ends. Contains transcript, call duration, and result data. ### ToolWebHookPayload Webhook requesting tool execution. Your server performs the action and returns the result. *** ## Performance ### Latency Time between user speech and agent response. Target is under 2 seconds for natural conversation. ### Concurrency Number of simultaneous active calls. Limited by account tier. ### Rate Limiting API request limits to prevent abuse. Tracked per endpoint with retry guidance. *** ## Account ### Organization Top-level account container. Holds all agents, integrations, and team members. ### API Key Authentication credential for API access. Starts with `bb_`. Keep secret and never expose in client-side code. *** ## Related > [card] [Core Concepts](/docs/introduction/core-concepts) > > Detailed explanation of building blocks > [card] [Quickstart](/docs/introduction/quickstart) > > Create your first agent # Create Your First Voice Agent in 5 Minutes Source: https://blackbox.dasha.ai/docs/introduction/quickstart Create a voice agent and test it in your browser — 5 minutes, no phone number required. Let's build something that talks. In the next 5 minutes, you'll create a voice agent and have an actual conversation with it — right in your browser. No phone number needed, no credit card, no complicated setup. By the end, you'll have a working agent you can customize however you want. ## Create your agent **1. Sign in** Head to [blackbox.dasha.ai](https://blackbox.dasha.ai) and sign in. If you don't have an account yet, creating one takes about 30 seconds. **2. Create a new agent** From your dashboard, click **Create Agent**. You'll see a form with a few fields to fill in. **3. Set up the basics** Here's what to enter: | Field | What to put | | - | - | | **Name** | Something like `My First Agent` — you can always change it later | | **Language** | Pick `English (USA)` for now | | **System Prompt** | Try: `You are a friendly assistant. Keep your answers short and conversational.` | **4. Save it** Click **Save Agent** — and that's it! Your agent exists now. **That took about 2 minutes.** Nice work! *** ## Talk to it Now for the fun part — let's hear your agent speak. **1. Start a test call** Click the **Test** button in the top right corner. Your browser will ask for microphone access — go ahead and allow it. **2. Say something** Try: "Hello, what can you help me with?" **3. Listen** Your agent will respond — using the same voice and AI that it'll use in production. This isn't a simulation; it's the real thing. **You're at about 4 minutes now.** One more quick thing. *** ## See what happened Every conversation gets recorded, so you can review what went well and what to improve. **1. Open your call history** Click **Calls** in the left sidebar. **2. Find your test call** It'll be at the top — the most recent one. **3. Check it out** Click **Inspect** to see the full transcript, how long each response took, and any errors that popped up. **That's 5 minutes.** You just built a voice agent. *** ## What's next? Your agent works — now let's make it actually useful. > [card] [Full setup guide](/docs/create/creating-your-first-agent) > > Walk through every setting in detail > [card] [Pick a better voice](/docs/create/voice-and-speech) > > Choose from 50+ voices across different providers > [card] [Add superpowers](/docs/create/tools-and-functions) > > Let your agent check orders, book appointments, look up information > [card] [Get a phone number](/docs/deploy/phone-numbers) > > Put your agent on a real phone line *** ## Something not working? > [card] [Troubleshooting](/docs/troubleshooting/common-issues) > > Agent not responding? Voice sounds weird? We've got quick fixes for the common hiccups. # Enable Agent Actions with Tools Source: https://blackbox.dasha.ai/docs/introduction/tools Learn how to define tools that let your Dasha BlackBox agent take actions — check order status, book appointments, look up customer data, and more. When your agent needs information or must perform an action, it calls a tool. You define the tool with JSON Schema, point it at your webhook, and the LLM decides when to use it. *** ## Defining a tool Tools are defined using JSON Schema with a name, description, parameters, and webhook URL. The `description` is critical — it tells the LLM WHEN to use the tool. Be specific. > [accordion] Example: Tool definition > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "name": "checkOrderStatus", > "description": "Look up order status by order number. Use when customer asks about their order, shipping, or delivery.", > "parameters": { > "type": "object", > "properties": { > "orderNumber": { > "type": "string", > "description": "The order number like ORD-12345" > } > }, > "required": ["orderNumber"] > }, > "webhookUrl": "https://api.yourcompany.com/webhooks/order-status" > } > ``` *** ## How tools work When your agent needs to use a tool, it calls your webhook with the parameters. The agent takes the result and speaks it naturally — it won't read your response word-for-word. > [accordion] Example: Webhook request > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "ToolWebHookPayload", > "status": "Running", > "callId": "call_abc123", > "agentId": "agent_xyz789", > "orgId": "org_123", > "toolName": "checkOrderStatus", > "arguments": { > "orderNumber": "ORD-12345" > }, > "callAdditionalData": {}, > "agentAdditionalData": {} > } > ``` > [accordion] Example: Webhook response > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "status": "shipped", > "orderNumber": "ORD-12345", > "shippedDate": "2025-01-15", > "carrier": "FedEx", > "trackingNumber": "789123456789", > "estimatedDelivery": "2025-01-18" > } > ``` *** ## Built-in tools Some tools are built in and don't need webhooks: | Tool | What it does | | - | - | | `transferCall` | Hand off to a human or another number | | `endConversation` | End the call gracefully | *** ## What's next > [card] [Webhooks](/docs/introduction/webhooks) > > Get notified when things happen > [card] [Tools & Functions](/docs/create/tools-and-functions) > > Complete tools guide > [card] [MCP Connections](/docs/create/mcp-connections) > > Connect external tool servers > [card] [Call Transfers](/docs/advanced-features/call-transfers) > > Route calls to humans # Receive Event Notifications with Webhooks Source: https://blackbox.dasha.ai/docs/introduction/webhooks Learn how webhooks notify your server when things happen in Dasha BlackBox — call started, call ended, tool execution, and more. Configure an endpoint, and Dasha BlackBox sends HTTP POST requests whenever calls start, end, fail, or need tool execution. Your server processes these events to update CRM systems, trigger workflows, or customize agent behavior. *** ## Webhook types | Webhook | When it fires | What you get | | - | - | - | | **Start** | Conversation begins | Caller info, agent config | | **Result** | Conversation ends | Full transcript, duration, status | | **Tool** | Agent invokes a tool | Tool name, parameters | | **Failed** | Call fails | Error details | | **Deadline** | Call times out | Timeout info | *** ## Result webhook When a call ends, your server receives the full conversation data. > [accordion] Example: Result webhook payload > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "CompletedWebHookPayload", > "status": "Completed", > "callId": "call_abc123", > "agentId": "agent_xyz789", > "durationSeconds": 127, > "transcription": [ > { "speaker": "assistant", "text": "Hi, how can I help you today?" }, > { "speaker": "user", "text": "I need to check on my order" } > ], > "result": { > "finishReason": "user_hangup", > "postCallAnalysis": {} > }, > "inspectorUrl": "https://blackbox.dasha.ai/calls/call_abc123" > } > ``` *** ## Common patterns **Log to CRM** — Send transcript to Salesforce, HubSpot after every call. **Dynamic configuration** — Use start webhook to customize agent behavior per-caller (load customer history, set special instructions). **Alerting** — Notify Slack when calls fail or contain certain keywords. **Analytics** — Pipe results to your data warehouse for custom reporting. *** ## What's next > [card] [Webhooks Overview](/docs/webhooks-and-events/webhooks-overview) > > Complete webhooks guide > [card] [Tools](/docs/introduction/tools) > > Let your agent take actions > [card] [Post-Call Analysis](/docs/advanced-features/post-call-analysis) > > Extract insights from conversations > [card] [WebSockets](/docs/websockets/websockets-overview) > > Real-time bidirectional communication # Build AI Voice Agents for Phone and Web Source: https://blackbox.dasha.ai/docs/introduction/what-is-blackbox Build AI voice agents that handle phone calls and web conversations. Create an agent in 5 minutes, deploy with real phone numbers, scale to thousands of concurrent calls. Imagine if your phone lines could answer themselves — with real conversations, not robotic menus. That's Dasha BlackBox. You build a voice agent, teach it what to say, and let it handle calls while you focus on everything else. No more hold music. No more "press 1 for sales." Just natural conversations that actually help your customers. ## What people are building Here's what real businesses are doing with Dasha BlackBox right now: **A busy e-commerce store** handles 500+ support calls every day. Their agent answers shipping questions, processes returns, and knows when to bring in a human for the tricky stuff. What used to take 8 minutes now takes 2.5. **A growing SaaS company** qualifies leads before they reach the sales team. The agent asks about budget, timeline, and what they're looking for. Now sales only talks to people who are actually ready to buy — and their conversion rate tripled. **A healthcare clinic** cut no-shows by 40%. Their agent calls patients the day before appointments, confirms they're coming, and reschedules if needed. Patients love the reminder. The front desk loves not making 200 calls a day. **A delivery company** keeps customers in the loop. "Your package arrives in 30 minutes — will someone be home?" Customers just answer naturally, and the route updates automatically. ## What you can do with it | Feature | What it means for you | | - | - | | **Multiple AI providers** | Try different models, find what works best. Switch anytime without rewriting anything. | | **50+ natural voices** | Find a voice that fits your brand. Or clone your own. | | **Phone + web** | Put your agent on a real phone number, or embed it right in your website. | | **Smart actions** | Your agent can check inventory, book appointments, look up orders — all mid-conversation. | | **40+ languages** | Go global without rebuilding. | | **Fast responses** | Under 2 seconds. Conversations feel natural, not awkward. | | **Instant notifications** | Know when calls start, end, or need your attention. | | **Full transcripts** | Every conversation saved and searchable. | ## Two ways to get started > [tab] Dashboard (no code needed) > > The visual builder is perfect for getting started — and honestly, most people never need anything else. > > 1. Sign in at [blackbox.dasha.ai](https://blackbox.dasha.ai) > 2. Click **Create Agent** > 3. Tell it what to say, pick a voice, choose an AI model > 4. Test it right in your browser > 5. When you're happy, connect it to a phone number or your website > > This is where most people start, especially if you're not a developer. You can build something real in about 10 minutes. > [tab] API (for developers) > > If you want to automate things, integrate with your systems, or build at scale — the API gives you full control. > > > [accordion] Example: Create an agent with code > > > > ```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: "Support Agent", > > config: { > > primaryLanguage: "en-US", > > llmConfig: { > > vendor: "openai", > > model: "gpt-4.1-mini", > > prompt: "You are a helpful support agent..." > > }, > > ttsConfig: { > > vendor: "ElevenLabs", > > voiceId: "21m00Tcm4TlvDq8ikWAM" > > } > > } > > }) > > }); > > // Returns: { agentId: "agent_abc123", name: "Support Agent", ... } > > ``` ## Ready to try it? > [card] [Quickstart](/docs/introduction/quickstart) > > Build your first agent in 5 minutes — seriously, we timed it > [card] [Core concepts](/docs/introduction/core-concepts) > > Understand how agents, conversations, and tools work together # Activity Logs Source: https://blackbox.dasha.ai/docs/monitor/activity-logs Track every action in your organization: webhooks, tool calls, API requests, agent changes, and call lifecycle events. Search, filter, and analyze with full-text search and aggregations. Track what happened, when, and why. Activity logs capture every significant event across your organization — from webhook deliveries to tool executions to agent configuration changes. **What you'll learn:** How to search and filter activity logs, understand event types and severities, and use the API for programmatic access. *** ## Access activity logs > [tab] Dashboard > > Navigate to **Activity Logs** in the sidebar to view all events across your organization. > [tab] API > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const response = await fetch( > 'https://blackbox.dasha.ai/api/v1/activity-logs/search', > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > page: 0, > size: 50, > sortDirection: 'Descending' > }) > } > ).then(r => r.json()); > > console.log(`Total events: ${response.totalCount}`); > response.results.forEach(event => { > console.log(`[${event.severity}] ${event.type}: ${event.message}`); > }); > ``` *** ## Event types Activity logs capture events across four categories: ### Agent lifecycle | Type | Description | | - | - | | **AgentCreated** | A new agent was created | | **AgentUpdated** | An existing agent was updated | | **AgentDeleted** | An agent was deleted | | **AgentCloned** | An agent was cloned from another agent | ### Conversation lifecycle | Type | Description | | - | - | | **CallCreated** | A conversation was created via REST API or WebSocket | | **CallBulkScheduled** | A bulk batch of conversations was scheduled | | **CallCanceled** | A conversation was canceled | | **CallCompleted** | A conversation completed successfully | | **CallFailed** | A conversation failed | | **CallDeadlineExceeded** | A conversation exceeded its deadline | | **CallDispatched** | A conversation was dispatched to the runner for execution | | **CallReceived** | An incoming call was received | | **CallRejectedByWebhook** | A conversation was rejected by the start webhook | ### Webhooks | Type | Description | | - | - | | **WebhookSuccess** | A webhook was delivered successfully | | **WebhookFailed** | A webhook delivery failed | ### Runtime events | Type | Description | | - | - | | **ToolCallSuccess** | A tool call executed successfully during a conversation | | **ToolCallFailed** | A tool call failed during a conversation | | **McpCallExecuted** | An MCP (Model Context Protocol) call was executed | ### Configuration changes | Type | Description | | - | - | | **ConfigurationCreated** | A configuration resource was created (provider, SIP, media, integration) | | **ConfigurationUpdated** | A configuration resource was updated | | **ConfigurationDeleted** | A configuration resource was deleted | *** ## Severity levels Each event has a severity level indicating its importance: | Severity | Description | Examples | | - | - | - | | **Info** | Normal operation, no action required | Successful webhook delivery, call completed | | **Warning** | Something unusual happened but operation continued | Slow webhook response, retry succeeded | | **Error** | An operation failed | Webhook timeout, tool call error | | **Critical** | Severe failure requiring immediate attention | Authentication failure, system unavailable | *** ## Caller types Events track who initiated the action: | Caller | Description | | - | - | | **User** | Action initiated by a user via API, dashboard, or web interface | | **System** | Action initiated by the platform (scheduler, webhooks, internal processes) | *** ## Filter activity logs ### By event type Filter to specific event types to focus your analysis: > [accordion] Filter by type > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const response = await fetch( > 'https://blackbox.dasha.ai/api/v1/activity-logs/search', > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > types: ['WebhookFailed', 'ToolCallFailed'], > size: 50 > }) > } > ).then(r => r.json()); > > console.log(`Failed events: ${response.totalCount}`); > ``` ### By severity Focus on errors and critical issues: > [accordion] Filter by severity > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const response = await fetch( > 'https://blackbox.dasha.ai/api/v1/activity-logs/search', > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > severities: ['Error', 'Critical'], > size: 100 > }) > } > ).then(r => r.json()); > > response.results.forEach(event => { > console.log(`[${event.severity}] ${event.message}`); > if (event.metadata) { > console.log(' Details:', JSON.stringify(event.metadata, null, 2)); > } > }); > ``` ### By date range Query events within a specific time window: > [accordion] Filter by date range > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const response = await fetch( > 'https://blackbox.dasha.ai/api/v1/activity-logs/search', > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > fromDate: '2026-04-01T00:00:00Z', > toDate: '2026-04-15T23:59:59Z', > size: 100 > }) > } > ).then(r => r.json()); > > console.log(`Events in range: ${response.totalCount}`); > ``` ### By agent or call Track events for a specific agent or call: > [accordion] Filter by agent > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const response = await fetch( > 'https://blackbox.dasha.ai/api/v1/activity-logs/search', > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > agentIds: ['YOUR_AGENT_ID'], > size: 50 > }) > } > ).then(r => r.json()); > ``` > [accordion] Filter by call > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const response = await fetch( > 'https://blackbox.dasha.ai/api/v1/activity-logs/search', > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > callIds: ['YOUR_CALL_ID'], > size: 50 > }) > } > ).then(r => r.json()); > ``` ### Full-text search Search across event messages and metadata: > [accordion] Text search > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const response = await fetch( > 'https://blackbox.dasha.ai/api/v1/activity-logs/search', > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > searchText: 'timeout', > size: 50 > }) > } > ).then(r => r.json()); > > console.log(`Events mentioning "timeout": ${response.totalCount}`); > ``` *** ## Aggregations Search results include aggregated counts for quick analysis. These show how events break down by type, severity, and caller across all matching results — not just the current page. ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} const response = await fetch( 'https://blackbox.dasha.ai/api/v1/activity-logs/search', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ fromDate: '2026-04-01T00:00:00Z', toDate: '2026-04-15T23:59:59Z', size: 0 // Only get aggregations, no results }) } ).then(r => r.json()); console.log('By type:', response.aggregations?.typeCounts); // { WebhookSuccess: 1523, ToolCallSuccess: 892, CallCompleted: 456, ... } console.log('By severity:', response.aggregations?.severityCounts); // { Info: 2800, Warning: 45, Error: 12, Critical: 1 } console.log('By caller:', response.aggregations?.callerCounts); // { System: 2750, User: 108 } ``` *** ## API response structure ### Search activity logs **Request:** `POST /api/v1/activity-logs/search` **Request body:** | Field | Type | Default | Description | | - | - | - | - | | `page` | integer | 0 | Page number (0-indexed) | | `size` | integer | 20 | Results per page (max 100) | | `types` | ActivityEventType\[] | — | Filter by event types | | `severities` | ActivityEventSeverity\[] | — | Filter by severity levels | | `callers` | ActivityEventCaller\[] | — | Filter by caller (User, System) | | `userEmail` | string | — | Filter by user email | | `callIds` | string\[] | — | Filter by call IDs | | `agentIds` | string\[] | — | Filter by agent IDs | | `fromDate` | DateTimeOffset | — | Start of date range | | `toDate` | DateTimeOffset | — | End of date range | | `searchText` | string | — | Full-text search query | | `sortField` | string | "timestamp" | Field to sort by | | `sortDirection` | SortDirection | Descending | Ascending or Descending | > [accordion] Response example > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "results": [ > { > "eventId": "evt_abc123", > "orgId": "org_xyz", > "userEmail": null, > "type": "WebhookSuccess", > "severity": "Info", > "callId": "call_def456", > "agentId": "agent_ghi789", > "message": "Webhook delivered successfully to https://api.example.com/webhook", > "caller": "System", > "metadata": { > "url": "https://api.example.com/webhook", > "statusCode": 200, > "responseTimeMs": 145 > }, > "timestamp": "2026-04-15T10:30:00Z" > }, > { > "eventId": "evt_def456", > "orgId": "org_xyz", > "userEmail": "developer@company.com", > "type": "AgentUpdated", > "severity": "Info", > "callId": null, > "agentId": "agent_ghi789", > "message": "Agent configuration updated", > "caller": "User", > "metadata": { > "changedFields": ["systemPrompt", "ttsConfig"] > }, > "timestamp": "2026-04-15T10:25:00Z" > } > ], > "totalCount": 2858, > "page": 0, > "size": 20, > "totalPages": 143, > "aggregations": { > "typeCounts": { > "WebhookSuccess": 1523, > "CallCompleted": 456, > "ToolCallSuccess": 892 > }, > "severityCounts": { > "Info": 2800, > "Warning": 45, > "Error": 12, > "Critical": 1 > }, > "callerCounts": { > "System": 2750, > "User": 108 > } > }, > "executionTimeMs": 23 > } > ``` *** ## Common tasks > [accordion] Find all failed webhooks > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const response = await fetch( > 'https://blackbox.dasha.ai/api/v1/activity-logs/search', > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > types: ['WebhookFailed'], > sortDirection: 'Descending', > size: 50 > }) > } > ).then(r => r.json()); > > response.results.forEach(event => { > console.log(`Call ${event.callId}: ${event.message}`); > if (event.metadata) { > console.log(` URL: ${event.metadata.url}`); > console.log(` Error: ${event.metadata.error || event.metadata.statusCode}`); > } > }); > ``` > [accordion] Debug a specific call > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > // Get all events for a specific call > const response = await fetch( > 'https://blackbox.dasha.ai/api/v1/activity-logs/search', > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > callIds: ['YOUR_CALL_ID'], > sortField: 'timestamp', > sortDirection: 'Ascending', > size: 100 > }) > } > ).then(r => r.json()); > > // Timeline of events > response.results.forEach(event => { > const time = new Date(event.timestamp).toISOString(); > console.log(`${time} [${event.type}] ${event.message}`); > }); > ``` > [accordion] Monitor tool call failures > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const response = await fetch( > 'https://blackbox.dasha.ai/api/v1/activity-logs/search', > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > types: ['ToolCallFailed'], > fromDate: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(), // Last 24h > size: 100 > }) > } > ).then(r => r.json()); > > // Group by tool name > const byTool = {}; > response.results.forEach(event => { > const toolName = event.metadata?.toolName || 'unknown'; > byTool[toolName] = (byTool[toolName] || 0) + 1; > }); > > console.log('Tool failures by name:', byTool); > ``` > [accordion] Track agent configuration changes > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const response = await fetch( > 'https://blackbox.dasha.ai/api/v1/activity-logs/search', > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > types: ['AgentCreated', 'AgentUpdated', 'AgentDeleted'], > callers: ['User'], > size: 50 > }) > } > ).then(r => r.json()); > > response.results.forEach(event => { > console.log(`${event.userEmail} ${event.type} agent ${event.agentId}`); > if (event.metadata?.changedFields) { > console.log(` Changed: ${event.metadata.changedFields.join(', ')}`); > } > }); > ``` *** ## Troubleshooting with activity logs Activity logs are your first stop when debugging issues. Here's how to approach common problems: ### Webhook not triggering? 1. Search for `WebhookFailed` events for your agent 2. Check the `metadata` field for error details (timeout, DNS failure, HTTP status) 3. Verify webhook URL is publicly accessible ### Tool calls failing silently? 1. Filter by `types: ['ToolCallFailed']` and your call ID 2. Review error messages and response times in metadata 3. Check if the tool webhook is responding within the 10-second timeout ### Unexpected call behavior? 1. Get the full event timeline for the call ID (sort ascending by timestamp) 2. Look for warning or error severity events 3. Check if `CallRejectedByWebhook` or `CallFailed` events explain the issue > [!NOTE] > > Activity logs are retained for 90 days. For longer retention or compliance requirements, export logs periodically using the search API. *** ## What's next > [card] [Call History](/docs/monitor/call-history) > > View and search past calls > [card] [Call Inspector](/docs/test/call-inspector) > > Deep dive into individual calls > [card] [Webhook Events](/docs/webhooks-and-events/webhook-events) > > Understand webhook payloads > [card] [Testing Webhooks](/docs/webhooks-and-events/testing-webhooks) > > Test webhook delivery # Call History Source: https://blackbox.dasha.ai/docs/monitor/call-history View, filter, and search past calls. Access transcripts, recordings, and detailed call information through the dashboard or API. Find any past call. Filter by status, date, agent, or endpoint — then drill down to transcripts, recordings, and tool executions for complete conversation analysis. **What you'll learn:** Filtering and searching calls, viewing call details, and API response structure. ## Access call history > [tab] Dashboard > > Navigate to **Calls** in the sidebar to view all calls. > [tab] From agent > > Navigate to **Agents** → Select agent → **Calls** tab to view calls for that specific agent. > [tab] API > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > // Search call results with pagination > const response = await fetch( > 'https://blackbox.dasha.ai/api/v1/callresults/search', > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > page: 0, > size: 50 > }) > } > ).then(r => r.json()); > > console.log(`Total calls: ${response.totalCount}`); > response.results.forEach(call => { > console.log(`${call.callId}: ${call.callStatus}`); > }); > ``` *** ## Filter calls ### By status Filter calls by their final outcome: | Status | Description | | - | - | | **Completed** | Conversation finished successfully | | **Failed** | Error occurred during call | | **Canceled** | Call was canceled before completion | | **Running** | Call currently in progress | | **Queued** | Waiting in queue | | **Pending** | Waiting to be queued | | **Created** | Just created, not yet queued | > [accordion] API example: Filter by status > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const response = await fetch( > 'https://blackbox.dasha.ai/api/v1/callresults/search', > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > callStatuses: ['Completed', 'Failed'], > page: 0, > size: 50 > }) > } > ).then(r => r.json()); > ``` > [accordion] Filter by date range > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const response = await fetch( > 'https://blackbox.dasha.ai/api/v1/callresults/search', > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > fromDate: '2025-01-01T00:00:00Z', > toDate: '2025-01-31T23:59:59Z', > page: 0, > size: 50 > }) > } > ).then(r => r.json()); > > console.log(`Calls in January: ${response.totalCount}`); > ``` > [accordion] Filter by agent > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const response = await fetch( > 'https://blackbox.dasha.ai/api/v1/callresults/search', > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > agentIds: ['YOUR_AGENT_ID'], > page: 0, > size: 50 > }) > } > ).then(r => r.json()); > > console.log(`Agent calls: ${response.totalCount}`); > ``` > [accordion] Full-text search > > Search across transcripts and metadata: > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const response = await fetch( > 'https://blackbox.dasha.ai/api/v1/callresults/search', > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > searchText: 'connection timeout', > page: 0, > size: 50 > }) > } > ).then(r => r.json()); > ``` *** ## View call details ### Quick details Click any call row to expand inline details: * **Full call ID** — Complete identifier for API operations * **Duration and timestamps** — Precise timing information * **Agent configuration** — Agent that handled the call * **Additional data** — Custom metadata passed when scheduling * **Transcript preview** — Quick view of conversation ### Open Call Inspector Click the **Inspect** button for full analysis: * Complete transcript with timestamps * Audio recording playback * Tool execution logs * LLM interaction details * Performance metrics > [card] [Call Inspector](/docs/test/call-inspector) > > Deep dive into individual calls *** ## API response structure ### Search call results **Request:** `POST /api/v1/callresults/search` **Request body:** | Field | Type | Description | | - | - | - | | `page` | integer | Page number (0-indexed) | | `size` | integer | Results per page (max 100) | | `fromDate` | DateTimeOffset | Filter start date | | `toDate` | DateTimeOffset | Filter end date | | `agentIds` | string\[] | Filter by agents | | `callStatuses` | CallStatus\[] | Filter by status | | `searchText` | string | Full-text search | | `includeAggregations` | boolean | Include statistics | > [accordion] Example: Search response > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "results": [ > { > "callId": "call_abc123", > "agentId": "agent_def456", > "orgId": "org_xyz", > "callStatus": "Completed", > "callType": "OutboundAudio", > "createdTime": "2025-01-20T10:30:00Z", > "completedTime": "2025-01-20T10:35:00Z", > "durationSeconds": 300, > "endpoint": "+1-555-123-4567", > "callAdditionalData": { > "customerId": "cust_123" > }, > "transcription": [...], > "result": {...}, > "inspectorUrl": "https://...", > "recordingUrl": "https://..." > } > ], > "totalCount": 150, > "page": 0, > "size": 20, > "totalPages": 8, > "executionTimeMs": 45 > } > ``` ### Structured failure attribution Newly recorded failed calls can include an optional `failure` object. It is the same customer-safe object returned by result webhooks, Activity Logs, blocking SIP test calls, and terminal WebSocket errors. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "callStatus": "Failed", "errorMessage": "Your configured LLM provider rejected the request. Provider response: model access denied", "failure": { "stage": "llm", "reason": "forbidden", "upstreamOwner": "customer", "protocol": "http", "statusCode": 403, "retryable": false, "message": "Your configured LLM provider rejected the request.", "upstreamMessage": "model access denied" } } ``` `failure` is omitted or `null` for successful calls and historical records created before structured attribution was available. Missing or unfamiliar ownership fails closed to `platform`, which suppresses `upstreamMessage`. Do not infer stage or ownership from `errorMessage`; use the structured fields when present. The completed-call fallback returned by `GET /api/v1/calls/{callId}` uses the same shape. The blocking SIP test-call API also includes the optional object in its terminal result. ### Get single call **Request:** `GET /api/v1/calls/{callId}` Returns call details including status, timestamps, and endpoint. *** ## Get call queue View scheduled and pending calls: **Request:** `GET /api/v1/calls/queue/list` **Query parameters:** | Parameter | Type | Description | | - | - | - | | `skip` | integer | Items to skip | | `take` | integer | Items to return (max 1000) | | `agentId` | string | Filter by agent | | `status` | CallStatus\[] | Filter by status | | `fromDate` | DateTimeOffset | Filter start date | | `toDate` | DateTimeOffset | Filter end date | *** ## Call statistics Get aggregated call statistics: **Request:** `GET /api/v1/calls/statistics/statuses` ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} const response = await fetch( 'https://blackbox.dasha.ai/api/v1/calls/statistics/statuses', { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } ).then(r => r.json()); console.log('Call counts by status:', response.statuses); // { Created: 5, Pending: 3, Queued: 10, Running: 2, Completed: 150, Failed: 12, Canceled: 8 } ``` *** ## Common tasks > [accordion] Find failed calls > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const response = await fetch( > 'https://blackbox.dasha.ai/api/v1/callresults/search', > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > callStatuses: ['Failed'], > sortField: 'completedTime', > sortDirection: 'Descending', > size: 50 > }) > } > ).then(r => r.json()); > > // Review error messages > response.results.forEach(call => { > console.log(`${call.callId}: ${call.errorMessage}`); > }); > ``` > [accordion] Search by custom field > > Query calls using custom fields in additional data: > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const response = await fetch( > 'https://blackbox.dasha.ai/api/v1/callresults/search', > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > additionalDataFilters: { > 'result.postCallAnalysis.sentiment': 'positive', > 'result.postCallAnalysis.info.age': { 'gte': 25, 'lte': 65 } > }, > size: 100 > }) > } > ).then(r => r.json()); > ``` > [accordion] Get aggregations > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const response = await fetch( > 'https://blackbox.dasha.ai/api/v1/callresults/search', > { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > includeAggregations: true, > aggregationFields: ['result.postCallAnalysis.sentiment'], > size: 0 // Only get aggregations, no results > }) > } > ).then(r => r.json()); > > console.log('Status counts:', response.aggregations?.statusCounts); > console.log('Agent counts:', response.aggregations?.agentCounts); > ``` *** ## Call statuses reference | Status | Description | | - | - | | **Created** | Call created but not yet queued | | **Pending** | Waiting to be queued | | **Queued** | In queue, waiting for resources | | **Running** | Call in progress | | **Completed** | Successfully finished | | **Failed** | Error occurred | | **Canceled** | Manually canceled or deadline exceeded | *** ## What's next > [card] [Call Inspector](/docs/test/call-inspector) > > Deep dive into individual calls > [card] [Conversations](/docs/introduction/conversations) > > Understand call transcripts > [card] [Concurrency Monitoring](/docs/monitor/concurrency-monitoring) > > Monitor active calls # Monitor Concurrent Call Capacity Source: https://blackbox.dasha.ai/docs/monitor/concurrency-monitoring Monitor concurrent call capacity, track utilization metrics, set up alerts, and plan scaling strategies for optimal voice AI performance. Know how many calls you can handle simultaneously. Monitor utilization in real time, set up alerts for capacity limits, and scale before calls start queueing. **What you'll learn:** Concurrency metrics, utilization thresholds, queue status, alerting setup, and scaling strategies. > [!NOTE] > > Screenshots may differ from current UI version. ## Understanding concurrency **Concurrency** is the number of simultaneous active calls across your organization or agent. Each active call consumes one slot from your concurrency limit until it completes. ### Key metrics | Metric | Definition | Calculation | | - | - | - | | **Active calls** | Calls currently in progress (Running status) | Count of calls where status = Running | | **Concurrency limit** | Maximum simultaneous calls allowed | Set by subscription tier | | **Utilization** | Percentage of limit currently in use | (Active Calls / Limit) × 100 | | **Queue depth** | Calls waiting for available slots | Count of calls where status = Queued | | **Available capacity** | Slots available for new calls | Limit - Active Calls | > [accordion] Utilization thresholds > > **Definition:** Percentage of concurrency capacity currently in use. > > **Calculation method:** > > ``` > Utilization % = (Active Calls / Concurrency Limit) × 100 > ``` **Performance thresholds:** | Utilization | Status | Interpretation | Recommended action | | - | - | - | - | | **0-70%** | Healthy | Normal operations, ample headroom | Monitor normally | | **70-85%** | Elevated | Approaching capacity | Monitor closely, plan scaling | | **85-95%** | Warning | Limited headroom for spikes | Consider scaling soon | | **95-100%** | Critical | Near or at capacity | Calls may queue, scale immediately | | **100%** | At limit | All slots in use | New calls queue until slots free | > [!WARNING] > > Running at 100% utilization for extended periods degrades service quality. Calls queue longer, deadlines may expire, and inbound callers may abandon. Maintain at least 15-20% buffer capacity above typical peak usage. *** ## View concurrency status > [tab] Dashboard > > 1. Navigate to **Dashboard** home page > 2. View **Active Calls** section showing current utilization > 3. Color indicators: > * 🟢 Green: Under 70% utilization > * 🟡 Yellow: 70-90% utilization > * 🔴 Red: Over 90% utilization > [tab] API > > Get current concurrency status: > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const { active, concurrency } = await fetch( > 'https://blackbox.dasha.ai/api/v1/misc/concurrency', > { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } > ).then(r => r.json()); > > const utilization = (active / concurrency * 100).toFixed(1); > > console.log(`Active: ${active}/${concurrency} (${utilization}%)`); > ``` > [accordion] Queue status > > Monitor calls waiting in queue: > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > // Get queued calls count > const queueResponse = await fetch( > 'https://blackbox.dasha.ai/api/v1/calls?status=Queued&take=1', > { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } > ).then(r => r.json()); > > console.log(`Calls waiting in queue: ${queueResponse.totalCount}`); > ``` > [accordion] Combined status check > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > async function getConcurrencyStatus() { > const [concurrencyData, queued, pending] = await Promise.all([ > fetch('https://blackbox.dasha.ai/api/v1/misc/concurrency', { > headers: { 'Authorization': 'Bearer YOUR_API_KEY' } > }).then(r => r.json()), > > fetch('https://blackbox.dasha.ai/api/v1/calls?status=Queued&take=1', { > headers: { 'Authorization': 'Bearer YOUR_API_KEY' } > }).then(r => r.json()), > > fetch('https://blackbox.dasha.ai/api/v1/calls?status=Pending&take=1', { > headers: { 'Authorization': 'Bearer YOUR_API_KEY' } > }).then(r => r.json()) > ]); > > const { active, concurrency } = concurrencyData; > > return { > activeCalls: active, > queuedCalls: queued.totalCount, > pendingCalls: pending.totalCount, > concurrencyLimit: concurrency, > utilization: ((active / concurrency) * 100).toFixed(1) + '%', > availableSlots: Math.max(0, concurrency - active) > }; > } > > const status = await getConcurrencyStatus(); > console.log('Concurrency Status:', status); > ``` *** ## Concurrency metrics > [accordion] Active calls > > **Definition:** Number of calls currently in Running status (actively connected and processing). > > **Calculation method:** > > ``` > Active Calls = Count of calls where status = 'Running' > ``` **Typical range:** 0 to concurrency limit. **What high values indicate:** * Peak usage periods * Bulk campaign in progress * Long average call durations > [accordion] Queue depth > > **Definition:** Number of calls waiting for an available slot to start processing. > > **Calculation method:** > > ``` > Queue Depth = Count of calls where status IN ('Created', 'Queued', 'Pending') > ``` **Performance thresholds:** | Depth | Status | Interpretation | | - | - | - | | **0** | Optimal | No waiting calls | | **1-10** | Acceptable | Brief waits expected | | **10-50** | Elevated | Monitor for growth | | **50-100** | High | Extended wait times likely | | **> 100** | Critical | Significant delays, scale needed | > [accordion] Wait time > > **Definition:** Time calls spend in queue before processing begins. > > **Estimated calculation:** > > ``` > Estimated Wait Time = (Queue Depth / Active Calls) × Average Call Duration > ``` **What long wait times indicate:** * Insufficient concurrency for volume * Long call durations consuming slots * Bulk campaigns overwhelming capacity *** ## Concurrency limits by plan Limits vary by subscription plan: | Plan | Concurrent Lines | Minutes/Month | | - | - | - | | **Developer** | 1 | 1,000 | | **Growth** | Multiple | Unlimited | > [!TIP] > > Check your specific limits in **Account Settings** → **Billing & Usage**. Contact sales for Growth plan pricing. *** ## What happens at capacity When all concurrency slots are in use: 1. **New calls enter queue** — Status changes to "Queued" 2. **Queue processed by priority** — Higher priority calls processed first 3. **Calls start as slots free** — First queued call gets next available slot 4. **Deadlines enforced** — Calls exceeding deadline are auto-canceled ### Impact on service quality | Metric | At capacity impact | Mitigation | | - | - | - | | **Wait time** | Increases with queue depth | Scale concurrency | | **Deadline expirations** | Queued calls may timeout | Set longer deadlines | | **Inbound abandonment** | Callers may hang up waiting | Reserve capacity for inbound | | **Campaign velocity** | Outbound campaigns slow down | Stagger campaign scheduling | ### Priority during capacity constraints Calls are processed by priority value (lower values processed first), then by deadline: | Priority | Behavior at capacity | | - | - | | **0-1 (Highest)** | Processed first when slots free | | **2-4 (Normal)** | Processed after higher priority calls | | **5+ (Lower)** | May wait longer during high utilization | Within the same priority level, calls closer to their deadline are processed first. *** ## Monitor utilization > [accordion] Continuous monitoring script > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > async function monitorConcurrency(intervalMs = 60000) { > async function check() { > const { active, concurrency } = await fetch( > 'https://blackbox.dasha.ai/api/v1/misc/concurrency', > { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } > ).then(r => r.json()); > > const utilization = (active / concurrency * 100); > const timestamp = new Date().toISOString(); > > console.log(`[${timestamp}] ${active}/${concurrency} (${utilization.toFixed(1)}%)`); > > // Alert on high utilization > if (utilization >= 95) { > console.error('CRITICAL: At capacity limit'); > } else if (utilization >= 85) { > console.warn('WARNING: High utilization - consider scaling'); > } else if (utilization >= 70) { > console.warn('NOTICE: Elevated utilization'); > } > > return { timestamp, active, concurrency, utilization }; > } > > // Initial check > await check(); > > // Continuous monitoring > setInterval(check, intervalMs); > } > > // Monitor every minute > monitorConcurrency(60000); > ``` > [accordion] Per-agent utilization > > Track utilization for specific agents: > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > async function getAgentUtilization(agentId) { > const response = await fetch( > `https://blackbox.dasha.ai/api/v1/calls?agentId=${agentId}&status=Running&take=1`, > { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } > ).then(r => r.json()); > > return { > agentId, > activeCalls: response.totalCount > }; > } > > // Check multiple agents > const agentIds = ['agent-1', 'agent-2', 'agent-3']; > > const agentStats = await Promise.all( > agentIds.map(id => getAgentUtilization(id)) > ); > > console.table(agentStats); > ``` > [accordion] Historical utilization analysis > > Analyze patterns over time: > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > async function analyzeUtilizationHistory() { > // Get recent call results to analyze duration patterns > const results = await fetch( > 'https://blackbox.dasha.ai/api/v1/call-results?take=500', > { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } > ).then(r => r.json()); > > // Group by hour > const byHour = {}; > results.items.forEach(call => { > const hour = new Date(call.createdTime).getHours(); > if (!byHour[hour]) byHour[hour] = { count: 0, totalDuration: 0 }; > byHour[hour].count++; > byHour[hour].totalDuration += call.durationSeconds; > }); > > // Calculate peak hours > const sortedHours = Object.entries(byHour) > .map(([hour, data]) => ({ > hour: parseInt(hour), > callCount: data.count, > avgDuration: (data.totalDuration / data.count / 60).toFixed(1) + ' min' > })) > .sort((a, b) => b.callCount - a.callCount); > > console.log('Peak hours by call volume:'); > console.table(sortedHours.slice(0, 5)); > > return sortedHours; > } > ``` *** ## Set up alerts > [accordion] Polling-based alerting > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > async function capacityAlert(thresholds = { warning: 85, critical: 95 }) { > const { active, concurrency } = await fetch( > 'https://blackbox.dasha.ai/api/v1/misc/concurrency', > { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } > ).then(r => r.json()); > > const utilization = (active / concurrency) * 100; > > if (utilization >= thresholds.critical) { > await sendAlert({ > severity: 'critical', > message: `Concurrency at ${utilization.toFixed(1)}%`, > active, > limit: concurrency, > action: 'Calls are queueing. Consider immediate scaling.' > }); > } else if (utilization >= thresholds.warning) { > await sendAlert({ > severity: 'warning', > message: `Concurrency at ${utilization.toFixed(1)}%`, > active, > limit: concurrency, > action: 'Monitor closely. Plan scaling if trend continues.' > }); > } > } > > // Check every minute > setInterval(() => capacityAlert(), 60000); > ``` > [accordion] Prometheus metrics exporter > > Export metrics for Prometheus monitoring: > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const express = require('express'); > const app = express(); > > app.get('/metrics', async (req, res) => { > const [concurrencyData, queued] = await Promise.all([ > fetch('https://blackbox.dasha.ai/api/v1/misc/concurrency', { > headers: { 'Authorization': 'Bearer YOUR_API_KEY' } > }).then(r => r.json()), > > fetch('https://blackbox.dasha.ai/api/v1/calls?status=Queued&take=1', { > headers: { 'Authorization': 'Bearer YOUR_API_KEY' } > }).then(r => r.json()) > ]); > > const { active, concurrency } = concurrencyData; > > const metrics = ` > # HELP blackbox_concurrency_limit Maximum concurrent calls allowed > # TYPE blackbox_concurrency_limit gauge > blackbox_concurrency_limit ${concurrency} > > # HELP blackbox_active_calls Current number of active calls > # TYPE blackbox_active_calls gauge > blackbox_active_calls ${active} > > # HELP blackbox_queued_calls Current number of queued calls > # TYPE blackbox_queued_calls gauge > blackbox_queued_calls ${queued.totalCount} > > # HELP blackbox_utilization_percent Current utilization percentage > # TYPE blackbox_utilization_percent gauge > blackbox_utilization_percent ${(active / concurrency * 100).toFixed(2)} > `.trim(); > > res.set('Content-Type', 'text/plain').send(metrics); > }); > > app.listen(9090, () => { > console.log('Prometheus metrics available at http://localhost:9090/metrics'); > }); > ``` ### Alert thresholds reference | Condition | Threshold | Severity | Response | | - | - | - | - | | Utilization spike | > 95% | Critical | Immediate investigation | | Sustained high | > 85% for 15 min | Warning | Plan scaling | | Queue buildup | > 50 calls | Warning | Review call durations | | Unexpected drop | \< 10% of normal | Info | Verify system health | *** ## Scaling strategies ### Increase concurrency limits **Upgrade subscription tier:** 1. Navigate to **Account Settings** → **Billing** 2. Click **Upgrade Plan** 3. Select tier with higher concurrency 4. New limits active immediately **Enterprise custom limits:** Contact support for limits above standard tiers. > [accordion] Multi-agent load distribution > > Distribute load across multiple agents: > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > async function selectLeastLoadedAgent(agentIds) { > const loads = await Promise.all( > agentIds.map(async (agentId) => { > const response = await fetch( > `https://blackbox.dasha.ai/api/v1/calls?agentId=${agentId}&status=Running&take=1`, > { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } } > ).then(r => r.json()); > > return { > agentId, > activeCalls: response.totalCount > }; > }) > ); > > // Sort by active calls (ascending) > loads.sort((a, b) => a.activeCalls - b.activeCalls); > > console.log('Agent loads:', loads); > return loads[0].agentId; // Return least loaded agent > } > > // Use when enqueuing calls > const agents = ['agent-support', 'agent-sales', 'agent-general']; > const targetAgent = await selectLeastLoadedAgent(agents); > > await fetch(`https://blackbox.dasha.ai/api/v1/calls/enqueue/${targetAgent}`, { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > endpoint: '+1-555-123-4567' > }) > }); > ``` > [accordion] Optimize call duration > > Shorter calls free slots faster: > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > // Agent configuration for efficient calls > { > "config": { > "llmConfig": { > "temperature": 0.6 // Focused outputs > }, > "features": { > "maxCallDuration": 300, // 5 minute maximum > "silenceTimeout": 15 // End on extended silence > } > } > } > ``` > [accordion] Stagger bulk campaigns > > Avoid overwhelming capacity with large campaigns: > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > async function staggeredEnqueue(agentId, calls, options = {}) { > const { batchSize = 50, delayMs = 5 * 60 * 1000 } = options; > > for (let i = 0; i < calls.length; i += batchSize) { > const batch = calls.slice(i, i + batchSize); > > // Enqueue batch > await fetch(`https://blackbox.dasha.ai/api/v1/calls/enqueue/${agentId}/batch`, { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify(batch) > }); > > console.log(`Enqueued batch ${Math.floor(i / batchSize) + 1}: ${batch.length} calls`); > > // Wait before next batch (unless last batch) > if (i + batchSize < calls.length) { > console.log(`Waiting ${delayMs / 1000}s before next batch...`); > await new Promise(resolve => setTimeout(resolve, delayMs)); > } > } > } > > // Example: Stagger 500 calls in batches of 50, 5 minutes apart > const callList = Array.from({ length: 500 }, (_, i) => ({ > endpoint: `+1-555-${String(i).padStart(7, '0')}` > })); > > await staggeredEnqueue('agent-campaign', callList, { > batchSize: 50, > delayMs: 5 * 60 * 1000 > }); > ``` *** ## Best practices ### Capacity planning | Practice | Recommendation | | - | - | | **Buffer capacity** | Maintain 20% headroom above typical peak | | **Monitor trends** | Track daily and weekly utilization patterns | | **Plan ahead** | Scale before campaigns, not during | | **Test limits** | Verify behavior at capacity before production | ### Load management | Practice | Recommendation | | - | - | | **Priority tiers** | Reserve high priority for time-sensitive calls | | **Stagger campaigns** | Batch large campaigns with delays | | **Balance agents** | Distribute load across multiple agents | | **Monitor duration** | Investigate unusually long calls | ### Alert configuration | Alert | Threshold | Check interval | | - | - | - | | **Critical capacity** | > 95% utilization | Every 1 minute | | **High utilization** | > 85% for 15 minutes | Every 5 minutes | | **Queue buildup** | > 50 queued calls | Every 2 minutes | | **Duration anomaly** | Calls > 2× average duration | Every 10 minutes | *** ## Troubleshooting > [accordion] Calls stuck in queue > > **Symptoms:** Calls remain in Queued status for extended periods. > > **Causes:** > > * All concurrency slots in use > * Agent disabled or outside business hours > * Long-running calls consuming all slots > > **Solutions:** > > 1. Check current utilization — verify you're at capacity > 2. Review active call durations — identify unusually long calls > 3. Verify agent is enabled and within schedule > 4. Increase concurrency limit or add agents > 5. Check for stuck calls in Running status that should have ended > [accordion] Unexpected utilization spikes > > **Symptoms:** Sudden increase in active calls not matching expected volume. > > **Causes:** > > * Bulk campaign started > * Multiple systems scheduling simultaneously > * Webhook retry storms > * Inbound call surge > > **Solutions:** > > 1. Review recent call scheduling patterns > 2. Check if bulk campaigns started unintentionally > 3. Implement rate limiting in scheduling systems > 4. Stagger scheduled calls with delays > 5. Add capacity checks before scheduling > [accordion] Frequently hitting limits > > **Symptoms:** Regularly reaching 100% utilization. > > **Causes:** > > * Insufficient capacity for volume > * Long average call durations > * Poor load distribution > > **Solutions:** > > 1. Upgrade to higher tier for more concurrency > 2. Add agents for load distribution > 3. Optimize prompts for shorter conversations > 4. Set maximum call duration limits > 5. Implement application-level rate limiting > [accordion] Uneven agent utilization > > **Symptoms:** Some agents at capacity while others idle. > > **Causes:** > > * Fixed agent assignment > * Uneven scheduling distribution > * Different agent schedules > > **Solutions:** > > 1. Implement load balancing when scheduling > 2. Route calls to least-loaded agent > 3. Align agent schedules with expected volume > 4. Consider using agent pools for similar use cases *** ## What's next > [card] [Call History](/docs/monitor/call-history) > > Manage scheduled call queue > [card] [Outbound Calls](/docs/deploy/outbound-calls) > > Schedule outbound campaigns # Analyze Completed Calls Source: https://blackbox.dasha.ai/docs/test/call-inspector Access the Call Inspector to analyze transcripts, audio recordings, LLM interactions, tool executions, and performance metrics for any completed call. Analyze completed calls in detail. The Call Inspector shows transcripts, audio recordings, timeline events, LLM prompts/responses, tool executions, and latency breakdowns for every conversation. **What you'll learn:** Accessing the inspector, understanding sections, and navigating to detailed analysis. > [!NOTE] > > Screenshots may differ from current UI version. *** ## Access the Call Inspector > [tab] From Calls page > > 1. Go to **Calls** in the sidebar > 2. Select the **Past Calls** tab > 3. Find your call in the list > 4. Click the **Inspect** button > 5. Inspector opens in a new tab > [tab] From Dashboard > > 1. View the **Recent Calls** section on your dashboard > 2. Click any completed call row > 3. Inspector opens in a new tab > [tab] From Agent details > > 1. Go to **Agents** → Select your agent > 2. Scroll to the call history section > 3. Click **Inspect** for any completed call > [tab] From API > > > [accordion] API example: Get inspector URL > > > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > > // Get inspector URL from call results > > const results = await fetch('https://blackbox.dasha.ai/api/v1/callresults/search', { > > method: 'POST', > > headers: { > > 'Authorization': 'Bearer YOUR_API_KEY', > > 'Content-Type': 'application/json' > > }, > > body: JSON.stringify({ > > callIds: ['your-call-id'] > > }) > > }).then(r => r.json()); > > > > console.log('Inspector URL:', results.results[0].inspectorUrl); > > ``` **The Call Inspector is only available for completed calls.** Calls in Pending, Queued, or Running status don't have inspector data until they complete. *** ## Inspector sections | Section | Contents | Use case | Learn more | | - | - | - | - | | **Overview** | Call metadata, status, duration | Quick context | Below | | **Transcript** | Full conversation with timestamps | Conversation review | — | | **Audio** | Recording playback | Voice quality | [Common Issues](/docs/troubleshooting/common-issues) | | **LLM** | Prompts, responses, tokens | Model debugging | [Common Issues](/docs/troubleshooting/common-issues) | | **Tools** | Function calls and responses | Integration debugging | [Common Issues](/docs/troubleshooting/common-issues) | | **Timeline** | Chronological events | Latency analysis | — | *** ## Call overview The inspector header displays key call metadata at a glance. ### Header information | Field | Description | API field | | - | - | - | | **Call ID** | Unique identifier (UUID) | `callId` | | **Status** | Completed, Failed, or Canceled | `callStatus` | | **Agent** | Agent ID and name | `agentId` | | **Duration** | Total conversation length | `durationSeconds` | | **Endpoint** | Phone number or "web" | `endpoint` | | **Call Type** | Connection type | `callType` | ### Call type values | Type | API value | Description | | - | - | - | | Inbound phone | `InboundAudio` | Incoming phone call | | Outbound phone | `OutboundAudio` | Outgoing phone call | | Web voice | `WebCall` | Browser WebRTC call | | Web chat | `Chat` | Text conversation | ### Timestamps | Timestamp | Meaning | | - | - | | **Created** | When the call was scheduled | | **Started** | When the conversation began | | **Completed** | When the call ended | ### Custom data Any `additionalData` passed during call creation appears as formatted JSON: > [accordion] Example: Call overview with custom data > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "callId": "660e8400-e29b-41d4-a716-446655440001", > "status": "Completed", > "duration": "00:03:45", > "additionalData": { > "customerId": "cust_789", > "orderNumber": "ORD-12345" > } > } > ``` *** ## Quick analysis ### Check conversation quality 1. Open the **Transcript** section 2. Scan for red flags: repetition, off-topic responses, user frustration 3. Listen to audio for voice quality issues 4. Review LLM logs if responses seem wrong → [Common Issues](/docs/troubleshooting/common-issues) ### Check performance 1. Open the **Timeline** section 2. Look at latency breakdown: STT, LLM, TTS 3. Identify the slowest component 4. Compare against targets (under 2s total) → [Common Issues](/docs/troubleshooting/common-issues) ### Debug failed calls 1. Check **Status** in the header 2. Look for error messages in system events 3. Review LLM logs for API errors 4. Check tool executions for failures → [Common Issues](/docs/troubleshooting/common-issues) *** ## Best practices ### During testing * Review 5-10 test calls before enabling an agent for production * Verify all conversation paths work as expected * Check that tool executions succeed * Confirm latencies are within acceptable ranges ### In production * Sample 5-10% of calls randomly for quality review * Review all failed calls within 24 hours * Track performance trends over time * Monitor tool success rates ### Data privacy * Redact PII before sharing transcripts externally * Comply with call recording consent laws in your jurisdiction * Implement data retention policies * Secure access to recordings with proper authentication *** ## What's next > [card] [Call History](/docs/monitor/call-history) > > View and filter past calls > [card] [Troubleshooting](/docs/troubleshooting/common-issues) > > Common issues and solutions > [card] [Common Issues](/docs/troubleshooting/common-issues) > > Solutions for frequent problems > [card] [Concurrency Monitoring](/docs/monitor/concurrency-monitoring) > > Monitor active calls and capacity # Test Agents in the Browser Source: https://blackbox.dasha.ai/docs/test/dashboard-testing Test voice agents in the browser without phone calls. Run voice or chat conversations with real-time transcripts and validate behavior before deployment. Test your agent in the browser without phone calls. Click **Test** to start voice or chat conversations with real-time transcripts. **What you'll learn:** Starting test conversations, choosing test modes, and reviewing results. *** ## Start a test conversation **1. Open your agent** Go to **Agents** in the sidebar and select your agent. **2. Click Test** Click **Test** in the Quick Actions panel. **3. Choose your mode** Select **Voice**, **Chat**, or **Phone** from the mode selector. **4. Have a conversation** Speak or type to interact with your agent. The transcript displays in real time. **5. End the call** Click **End Call** when finished. Call results become available for review. *** ## Test modes | Mode | Description | Best for | | - | - | - | | **Voice** | Real-time voice conversation using STT and TTS | Final validation, voice quality, latency testing | | **Chat** | Text-based conversation with instant responses | Prompt iteration, debugging, quick scenarios | | **Phone** | Call a real phone number | End-to-end telephony testing | *** ## Test controls | Control | Function | | - | - | | **Mode selector** | Switch between Voice, Chat, and Phone modes | | **Text input** | Type messages (chat mode) | | **End Call** | Stop the current conversation | *** ## Reviewing results After ending a test call, view the call result: **1. End the call** Click **End Call** when finished. **2. View the result** Click **Show** on the Result indicator in the dev toolbar. **3. Export for debugging** **Copy** to clipboard or **Download** as JSON. **Result structure:** > [accordion] Example: Result structure > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "callId": "660e8400-e29b-41d4-a716-446655440001", > "status": "Completed", > "agentId": "agent-abc123", > "endpoint": "web", > "duration": "00:02:15", > "inspectorUrl": "https://inspector.blackbox.ai/..." > } > ``` For detailed analysis, open the [Call Inspector](/docs/test/call-inspector) using the `inspectorUrl`. *** ## Pre-deployment checklist > [tab] Voice quality > > * [ ] Voice sounds natural and professional > * [ ] Pronunciation of brand terms is correct > * [ ] Speed is comfortable (not rushed or slow) > * [ ] Multi-turn conversations flow smoothly > [tab] Response quality > > * [ ] 10+ common questions tested and verified > * [ ] Responses are accurate and on-topic > * [ ] Tone matches brand voice > * [ ] Edge cases handled gracefully > [tab] Integrations > > * [ ] All configured tools execute successfully > * [ ] Webhook endpoints return HTTP 200 > * [ ] Tool parameters extracted correctly > [tab] Performance > > * [ ] Response latency under 2 seconds > * [ ] STT transcription accuracy above 90% > * [ ] Consistent behavior across 5+ test runs *** ## Troubleshooting > [accordion] Test won't start > > **Possible causes:** Incomplete configuration, network issues, unsaved agent > > **Solutions:** > > 1. Verify all required fields are completed (LLM config, TTS config, STT config) > 2. Check that API keys are valid and have necessary permissions > 3. Save the agent before attempting to test > 4. Clear browser cache and reload the page > [accordion] Microphone not working > > **Possible causes:** Permission denied, wrong device selected > > **Solutions:** > > 1. Click the lock icon in the address bar → Allow microphone access > 2. Check system privacy settings > 3. Try a different browser (Chrome works best) > [accordion] Agent doesn't respond > > **Possible causes:** LLM configuration error, prompt issue > > **Solutions:** > > 1. Verify the LLM API key is valid > 2. Check the model name is correct > 3. Test with a minimal prompt: "You are a helpful assistant." *** ## API testing Schedule test calls programmatically for automation: > [accordion] API example: Schedule test call > > ```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: "web", > priority: 7, > callDeadline: new Date(Date.now() + 600000).toISOString(), > additionalData: { > testSession: true, > testScenario: "basic-greeting" > } > }) > }); > > const call = await response.json(); > console.log(`Test call scheduled: ${call.callId}`); > ``` *** ## What's next > [card] [Call Inspector](/docs/test/call-inspector) > > Analyze completed calls > [card] [Troubleshooting](/docs/troubleshooting/common-issues) > > Common issues and solutions # Validate Your Agent Before Deployment Source: https://blackbox.dasha.ai/docs/test/testing-overview Test voice AI agents before deployment using browser testing, API calls, and debugging tools. Validate conversation quality, voice experience, and integrations. Test systematically before going live. This guide covers testing workflow and checklists. **What you'll learn:** Testing workflow, environments, and pre-launch checklists. > [!WARNING] > > Enabled agents receive live calls immediately. Test with the agent disabled before enabling. *** ## Testing workflow ### Phase 1: Configuration **1. Create disabled agent** Set `isEnabled: false` and configure LLM, voice, and system prompt **2. Preview voice** Compare voices, adjust speed (0.9-1.1x recommended) **3. Test prompts** Use chat mode to iterate on prompts quickly **4. Test webhooks** Verify endpoints return HTTP 200 ### Phase 2: Conversation testing **1. Test happy paths** Run ideal conversation flows **2. Test edge cases** Try unclear input, interruptions, out-of-scope requests **3. Test errors** Disconnect webhooks, test timeout handling **4. Voice quality** Switch to voice mode, check clarity and latency ### Phase 3: Integration testing **1. Test tools** Trigger each tool, verify parameter extraction **2. Test MCP connections** Validate server connectivity **3. Test schedule** Verify business hours behavior **4. Test concurrency** Schedule multiple calls via API ### Phase 4: Pre-production **1. End-to-end voice test** Test all conversation branches **2. Review metrics** Target: \<2 seconds latency **3. Team review** Gather feedback on conversation quality **4. Enable for production** Monitor first 10-20 calls in Call Inspector *** ## Checklists ### Essential (every agent) * [ ] Voice sounds natural and clear * [ ] Core flows complete successfully * [ ] System prompt instructions followed * [ ] 10+ scenarios validated * [ ] Error handling tested ### Advanced (complex agents) * [ ] All tools execute successfully * [ ] Webhooks deliver and retry * [ ] MCP servers functional * [ ] Multi-turn coherence maintained ### Edge cases (production-critical) * [ ] Long silences handled (5+ seconds) * [ ] Background noise tolerated * [ ] Out-of-scope requests declined gracefully *** ## What's next > [card] [Dashboard Testing](/docs/test/dashboard-testing) > > Test agents in the browser > [card] [Call Inspector](/docs/test/call-inspector) > > Analyze completed calls in detail # Fix Common Agent and API Problems Source: https://blackbox.dasha.ai/docs/troubleshooting/common-issues Quick solutions for the most common Dasha BlackBox problems: agent issues, API errors, webhooks, and voice quality Fix common Dasha BlackBox problems quickly. Find your symptom, identify the cause, apply the solution. *** ## Quick Diagnosis | Symptom | Likely Cause | Solution | | - | - | - | | Agent enabled but calls fail | Phone not configured | [Agent Not Responding](#agent-not-responding) | | HTTP 401 errors | Invalid/expired API key | [Authentication Failures](#authentication-failures) | | Webhooks not received | URL not accessible | [Webhook Failures](#webhook-delivery-failures) | | "Concurrent limit exceeded" | Too many active calls | [Concurrent Limits](#concurrent-call-limit-exceeded) | | Tool calls failing | Webhook timeout or schema mismatch | [Tool Failures](#tool-calling-failures) | | Robotic/choppy voice | TTS provider or network | [Voice Quality](#voice-quality-issues) | | Agent mishears user | Language or noise settings | [ASR Errors](#asr-transcription-errors) | | Slow/irrelevant responses | Model or prompt issues | [LLM Issues](#llm-response-issues) | | Recording not found | Not enabled or still processing | [Recording Issues](#call-recording-not-available) | *** ## Agent Not Responding **Symptoms**: Agent shows "Enabled" but calls don't connect, go to voicemail, or fail immediately. ### Quick Checks | Check | How to Verify | Fix | | - | - | - | | Agent status | Dashboard → Agent → Status badge | Enable if Disabled | | Phone number | Agent config → `phoneNumber` field | Assign E.164 format number (+12025551234) | | Required fields | System prompt, LLM, TTS, STT configured | Fill missing fields | > [accordion] Verify via API > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const agent = await fetch(`https://blackbox.dasha.ai/api/v1/agents/${agentId}`, { > headers: { 'Authorization': 'Bearer YOUR_API_KEY' } > }).then(r => r.json()); > > console.log('Enabled:', agent.isEnabled); > console.log('Outbound SIP:', agent.config.outboundSipConfig?.fromUser); > console.log('Inbound SIP URI:', agent.inboundSipConfig?.sipUri); > ``` ### Debug Steps 1. **Test from dashboard** — If dashboard test works but live calls fail, issue is phone/integration setup 2. **Check call logs** — Dashboard → Calls → Filter by agent → Review failed calls 3. **Verify webhooks** — Ensure webhook URLs are publicly accessible (not localhost) *** ## Authentication Failures **Symptoms**: HTTP 401 Unauthorized, "Invalid API key", "Token expired" ### Common Causes | Error | Cause | Fix | | - | - | - | | "Invalid API key" | Key doesn't exist or revoked | Generate new key in dashboard | | "Token expired" | Web integration token expired | Regenerate via API or dashboard | | 401 only in production | Using wrong environment key | Check environment variables | | 401 from specific origins | Origin not whitelisted | Add origin to web integration | > [accordion] Verify API Key > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > // Test key validity > const response = await fetch('https://blackbox.dasha.ai/api/v1/agents', { > headers: { 'Authorization': 'Bearer YOUR_API_KEY' } > }); > console.log('Valid:', response.status !== 401); > ``` > [accordion] Fix Origin Restrictions > > For web integrations, add all required origins: > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > await fetch('https://blackbox.dasha.ai/api/v1/web-integrations/YOUR_INTEGRATION_ID', { > method: 'PATCH', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > allowedOrigins: ['https://yourapp.com', 'http://localhost:3000'] > }) > }); > ``` *** ## Webhook Delivery Failures **Symptoms**: Webhooks not received, timeout errors, SSL certificate errors ### Common Causes | Error | Cause | Fix | | - | - | - | | Connection timeout | Endpoint too slow | Respond immediately, process async | | Connection refused | URL not accessible | Use public URL, not localhost | | SSL certificate error | Self-signed or expired cert | Use Let's Encrypt or valid CA | | DNS resolution failed | Domain doesn't resolve | Check DNS configuration | ### Timeout Requirements | Webhook Type | Default Timeout | Max Configurable | | - | - | - | | StartWebHookPayload | 10 seconds | 300 seconds | | ToolWebHookPayload | 5 seconds | 300 seconds | | Other webhooks | 30 seconds | — | > [accordion] Fix Slow Endpoints > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > // Respond immediately, process async > app.post('/webhook', (req, res) => { > res.status(200).json({ received: true }); > > setImmediate(async () => { > await processWebhook(req.body); > }); > }); > ``` > [accordion] Test Webhook > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const result = await fetch('https://blackbox.dasha.ai/api/v1/webhooks/test', { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > webHook: { url: 'https://your-server.com/webhook' }, > webhookType: 'CompletedWebHookPayload' > }) > }).then(r => r.json()); > > console.log('Success:', result.success, 'Time:', result.timeTaken, 'ms'); > ``` > [accordion] Local Development > > Use ngrok to expose local endpoints: > > ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} > ngrok http 3000 > # Use the https://xxx.ngrok.io URL in webhook configuration > ``` *** ## Concurrent Call Limit Exceeded **Symptoms**: "Concurrent call limit exceeded", HTTP 429 with "Too many active calls" ### Limits by Plan | Plan | Concurrent Lines | Minutes/Month | | - | - | - | | Developer (Free) | 1 | 1,000 | | Growth | 30 (at start) | Contact sales | | Enterprise | Custom | Custom | > [!NOTE] > > Growth and Enterprise plan limits can be adjusted based on your needs. Contact [support@dasha.ai](mailto:support@dasha.ai) to discuss your requirements. > [accordion] Check Current Usage > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const concurrency = await fetch('https://blackbox.dasha.ai/api/v1/misc/concurrency', { > headers: { 'Authorization': 'Bearer YOUR_API_KEY' } > }).then(r => r.json()); > > console.log('Active:', concurrency.active, '/', concurrency.concurrency); > ``` ### Solutions 1. **Wait for slots** — Poll active calls, schedule when capacity available 2. **Stagger scheduling** — Space calls over time instead of bulk scheduling 3. **Upgrade tier** — Contact [support@dasha.ai](mailto:support@dasha.ai) for higher limits *** ## Tool Calling Failures **Symptoms**: Agent says "I'm unable to complete that request", tool webhook errors, missing parameters ### Common Causes | Error | Cause | Fix | | - | - | - | | Timeout | Webhook takes over 10 seconds | Optimize endpoint, respond faster | | Invalid response | Response not JSON | Return valid JSON object | | Missing parameters | Schema mismatch | Check tool schema in agent config | | Agent doesn't use tool | Prompt unclear | Add explicit tool usage instructions | > [accordion] Verify Tool Configuration > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const agent = await fetch('https://blackbox.dasha.ai/api/v1/agents/YOUR_AGENT_ID', { > headers: { 'Authorization': 'Bearer YOUR_API_KEY' } > }).then(r => r.json()); > > console.log('Tools:', agent.config.tools?.map(t => t.name)); > agent.config.tools?.forEach(t => { > console.log(` ${t.name} webhook: ${t.webhook?.url}`); > }); > ``` > [accordion] Fix Prompt for Tool Usage > > Add explicit instructions to system prompt: > > ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} > ALWAYS use the check_availability tool before confirming a booking. > NEVER guess about availability - always check first. > ``` *** ## Voice Quality Issues **Symptoms**: Robotic voice, choppy audio, audio dropouts ### Quick Fixes | Issue | Try This | | - | - | | Robotic voice | Switch TTS provider or try different voice | | Too fast/slow | Adjust `speed` (0.8-1.2 range) | | Choppy audio | Check network quality, use wired connection | | Inconsistent quality | Try different voice ID | ### Provider Comparison | Provider | Quality | Best For | | - | - | - | | Cartesia | Good | Emotions, wide speed range | | ElevenLabs | Excellent | Premium quality, voice cloning | | Inworld | Very Good | Character voices, gaming | > [accordion] Switch Provider > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > await fetch('https://blackbox.dasha.ai/api/v1/agents/YOUR_AGENT_ID', { > method: 'PATCH', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > config: { ttsConfig: { provider: 'Cartesia', speed: 1.0 } } > }) > }); > ``` *** ## ASR Transcription Errors **Symptoms**: Agent responds to wrong words, user repeats themselves, numbers transcribed incorrectly ### Quick Fixes | Issue | Fix | | - | - | | Wrong language | Set correct `primaryLanguage` (e.g., `en-US`) | | Background noise | Enable `ambientNoise: true` in features | | Frequent mishearing | Add confirmation prompts to system prompt | > [accordion] Enable Noise Suppression > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > await fetch('https://blackbox.dasha.ai/api/v1/agents/YOUR_AGENT_ID', { > method: 'PATCH', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > config: { features: { ambientNoise: true } } > }) > }); > ``` > [accordion] Add Confirmation to Prompt > > ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} > ALWAYS confirm critical information by repeating it back: > - Names: "Your name is [name]. Is that correct?" > - Numbers: "That's [number]. Right?" > ``` *** ## LLM Response Issues **Symptoms**: Slow responses (over 5 seconds), irrelevant answers, hallucinations, repetition ### Quick Fixes | Issue | Fix | | - | - | | Too slow | Use faster model (Reflex-1, GPT-4.1 Mini) | | Irrelevant responses | Improve system prompt clarity | | Hallucinations | Lower temperature (0.3-0.5) | | Repetitive | Adjust presence/frequency penalties | ### Model Comparison | Model | Speed | Intelligence | Cost | | - | - | - | - | | Reflex-1 | Very Fast | Good | High | | GPT-4.1 Mini | Fast | Good | Low | | Claude 3.5 Sonnet | Fast | Excellent | Medium | | Gemini 2.5 Flash | Very Fast | Good | Low | | GPT-4 | Medium | Excellent | Medium | > [accordion] Adjust Settings > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > await fetch('https://blackbox.dasha.ai/api/v1/agents/YOUR_AGENT_ID', { > method: 'PATCH', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > config: { > llmConfig: { > model: 'gpt-4.1-mini', > temperature: 0.5 > } > } > }) > }); > ``` *** ## Call Recording Not Available **Symptoms**: "Recording not found", null recordingId, some calls have recordings but others don't ### Quick Checks | Issue | Fix | | - | - | | Recording disabled | Enable `recordingEnabled: true` in agent features | | Just completed | Wait 1-2 minutes for processing | | 404 on download | Use correct endpoint: `/calls/media/{recordingId}` | > [accordion] Enable Recording > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > await fetch('https://blackbox.dasha.ai/api/v1/agents/YOUR_AGENT_ID', { > method: 'PATCH', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > config: { features: { recordingEnabled: true } } > }) > }); > ``` > [accordion] Check Recording Status > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const call = await fetch('https://blackbox.dasha.ai/api/v1/calls/YOUR_CALL_ID', { > headers: { 'Authorization': 'Bearer YOUR_API_KEY' } > }).then(r => r.json()); > > console.log('Recording ID:', call.recordingId); > // If null and call is Completed, wait and retry > ``` *** ## Dashboard Loading Issues **Symptoms**: Blank screen, infinite spinner, 403/401 errors ### Quick Fixes | Issue | Fix | | - | - | | Blank screen | Clear cache and cookies, try incognito | | 401/403 errors | Log out, clear cookies, log back in | | Works in incognito | Disable browser extensions | | Still broken | Check [status.dasha.ai](https://status.dasha.ai) | *** ## When to Contact Support Email **[support@dasha.ai](mailto:support@dasha.ai)** when: * Service unavailable for over 15 minutes * Data loss or security concerns * Tried all troubleshooting steps without resolution * Need account-level changes (tier upgrades, custom limits) **Include in your email**: * Agent ID and Call ID (if applicable) * Error messages (exact text) * Steps already tried * Timestamp when issue occurred *** ## Related Resources * [Dashboard Testing](/docs/test/dashboard-testing) — Test agents in the browser * [Call Inspector](/docs/test/call-inspector) — Deep call analysis * [Webhooks Overview](/docs/webhooks-and-events/webhooks-overview) — Webhook configuration and security * [Production Checklist](/docs/deploy/production-checklist) — Pre-launch validation # Set Up Webhook Endpoints Source: https://blackbox.dasha.ai/docs/webhooks-and-events/configuring-webhooks Configure webhook URLs, authentication headers, and event types through the dashboard or API. Point Dasha BlackBox at your endpoint, add authentication headers, and receive HTTP POST requests for call events. **What you'll learn:** Dashboard and API configuration, URL requirements. *** ## Quick setup **1. Navigate to webhooks** Agent → **Settings** → **Webhooks** **2. Enter URL** Must be HTTPS and publicly accessible **3. Add headers** Bearer tokens, API keys for authentication **4. Insert call data (optional)** Click **`{ }`** in the URL or a header value to insert a variable such as `{{callAdditionalData.orderId}}` **5. Test** Use the test button to verify HTTP 200 response *** ## URL requirements * **HTTPS recommended** — Use HTTPS for security * **Publicly accessible** — No localhost or private IPs * **Response under 10 seconds** — Use async processing For local development, use [ngrok](https://ngrok.com): > [accordion] Example: Local development with ngrok > > ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} > ngrok http 3000 > # Use https://xxx.ngrok.io/webhook > ``` *** ## Use call data in the request The webhook URL and header values accept variables. Dasha BlackBox replaces them with values from the call before it sends the request: | Field | Example | | - | - | | Webhook URL | `https://api.example.com/orders/{{callAdditionalData.orderId}}/result` | | Header value | `X-Tenant: {{agentAdditionalData.tenant}}` | Open **Advanced request settings** to change the HTTP method, add query parameters or change the request body. A webhook without variables or advanced settings is sent exactly as before. > [card] [Request Templating](/docs/webhooks-and-events/webhook-request-templating) > > All variables, rendering rules, advanced settings and API reference *** ## Response requirements | Status | Meaning | Retry? | | - | - | - | | 2xx | Success | No | | 4xx | Client error | No | | 5xx | Server error | Yes | | Timeout | No response | Yes | **Best practice**: Respond immediately, process asynchronously. *** ## Checklist * [ ] URL publicly accessible * [ ] Response time under 10 seconds * [ ] Idempotency handling implemented *** ## What's next > [card] [Request Templating](/docs/webhooks-and-events/webhook-request-templating) > > Call data in URLs, headers and bodies > [card] [Webhook Events](/docs/webhooks-and-events/webhook-events) > > Event types and payloads > [card] [Testing Webhooks](/docs/webhooks-and-events/testing-webhooks) > > Comprehensive testing guide # Test Webhook Endpoints Before Going Live Source: https://blackbox.dasha.ai/docs/webhooks-and-events/testing-webhooks Test webhook endpoints locally with ngrok, validate payloads, and verify security before production deployment. Verify your webhook integration works before going live. Test endpoints locally, simulate events, and validate payloads. **What you'll learn:** Local testing with ngrok, API test endpoint, payload validation, and debugging techniques. ## Testing Methods | Method | Best For | | - | - | | **Dashboard Test** | Quick validation | | **webhook.site** | Inspecting payloads without server | | **ngrok** | Full integration testing with local server | *** > [accordion] API Test Endpoint > > Send test webhooks programmatically: > > ```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://your-server.com/webhook', > headers: { 'Authorization': 'Bearer your-secret' } > }, > webhookType: 'CompletedWebHookPayload', > callAdditionalData: { userId: 'test-123' } > }) > }); > > const result = await response.json(); > console.log('Success:', result.success); > console.log('HTTP Status:', result.httpStatus); > console.log('Time:', result.timeTaken, 'ms'); > ``` > [accordion] Example: Test webhook response > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "success": true, > "httpStatus": 200, > "responseData": { "received": true }, > "timeTaken": 245 > } > ``` *** ## Testing webhooks that use call data A webhook that contains variables such as `{{callAdditionalData.orderId}}` needs stand-in values, because that data exists only on a real call. * **Dashboard:** fill in **Test values for custom data**, which appears when the webhook references custom data, then click **Test Webhook** or **Test Tool**. Sample values are not saved. * **API:** pass `callAdditionalData` and `agentAdditionalData` in the test request, as in the example above, and include the webhook's `customSettings`. Check **Request Sent** in the dashboard, or `sentRequest` in the API response, to see the final URL, headers and body. A variable that still appears with its braces had no value in the test data. See [Request Templating](/docs/webhooks-and-events/webhook-request-templating) for the full reference. *** ## Testing with webhook.site 1. Visit [webhook.site](https://webhook.site) 2. Copy your unique URL 3. Use as webhook URL in test API 4. Inspect full request details *** ## Local Testing with ngrok > [accordion] Setup > > ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} > # Install ngrok > brew install ngrok # macOS > # or download from ngrok.com > > # Authenticate > ngrok config add-authtoken YOUR_TOKEN > > # Start tunnel > ngrok http 3000 > # Output: https://abc123.ngrok.io -> localhost:3000 > ``` > [accordion] Local Webhook Server > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const express = require('express'); > > const app = express(); > app.use(express.json()); > > app.post('/webhook', (req, res) => { > console.log('Webhook received:', req.body.type); > > // Handle by type > switch (req.body.type) { > case 'StartWebHookPayload': > console.log('Call started:', req.body.callId); > break; > case 'CompletedWebHookPayload': > console.log('Call completed:', req.body.callId); > break; > case 'FailedWebHookPayload': > console.error('Call failed:', req.body.errorMessage); > break; > } > > res.status(200).json({ received: true }); > }); > > app.listen(3000, () => console.log('Server on port 3000')); > ``` > [accordion] Testing Workflow > > ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} > # Terminal 1: Start server > node webhook-server.js > > # Terminal 2: Start ngrok > ngrok http 3000 > > # Terminal 3: Test > curl -X POST https://blackbox.dasha.ai/api/v1/webhooks/test \ > -H "Authorization: Bearer YOUR_API_KEY" \ > -H "Content-Type: application/json" \ > -d '{ > "webHook": { "url": "https://abc123.ngrok.io/webhook" }, > "webhookType": "CompletedWebHookPayload" > }' > ``` Access ngrok web interface at `http://127.0.0.1:4040` to inspect and replay requests. *** ## Testing Event Types > [accordion] StartWebHookPayload > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > await fetch('https://blackbox.dasha.ai/api/v1/webhooks/test', { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > webHook: { url: 'https://your-server.com/webhook' }, > webhookType: 'StartWebHookPayload', > agentAdditionalData: { companyName: 'Acme Corp' }, > callAdditionalData: { customerId: 'cust_123' } > }) > }); > ``` > [accordion] ToolWebHookPayload > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > await fetch('https://blackbox.dasha.ai/api/v1/webhooks/test', { > method: 'POST', > headers: { > 'Authorization': 'Bearer YOUR_API_KEY', > 'Content-Type': 'application/json' > }, > body: JSON.stringify({ > webHook: { url: 'https://your-server.com/webhook' }, > webhookType: 'ToolWebHookPayload', > toolName: 'check_availability', > toolArguments: { date: '2025-01-20', time: '14:00' } > }) > }); > ``` *** > [accordion] Testing Retry Behavior > > Simulate failures to test retry handling: > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > let attemptCount = 0; > > app.post('/webhook', (req, res) => { > attemptCount++; > console.log(`Attempt ${attemptCount}`); > > // Fail first 2 attempts > if (attemptCount <= 2) { > return res.status(500).json({ error: 'Temporary error' }); > } > > res.status(200).json({ received: true }); > }); > ``` *** > [accordion] Testing Idempotency > > Handle duplicate webhooks: > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const processed = new Set(); > > app.post('/webhook', (req, res) => { > const id = `${req.body.callId}_${req.body.timestamp}`; > > if (processed.has(id)) { > console.log('Duplicate webhook, skipping'); > return res.status(200).json({ duplicate: true }); > } > > processed.add(id); > processWebhook(req.body); > > res.status(200).json({ received: true }); > }); > ``` *** ## Debugging ### Common Issues | Issue | Solution | | - | - | | Connection refused | Verify URL is publicly accessible | | Timeout | Respond within 30s, use async processing | | 401 Unauthorized | Check authentication headers | | 500 errors | Check server logs, add error handling | ### Response Time Requirements | Event Type | Max Response Time | | - | - | | StartWebHookPayload | 5 seconds | | ToolWebHookPayload | 10 seconds | | Other webhooks | 30 seconds | > [accordion] Quick Response Pattern > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > app.post('/webhook', (req, res) => { > // Respond immediately > res.status(200).json({ received: true }); > > // Process asynchronously > setImmediate(() => { > processWebhook(req.body); > }); > }); > ``` *** ## Pre-Production Checklist * [ ] Webhook URL is publicly accessible * [ ] Response time under required limit * [ ] Idempotency handling for duplicates * [ ] Error handling for all scenarios * [ ] Logging enabled for debugging * [ ] Tested all event types *** ## Next Steps * [Configuring Webhooks](/docs/webhooks-and-events/configuring-webhooks) — Set up webhook endpoints * [Webhook Events](/docs/webhooks-and-events/webhook-events) — Event types and payloads # Webhook Payload Types and Schemas Source: https://blackbox.dasha.ai/docs/webhooks-and-events/webhook-events Complete reference for webhook payload types, structures, and response formats based on the actual API schema. Use the `type` field to route incoming webhooks, then reference the tables below for field-by-field details on each payload. **What you'll learn:** Payload type enum, common fields, event-specific schemas, and response format requirements. *** ## WebHookPayloadType Enum All webhook payloads include a `type` field that serves as the discriminator. The possible values are: | Type Value | Description | Status | | - | - | - | | `StartWebHookPayload` | Call is starting (pre-call webhook) | Queued | | `CompletedWebHookPayload` | Call completed successfully | Completed | | `FailedWebHookPayload` | Call failed with an error | Failed | | `CallDeadLineWebHookPayload` | Call canceled due to deadline expiration | Canceled | | `TransferWebHookPayload` | Transfer decision requested (HTTP transfer) | Running | | `ToolWebHookPayload` | Tool/function execution requested | Running | | `UnknownWebHookPayload` | Unknown or unhandled payload type | - | *** ## Common Payload Fields All webhook payloads inherit from `BaseWebHookPayload` and include these common fields: | Field | Type | Required | Description | | - | - | - | - | | `type` | `WebHookPayloadType` | Yes | Discriminator field identifying the payload type | | `status` | `CallStatus` | Yes | Current call status (`Queued`, `Running`, `Completed`, `Failed`, `Canceled`) | | `callId` | `string` | Yes | Unique identifier for the call | | `agentId` | `string` | Yes | ID of the agent handling the call | | `orgId` | `string` | Yes | Organization identifier | | `callAdditionalData` | `object` | Yes | Custom metadata passed when creating the call | | `agentAdditionalData` | `object` | Yes | Custom metadata from agent configuration | | `serverJobId` | `string` | No | Internal server job identifier | | `sip` | `SipInfo` | No | 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. Present on inbound phone calls from the start webhook on, and on outbound phone calls from the result webhooks on: the platform reports the dialog when the call rings, is answered or is rejected (busy, declined), so not on their start webhook. Absent for web calls and chats, and for an outbound call that got no response to its INVITE. | | `endpoint` | `string` | No | Call endpoint (phone number, SIP URI, etc.) | ### SipInfo Structure When `sip` is present. On an inbound call, From is the caller and To is the number they dialed; on an outbound call, From is the agent's caller ID and To is the number dialed at your outbound SIP server. | Field | Type | Description | | - | - | - | | `fromUser` | `string` | User part of SIP From header | | `fromDomain` | `string` | Domain part of SIP From header | | `toUser` | `string` | User part of SIP To header | | `toDomain` | `string` | Domain part of SIP To header | | `diversion` | `string[]` | Array of diversion headers | | `xHeaders` | `object` | The custom X- headers of the dialog, by header name as sent (for example `X-Account-Id`): what your PBX or carrier adds to carry its own identifiers with the call. From the INVITE on an inbound call; from the response that set up or rejected the call on an outbound call. Empty when there were none | | `uui` | `object` | The `User-to-User` header of the dialog (RFC 7433), parsed, or null when the dialog carried none: the opaque context a PBX, contact center or carrier attaches to the call. `raw` is the header value as received, parameters included. `data` is the decoded text when the header was hex-encoded (the default), the data verbatim when it declared `encoding=ascii`, or the data verbatim when it could not be decoded; `encoding` says which (`hex`, `ascii` or `text`). `purpose` and `content` are the header's parameters, present only when sent. From the INVITE on an inbound call; from the response that set up or rejected the call on an outbound call | | `callId` | `string` | Call-ID header of the SIP dialog, the value your PBX or carrier logs for the call. Null when the platform has not reported it | ### CallStatus Values | Value | Description | | - | - | | `Unknown` | Unknown status | | `Created` | Call created but not yet queued | | `Pending` | Call pending execution | | `Queued` | Call queued and ready to start | | `Running` | Call in progress | | `Completed` | Call completed successfully | | `Failed` | Call failed with error | | `Canceled` | Call was canceled | ### CallConnectionType Values | Value | Description | | - | - | | `Unknown` | Unknown connection type | | `InboundAudio` | Inbound phone call | | `OutboundAudio` | Outbound phone call | | `WebChat` | Web-based chat session | | `WebCall` | Web-based voice call | | `WebPhone` | Web phone connection | *** ## StartWebHookPayload Sent when a call is about to start. This is a **pre-call webhook** that allows you to accept or reject the call, and optionally override the agent configuration. **Status:** `Queued` ### Fields | Field | Type | Required | Description | | - | - | - | - | | `type` | `"StartWebHookPayload"` | Yes | Discriminator | | `status` | `"Queued"` | Yes | Always `Queued` for start payloads | | `originalAgentConfig` | `AgentConfigDto` | Yes | The current agent configuration at call start | | *(common fields)* | - | Yes | All fields from `BaseWebHookPayload` | > [accordion] Example Payload > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "StartWebHookPayload", > "status": "Queued", > "callId": "660e8400-e29b-41d4-a716-446655440001", > "agentId": "550e8400-e29b-41d4-a716-446655440000", > "orgId": "org_123abc", > "callAdditionalData": { > "customerId": "cust_789", > "campaignId": "fall-promo-2024" > }, > "agentAdditionalData": { > "department": "sales" > }, > "endpoint": "+15551234567", > "sip": { > "fromUser": "+15551234567", > "fromDomain": "sip.provider.com", > "toUser": "agent-line", > "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" > }, > "originalAgentConfig": { > "primaryLanguage": "en-US", > "llmConfig": { > "vendor": "openai", > "model": "gpt-4.1-mini", > "prompt": "You are a helpful customer support agent..." > }, > "ttsConfig": { > "vendor": "Dasha", > "voiceId": "default-voice" > }, > "sttConfig": { > "vendor": "Auto" > } > } > } > ``` ### Start Webhook Response Your webhook must return one of two response types: #### StartWebHookResponseAccept Return this to accept the call and optionally override the agent configuration. | Field | Type | Required | Description | | - | - | - | - | | `accept` | `true` | Yes | Must be `true` to accept | | `overrideAgentConfig` | `AgentConfigDto` | No | Complete agent configuration to use instead of the original. **Note:** This replaces the entire configuration, not a partial merge. | | `additionalData` | `object` | No | Additional data to inject into the call context | > [accordion] Example: Accept Response > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "accept": true, > "overrideAgentConfig": { > "primaryLanguage": "es-ES", > "llmConfig": { > "vendor": "openai", > "model": "gpt-4.1", > "prompt": "Eres un agente de soporte al cliente...", > "options": { "temperature": 0.7 } > }, > "ttsConfig": { > "vendor": "ElevenLabs", > "voiceId": "spanish-voice-id" > }, > "sttConfig": { > "vendor": "Auto" > } > }, > "additionalData": { > "customerTier": "premium", > "preferredLanguage": "es" > } > } > ``` #### StartWebHookResponseReject Return this to reject the call. | Field | Type | Required | Description | | - | - | - | - | | `accept` | `false` | Yes | Must be `false` to reject | | `reasonMessage` | `string` | Yes | Reason for rejection (minimum 1 character) | > [accordion] Example: Reject Response > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "accept": false, > "reasonMessage": "Customer account is suspended" > } > ``` *** ## CompletedWebHookPayload Sent when a call reaches `Completed` status. Contains the full transcription and call results; `result.status` can still report a terminal failure. **Status:** `Completed` ### Fields | Field | Type | Required | Description | | - | - | - | - | | `type` | `"CompletedWebHookPayload"` | Yes | Discriminator | | `status` | `"Completed"` | Yes | Always `Completed` | | `callType` | `CallConnectionType` | Yes | Type of call connection | | `result` | `CompletedOutput` | Yes | Call result data including post-call analysis | | `transcription` | `Transcription[]` | Yes | Complete conversation transcript | | `toolCalls` | `ToolCall[]` | No | Tools the agent called, in start-time order. Absent or empty when no tool was called | | `inspectorUrl` | `string` | Yes | URL to view call in Call Inspector | | `recordingUrl` | `string` | No | URL to call recording (if enabled) | | `createdTime` | `string` (ISO 8601) | Yes | When the call was created | | `completedTime` | `string` (ISO 8601) | Yes | When the call completed | | `durationSeconds` | `number` | Yes | Total call duration in seconds | | `failure` | `ConversationFailureDto` | No | Customer-safe attribution when `result.status` is `Failed`; omitted for successful results | | *(common fields)* | - | Yes | All fields from `BaseWebHookPayload` | ### ConversationFailureDto Structure `failure` provides normalized, customer-safe details for `FailedWebHookPayload` and for a `CompletedWebHookPayload` whose `result.status` is `Failed`. | Field | Type | Required | Description | | - | - | - | - | | `stage` | `string` | Yes | Failed stage: `configuration`, `telephony`, `stt`, `llm`, `tts`, `tool`, `webhook`, `runtime`, or `unknown` | | `reason` | `string` | Yes | Provider-independent reason: `authentication`, `forbidden`, `rateLimit`, `timeout`, `unavailable`, `invalidConfiguration`, `rejected`, `cancelled`, `internal`, or `unknown` | | `upstreamOwner` | `string` | No | Failed upstream owner: `customer` or `platform` | | `protocol` | `string` | No | Transport protocol: `http`, `sip`, `grpc`, or `unknown` | | `statusCode` | `integer` | No | HTTP, SIP, or gRPC status code, when known | | `retryable` | `boolean` | No | Whether retrying may succeed, when known | | `message` | `string` | Yes | Canonical, customer-safe explanation | | `upstreamMessage` | `string` | No | Sanitized provider response; present only for a customer-managed upstream | Ownership fails closed. If `upstreamOwner` is missing or unrecognized, BlackBox treats it as `platform` and omits `upstreamMessage`. Dasha-managed provider details remain private. ### CompletedOutput Structure | Field | Type | Description | | - | - | - | | `failDetails` | `string` | Failure details (if any) | | `finishReason` | `string` | Reason for call completion | | `serviceStatus` | `string` | Service status code | | `status` | `string` | Final status | | `postCallAnalysis` | `object` | Results keyed by the configured analysis name; each value contains that analysis's labels | | `transferInformation` | `TransferInfo[]` | Array of transfer information (duration, etc.) | | `ivrDetection` | `IvrDetectionResult` | How IVR or answering machine detection ended the call; absent when detection did not end it | | `voiceDetections` | `VoiceDetection[]` | Every verdict of audio-based answering machine detection, in arrival order; empty when none arrived | ### IvrDetectionResult Structure | Field | Type | Description | | - | - | - | | `type` | `string` | `MaxProgressTonesReceived`, `MaxTonesReceived`, `SmartDetection`, `SmartDetectionInBackground`, `VoiceDetection` or `NavigationFailed` | | `description` | `string` | Human-readable description of the outcome | ### VoiceDetection Structure Present when IVR voice recognition is enabled for the agent. A call can carry several verdicts, for example a second detection window, so the list keeps them in the order they arrived. A machine verdict ends the call when the agent's IVR detection says so and sets `ivrDetection.type` to `VoiceDetection`. A human verdict is listed as well, and it never ends the call. | Field | Type | Description | | - | - | - | | `voiceType` | `string` | `robot` for a machine verdict, `human` for a human verdict | | `engine` | `string \| null` | Detection engine that produced the verdict, such as `amdy` or `dasha` | | `code` | `string` | The class the engine heard, such as `VOICEMAILAMD` or `OTHERAMD` | | `confidence` | `number` | Confidence of the verdict, from 0 to 1 | | `duration` | `number \| null` | Seconds of audio heard by the time of the verdict, leading silence included | | `rawAnswer` | `string \| null` | The engine's answer as received, such as `VOICEMAILAMD-4.50-0.95` | ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "ivrDetection": { "type": "VoiceDetection", "description": "Possible detected answering machine answer or IVR or voicemail detected. Ending call." }, "voiceDetections": [ { "voiceType": "robot", "engine": "amdy", "code": "VOICEMAILAMD", "confidence": 0.95, "duration": 4.5, "rawAnswer": "VOICEMAILAMD-4.50-0.95" } ] } ``` ### Transcription Structure | Field | Type | Description | | - | - | - | | `speaker` | `string` | Speaker identifier (`"user"` or `"assistant"`) | | `name` | `string` | Speaker name (optional) | | `text` | `string` | Transcribed text | | `startTime` | `string` (ISO 8601) | When this segment started | | `endTime` | `string` (ISO 8601) | When this segment ended | ### ToolCall Structure Covers custom webhook tools, MCP tools, and built-in tools. | Field | Type | Description | | - | - | - | | `id` | `string` | Identifier of the tool call, unique within the conversation | | `name` | `string` | Name of the tool | | `arguments` | any JSON value or `null` | Arguments the agent passed. Parsed JSON when valid, otherwise the raw string | | `result` | any JSON value or `null` | Value the tool returned. Parsed JSON when valid, otherwise the raw string | | `startTime` | `string` (ISO 8601) | When the agent called the tool | | `endTime` | `string` (ISO 8601) or `null` | When the tool returned; `null` if it had not returned when the call ended | > [accordion] Example Payload > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "CompletedWebHookPayload", > "status": "Completed", > "callId": "660e8400-e29b-41d4-a716-446655440001", > "agentId": "550e8400-e29b-41d4-a716-446655440000", > "orgId": "org_123abc", > "callAdditionalData": { > "customerId": "cust_789" > }, > "agentAdditionalData": {}, > "endpoint": "+15551234567", > "callType": "OutboundAudio", > "createdTime": "2024-10-20T14:32:00.000Z", > "completedTime": "2024-10-20T14:37:45.789Z", > "durationSeconds": 345.789, > "inspectorUrl": "https://blackbox.dasha.ai/calls/660e8400-e29b-41d4-a716-446655440001", > "recordingUrl": "https://storage.blackbox.dasha.ai/recordings/660e8400-e29b-41d4-a716-446655440001.mp3", > "result": { > "finishReason": "user_hangup", > "status": "success", > "postCallAnalysis": { > "call_outcome": { > "sentiment": "positive", > "issueResolved": true, > "callCategory": "billing_inquiry" > } > }, > "transferInformation": [] > }, > "transcription": [ > { > "speaker": "assistant", > "name": "Agent", > "text": "Hello! Thank you for calling. How can I help you today?", > "startTime": "2024-10-20T14:32:15.000Z", > "endTime": "2024-10-20T14:32:19.500Z" > }, > { > "speaker": "user", > "name": "Customer", > "text": "Hi, I have a question about my recent bill.", > "startTime": "2024-10-20T14:32:20.000Z", > "endTime": "2024-10-20T14:32:24.000Z" > }, > { > "speaker": "assistant", > "name": "Agent", > "text": "Of course! I'd be happy to help with your billing question. Could you tell me more about what you're seeing?", > "startTime": "2024-10-20T14:32:24.500Z", > "endTime": "2024-10-20T14:32:30.000Z" > } > ], > "toolCalls": [ > { > "id": "call_8f2d", > "name": "get_invoice", > "arguments": { "customerId": "cust_789" }, > "result": { "invoiceId": "inv_1042", "amount": 49.9, "status": "paid" }, > "startTime": "2024-10-20T14:32:31.000Z", > "endTime": "2024-10-20T14:32:31.420Z" > } > ] > } > ``` > [accordion] Example: Completed Payload with Terminal Failure > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "CompletedWebHookPayload", > "status": "Completed", > "callId": "660e8400-e29b-41d4-a716-446655440003", > "agentId": "550e8400-e29b-41d4-a716-446655440000", > "orgId": "org_123abc", > "callAdditionalData": { > "customerId": "cust_791" > }, > "agentAdditionalData": {}, > "endpoint": "+15551234569", > "callType": "OutboundAudio", > "createdTime": "2026-09-18T14:32:00.000Z", > "completedTime": "2026-09-18T14:32:18.000Z", > "durationSeconds": 18, > "inspectorUrl": "https://blackbox.dasha.ai/calls/660e8400-e29b-41d4-a716-446655440003", > "result": { > "finishReason": "telephony_error", > "serviceStatus": "failed", > "status": "Failed", > "failDetails": "Your telephony provider rejected the call. Provider response: Forbidden.", > "postCallAnalysis": {}, > "transferInformation": [] > }, > "transcription": [], > "failure": { > "stage": "telephony", > "reason": "forbidden", > "upstreamOwner": "customer", > "protocol": "sip", > "statusCode": 403, > "retryable": false, > "message": "Your telephony provider rejected the call.", > "upstreamMessage": "Forbidden." > } > } > ``` *** ## FailedWebHookPayload Sent when a call fails due to an error. **Status:** `Failed` ### Fields | Field | Type | Required | Description | | - | - | - | - | | `type` | `"FailedWebHookPayload"` | Yes | Discriminator | | `status` | `"Failed"` | Yes | Always `Failed` | | `callType` | `CallConnectionType` | Yes | Type of call connection | | `errorMessage` | `string` | Yes | Customer-safe error text; remains a required string for backward structural compatibility | | `failure` | `ConversationFailureDto` | No | Structured, customer-safe failure attribution, when available | | `toolCalls` | `ToolCall[]` | No | Tools the agent called before the failure, in start-time order (see [ToolCall Structure](#toolcall-structure)) | | `inspectorUrl` | `string` | No | URL to view call in Call Inspector | | `recordingUrl` | `string` | No | URL to partial recording (if available) | | `createdTime` | `string` (ISO 8601) | Yes | When the call was created | | `completedTime` | `string` (ISO 8601) | Yes | When the call failed | | *(common fields)* | - | Yes | All fields from `BaseWebHookPayload` | > [accordion] Example Payload > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "FailedWebHookPayload", > "status": "Failed", > "callId": "660e8400-e29b-41d4-a716-446655440002", > "agentId": "550e8400-e29b-41d4-a716-446655440000", > "orgId": "org_123abc", > "callAdditionalData": { > "customerId": "cust_790" > }, > "agentAdditionalData": {}, > "endpoint": "+15551234568", > "callType": "OutboundAudio", > "createdTime": "2024-10-20T14:40:00.000Z", > "completedTime": "2024-10-20T14:40:30.456Z", > "errorMessage": "Your configured LLM provider rejected the request. Provider response: Incorrect API key.", > "failure": { > "stage": "llm", > "reason": "authentication", > "upstreamOwner": "customer", > "protocol": "http", > "statusCode": 401, > "retryable": false, > "message": "Your configured LLM provider rejected the request.", > "upstreamMessage": "Incorrect API key." > }, > "inspectorUrl": "https://blackbox.dasha.ai/calls/660e8400-e29b-41d4-a716-446655440002" > } > ``` For new structured failures, `errorMessage` contains only ownership-approved public text. It may include the sanitized `upstreamMessage` for a customer-owned upstream, but it never includes Dasha-managed provider details. *** ## CallDeadLineWebHookPayload Sent when a call is canceled because its scheduled deadline expired before the call could be executed. **Status:** `Canceled` ### Fields | Field | Type | Required | Description | | - | - | - | - | | `type` | `"CallDeadLineWebHookPayload"` | Yes | Discriminator | | `status` | `"Canceled"` | Yes | Always `Canceled` | | `callType` | `CallConnectionType` | Yes | Type of call connection | | `reasonMessage` | `string` | No | Reason for cancellation | | `createdTime` | `string` (ISO 8601) | No | When the call was created | | `completedTime` | `string` (ISO 8601) | No | When the call was canceled | | *(common fields)* | - | Yes | All fields from `BaseWebHookPayload` | > [accordion] Example Payload > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "CallDeadLineWebHookPayload", > "status": "Canceled", > "callId": "660e8400-e29b-41d4-a716-446655440003", > "agentId": "550e8400-e29b-41d4-a716-446655440000", > "orgId": "org_123abc", > "callAdditionalData": { > "scheduledFor": "2024-10-20T14:00:00.000Z" > }, > "agentAdditionalData": {}, > "endpoint": "+15551234569", > "callType": "OutboundAudio", > "createdTime": "2024-10-20T13:00:00.000Z", > "completedTime": "2024-10-20T15:00:00.000Z", > "reasonMessage": "Call deadline expired before execution" > } > ``` *** ## TransferWebHookPayload Sent during HTTP transfers to request a transfer decision. Your webhook determines where to route the call. **Status:** `Running` ### Fields | Field | Type | Required | Description | | - | - | - | - | | `type` | `"TransferWebHookPayload"` | Yes | Discriminator | | `status` | `"Running"` | Yes | Always `Running` | | `transferReason` | `string` | No | Reason for transfer execution | | `transcription` | `Transcription[]` | Yes | Partial transcription up to the transfer moment | | *(common fields)* | - | Yes | All fields from `BaseWebHookPayload` | > [accordion] Example Payload > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "TransferWebHookPayload", > "status": "Running", > "callId": "660e8400-e29b-41d4-a716-446655440004", > "agentId": "550e8400-e29b-41d4-a716-446655440000", > "orgId": "org_123abc", > "callAdditionalData": { > "customerId": "cust_791", > "accountTier": "premium" > }, > "agentAdditionalData": {}, > "endpoint": "+15551234570", > "transferReason": "Customer requested human agent for billing dispute", > "transcription": [ > { > "speaker": "assistant", > "name": "Agent", > "text": "I understand you'd like to speak with a billing specialist about your dispute.", > "startTime": "2024-10-20T14:45:00.000Z", > "endTime": "2024-10-20T14:45:05.000Z" > }, > { > "speaker": "user", > "name": "Customer", > "text": "Yes, I need to talk to someone who can actually help me with this refund.", > "startTime": "2024-10-20T14:45:06.000Z", > "endTime": "2024-10-20T14:45:10.000Z" > } > ] > } > ``` ### Transfer Webhook Response Your webhook should return a transfer decision specifying where to route the call. The response format depends on your transfer configuration. > [!NOTE] > > For complete details on transfer webhook responses and HTTP transfer configuration, see [Call Transfers](/docs/advanced-features/call-transfers). Transfer parameters documented there align with this TransferWebHookPayload. > [accordion] Example: Cold Transfer Response > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "transferTo": "+15559876543", > "transferType": "cold" > } > ``` > [accordion] Example: Warm Transfer Response > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "transferTo": "+15559876543", > "transferType": "warm", > "briefing": "Customer Jane Doe needs help with billing dispute. Account: premium tier." > } > ``` *** ## ToolWebHookPayload Sent when the AI agent invokes a configured tool/function during a conversation. **Status:** `Running` ### Fields | Field | Type | Required | Description | | - | - | - | - | | `type` | `"ToolWebHookPayload"` | Yes | Discriminator | | `status` | `"Running"` | Yes | Always `Running` | | `toolName` | `string` | Yes | Name of the tool being called | | `arguments` | `object` | Yes | Arguments passed to the tool (as defined in tool schema) | | *(common fields)* | - | Yes | All fields from `BaseWebHookPayload` | > [accordion] Example Payload > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "ToolWebHookPayload", > "status": "Running", > "callId": "660e8400-e29b-41d4-a716-446655440005", > "agentId": "550e8400-e29b-41d4-a716-446655440000", > "orgId": "org_123abc", > "callAdditionalData": { > "customerId": "cust_792" > }, > "agentAdditionalData": {}, > "endpoint": "+15551234571", > "toolName": "check_account_balance", > "arguments": { > "customerId": "cust_792", > "accountType": "checking" > } > } > ``` > [accordion] Tool Webhook Response > > Return the tool execution result as JSON. The structure depends on your tool definition. > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "balance": 1234.56, > "currency": "USD", > "lastTransaction": "2024-10-19T10:15:00Z" > } > ``` *** ## Event Handling Best Practices > [accordion] Use the Type Discriminator > > Always route based on the `type` field, not assumptions about payload structure: > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const handlers = { > 'StartWebHookPayload': handleStart, > 'CompletedWebHookPayload': handleCompleted, > 'FailedWebHookPayload': handleFailed, > 'CallDeadLineWebHookPayload': handleDeadline, > 'TransferWebHookPayload': handleTransfer, > 'ToolWebHookPayload': handleTool > }; > > app.post('/webhooks/blackbox', (req, res) => { > const handler = handlers[req.body.type]; > if (handler) { > return handler(req.body, res); > } > console.warn(`Unknown webhook type: ${req.body.type}`); > res.status(200).send('OK'); > }); > ``` ### Respond Quickly Dasha BlackBox expects webhook responses within the configured timeout (default: 10 seconds for start webhooks, 5 seconds for tools). > [accordion] Example: Async processing for long operations > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > // For long-running operations, acknowledge immediately and process asynchronously > app.post('/webhooks/blackbox', async (req, res) => { > if (req.body.type === 'CompletedWebHookPayload') { > // Acknowledge immediately > res.status(200).send('OK'); > // Process asynchronously > processCompletedCall(req.body).catch(console.error); > return; > } > // For start/transfer/tool webhooks, must respond with data > // ... > }); > ``` > [accordion] Handle All Payload Types > > Ensure your webhook handles all possible payload types gracefully: > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > app.post('/webhooks/blackbox', (req, res) => { > const { type } = req.body; > > // Log all received webhooks for debugging > console.log(`Received webhook: ${type}, callId: ${req.body.callId}`); > > switch (type) { > case 'StartWebHookPayload': > return handleStart(req, res); > case 'CompletedWebHookPayload': > case 'FailedWebHookPayload': > case 'CallDeadLineWebHookPayload': > // Status webhooks don't require response data > processStatusWebhook(req.body); > return res.status(200).send('OK'); > case 'TransferWebHookPayload': > return handleTransfer(req, res); > case 'ToolWebHookPayload': > return handleTool(req, res); > default: > console.warn(`Unhandled webhook type: ${type}`); > return res.status(200).send('OK'); > } > }); > ``` *** > [accordion] Complete Webhook Handler Example > > Here's a production-ready Express.js webhook handler implementing all payload types: > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const express = require('express'); > const app = express(); > app.use(express.json()); > > // Start webhook handler - accept/reject calls > async function handleStartWebhook(payload, res) { > const { callId, callAdditionalData, originalAgentConfig } = payload; > > try { > // Example: Check if customer is allowed to call > const customerId = callAdditionalData?.customerId; > const isAllowed = await checkCustomerStatus(customerId); > > if (!isAllowed) { > return res.json({ > accept: false, > reasonMessage: 'Customer account is not active' > }); > } > > // Example: Override config based on customer tier > const customerTier = await getCustomerTier(customerId); > if (customerTier === 'premium') { > return res.json({ > accept: true, > overrideAgentConfig: { > ...originalAgentConfig, > llmConfig: { > ...originalAgentConfig.llmConfig, > model: 'gpt-4.1' // Upgrade to better model for premium > } > }, > additionalData: { > customerTier: 'premium' > } > }); > } > > // Accept with default config > return res.json({ accept: true }); > > } catch (error) { > console.error('Start webhook error:', error); > // On error, accept with default config > return res.json({ accept: true }); > } > } > > // Completed webhook handler - process results > async function handleCompletedWebhook(payload) { > const { > callId, > transcription, > result, > durationSeconds, > callAdditionalData > } = payload; > > // Store call data > await storeCallRecord({ > callId, > customerId: callAdditionalData?.customerId, > duration: durationSeconds, > transcript: transcription, > postCallAnalysis: result.postCallAnalysis, > finishReason: result.finishReason > }); > > // "call_outcome" is the configured analysis name in this example. > if (result.postCallAnalysis?.call_outcome?.issueResolved === false) { > await createFollowUpTask(callId, callAdditionalData?.customerId); > } > } > > // Failed webhook handler - handle errors > async function handleFailedWebhook(payload) { > const { callId, errorMessage, callAdditionalData } = payload; > > await logCallFailure({ > callId, > customerId: callAdditionalData?.customerId, > error: errorMessage > }); > > // Alert on repeated failures > const recentFailures = await getRecentFailureCount( > callAdditionalData?.customerId, > '1h' > ); > if (recentFailures > 3) { > await alertOperations('High failure rate for customer'); > } > } > > // Transfer webhook handler - route calls > async function handleTransferWebhook(payload, res) { > const { callAdditionalData, transferReason } = payload; > > try { > // Route based on customer tier or transfer reason > const customerId = callAdditionalData?.customerId; > const accountTier = callAdditionalData?.accountTier; > > if (accountTier === 'premium') { > // Premium customers get warm transfer to dedicated rep > const assignedRep = await getAssignedRep(customerId); > return res.json({ > transferTo: assignedRep.phone, > transferType: 'warm', > briefing: `Premium customer ${customerId}. Reason: ${transferReason}` > }); > } > > // Standard customers get cold transfer to queue > return res.json({ > transferTo: '+1-555-0100', > transferType: 'cold' > }); > > } catch (error) { > console.error('Transfer webhook error:', error); > // Fallback to default support line > return res.json({ > transferTo: '+1-555-0100', > transferType: 'cold' > }); > } > } > > // Tool webhook handler - execute functions > async function handleToolWebhook(payload, res) { > const { toolName, arguments: args, callAdditionalData } = payload; > > try { > switch (toolName) { > case 'check_account_balance': > const balance = await getAccountBalance( > args.customerId, > args.accountType > ); > return res.json(balance); > > case 'schedule_callback': > const scheduled = await scheduleCallback( > callAdditionalData?.customerId, > args.preferredTime > ); > return res.json({ success: true, scheduledTime: scheduled }); > > case 'process_refund': > const refund = await processRefund( > args.orderId, > args.amount > ); > return res.json(refund); > > default: > return res.json({ error: `Unknown tool: ${toolName}` }); > } > } catch (error) { > console.error(`Tool ${toolName} error:`, error); > return res.json({ error: error.message }); > } > } > > // Main webhook endpoint > app.post('/webhooks/blackbox', async (req, res) => { > const payload = req.body; > > console.log(`Webhook received: ${payload.type}, callId: ${payload.callId}`); > > switch (payload.type) { > case 'StartWebHookPayload': > return handleStartWebhook(payload, res); > > case 'CompletedWebHookPayload': > await handleCompletedWebhook(payload); > return res.status(200).send('OK'); > > case 'FailedWebHookPayload': > await handleFailedWebhook(payload); > return res.status(200).send('OK'); > > case 'CallDeadLineWebHookPayload': > console.log(`Call ${payload.callId} canceled: ${payload.reasonMessage}`); > return res.status(200).send('OK'); > > case 'TransferWebHookPayload': > return handleTransferWebhook(payload, res); > > case 'ToolWebHookPayload': > return handleToolWebhook(payload, res); > > default: > console.warn(`Unknown webhook type: ${payload.type}`); > return res.status(200).send('OK'); > } > }); > > // Health check > app.get('/health', (req, res) => res.status(200).send('OK')); > > const PORT = process.env.PORT || 3000; > app.listen(PORT, () => { > console.log(`Webhook server running on port ${PORT}`); > }); > ``` *** ## Next Steps * [Configuring Webhooks](/docs/webhooks-and-events/configuring-webhooks) - Set up webhook endpoints * [Testing Webhooks](/docs/webhooks-and-events/testing-webhooks) - Test your webhook integration * [Call Transfers](/docs/advanced-features/call-transfers) - Transfer parameters align with TransferWebHookPayload * [Tools and Functions](/docs/create/tools-and-functions) - Configure tools for ToolWebHookPayload # Use Call Data in Webhook URLs and Headers Source: https://blackbox.dasha.ai/docs/webhooks-and-events/webhook-request-templating Insert call variables such as callAdditionalData into the URL, query string, headers and body of tool, result, start and HTTP transfer webhooks. Put data from the call straight into a webhook request. Write a variable such as `{{callAdditionalData.orderId}}` in the webhook URL, a header, a query parameter or the body, and Dasha BlackBox replaces it with the real value before it sends the request. **What you'll learn:** Where variables work, which variables exist, how to change the HTTP method, query string and body, and how to test the result. *** ## Quick example You create a call with this additional data: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "additionalData": { "customerId": "c-42" } } ``` You configure a tool webhook like this: | Field | Value | | - | - | | Webhook URL | `https://api.example.com/customers/{{callAdditionalData.customerId}}/orders` | | Header `X-Call-Id` | `{{callId}}` | Your API receives: ```http theme={"theme":{"light":"github-light","dark":"github-dark"}} POST https://api.example.com/customers/c-42/orders X-Call-Id: 67890abcdef123456789 Content-Type: application/json ``` The body is still the standard JSON payload for that webhook. Templating changes only the parts you put variables in. *** ## Where variables work Variables work the same way in all four webhooks: | Webhook | Configure in | | - | - | | Tool webhook | Agent → **Tools** → tool editor | | Result webhook | Agent → **Webhooks** → Result Webhooks | | Start webhook | Agent → **Webhooks** → Start Webhooks | | HTTP transfer webhook | Agent → call transfer settings → **HTTP** transfer | Within a webhook, you can use variables in: | Part of the request | Example | | - | - | | URL path | `https://api.example.com/orders/{{callAdditionalData.orderId}}` | | URL query string | `https://api.example.com/orders?tenant={{agentAdditionalData.tenant}}` | | Header names and values | `X-Tenant: {{agentAdditionalData.tenant}}` | | Query parameters (advanced settings) | `status` = `{{arguments.status}}` | | Request body (advanced settings) | `{ "order": "{{callAdditionalData.orderId}}" }` | In the dashboard, every field that accepts variables has a **`{ }`** button. Click it to pick a variable from the list for that webhook. For **callAdditionalData.** and **agentAdditionalData.**, pick the entry and type your own key. The cursor stays inside the braces. > [!NOTE] > > Existing webhooks are not affected. A webhook without variables or advanced settings is sent exactly as before, with the same JSON payload. *** ## Variable reference A variable is a path into the webhook's JSON payload. Every field described in [Webhook Events](/docs/webhooks-and-events/webhook-events) is available. ### Available in every webhook | Variable | Value | | - | - | | `{{callAdditionalData.<key>}}` | Additional data you pass when you create or [register](/docs/deploy/register-call) the call | | `{{agentAdditionalData.<key>}}` | The agent's own **Additional Data** | | `{{callId}}` | Unique ID of the call | | `{{agentId}}` | ID of the agent handling the call | | `{{orgId}}` | Your organization ID | | `{{endpoint}}` | Phone number or endpoint of the call | | `{{serverJobId}}` | Internal conversation job ID, useful for support requests | | `{{sip.fromUser}}`, `{{sip.fromDomain}}`, `{{sip.toUser}}`, `{{sip.toDomain}}`, `{{sip.xHeaders.<name>}}`, `{{sip.uui.data}}`, `{{sip.uui.raw}}`, `{{sip.callId}}` | The SIP dialog of the phone call: From and To addresses, the custom X- headers by name (`{{sip.xHeaders.X-Account-Id}}` for the header `X-Account-Id`), the User-to-User header (`{{sip.uui.data}}` decoded, `{{sip.uui.raw}}` as received) and the Call-ID. On inbound calls From is the caller; on outbound calls From is the agent's caller ID and To the number dialed. Inbound calls have it from the start webhook on; outbound calls from the result webhooks on (once the call rang, was answered or was rejected), so not on the start webhook | ### Specific to one webhook > [tab] Tool > > | Variable | Value | > | - | - | > | `{{arguments.<name>}}` | An argument the language model produced, as defined in the tool's schema | > | `{{toolName}}` | Name of the tool being called | > [tab] Result > > One result webhook receives completed, failed and deadline calls. Some variables exist only for some of these outcomes. > > | Variable | Available for | > | - | - | > | `{{status}}` | All outcomes: `Completed`, `Failed` or `Canceled` | > | `{{callType}}`, `{{createdTime}}`, `{{completedTime}}` | All outcomes | > | `{{durationSeconds}}`, `{{inspectorUrl}}` | Completed and failed calls | > | `{{recordingUrl}}` | Completed and failed calls that were recorded | > | `{{result.finishReason}}` | Completed calls | > | `{{result.postCallAnalysis.<key>}}` | Completed calls with [post-call analysis](/docs/advanced-features/post-call-analysis) | > | `{{errorMessage}}` | Failed calls | > | `{{reasonMessage}}` | Deadline (canceled) calls | > [tab] Start > > The start webhook has no extra variables of its own. `callAdditionalData` holds the data passed when the call was created. Data returned by the start webhook itself is added afterwards. > [tab] HTTP transfer > > | Variable | Value | > | - | - | > | `{{transferReason}}` | The agent's explanation of why it is transferring the call | *** ## How values are rendered | Rule | Detail | | - | - | | Syntax | `{{path}}`. Spaces inside the braces are ignored: `{{ callId }}` works. | | Nested values | Use dots: `{{callAdditionalData.customer.id}}`. Use a number for a list item: `{{callAdditionalData.items.0.sku}}`. | | Text and numbers | Inserted as they are. `true`, `false` and `null` are inserted as those words. | | Objects and lists | Inserted as raw JSON text. | | Missing value | The variable is **sent as written**, for example a literal `{{callAdditionalData.orderId}}`. Make sure every call supplies the keys you reference. | | Query string encoding | Query values are fully URL-encoded, so free-form text is safe there. | | Path encoding | Path values are only lightly encoded: `/`, `?` and `#` are not escaped. Use URL-safe identifiers in the path and put free-form text in a query parameter. | | Empty values | A query parameter or header whose value renders to empty text is left out of the request. | *** ## Advanced request settings Open **Advanced request settings** under the headers to change the request itself. | Setting | Options | | - | - | | **HTTP Method** | `POST` (default), `GET`, `PUT`, `PATCH`, `DELETE` | | **Query Parameters** | Name and value pairs appended to the URL. Values accept variables. | | **Request Body** | `Default`, `Raw text`, `JSON object` or `Form (url-encoded)` | > [!WARNING] > > `GET` requests are sent without a body. Your API receives only the URL, query parameters and headers. Put everything it needs into those. ### Request body formats | Format | Content type | What is sent | | - | - | - | | Default | `application/json` | The standard payload for that webhook. Nothing changes. | | Raw text | `text/plain` | Your text template with variables replaced | | JSON object | `application/json` | A JSON object you build field by field | | Form (url-encoded) | `application/x-www-form-urlencoded` | Form fields you build field by field | For **JSON object** and **Form**, each row has a field name and a value: * For JSON, the field name is a dotted path in the output, so `customer.id` creates `{ "customer": { "id": … } }`. * A value that is exactly one variable, such as `{{arguments.units}}`, keeps its original type: a number stays a number. You can add a **fallback** used when the variable is missing. * Any other value is a literal or a text template, such as `order-{{callAdditionalData.orderId}}`. > [!WARNING] > > Changing the body format of a **result** or **start** webhook replaces the standard payload. Your endpoint then receives only the fields you map. For the start webhook, your endpoint must still [return an accept or reject response](/docs/webhooks-and-events/webhook-events#start-webhook-response). *** ## Configure in the dashboard **1. Pass the data with the call** Include `additionalData` when you create or register the call, for example `{ "customerId": "c-42" }`. **2. Open the webhook** Open the tool, the result or start webhook, or the HTTP transfer you want to change. **3. Insert variables** In **Webhook URL** or a header value, click **`{ }`** and pick a variable. For custom data, pick **callAdditionalData.** and type the key. **4. Adjust the request if needed** Open **Advanced request settings** to change the method, add query parameters or change the body. **5. Test and save** Fill in **Test values for custom data**, click **Test Tool** or **Test Webhook**, and check **Request Sent**. Then save. An amber **Unknown variable** hint under a field means the name is not in the list for that webhook. Check it for typos. *** ## Configure via API Set `customSettings` on the webhook object. This example is a tool webhook that sends a `GET` request: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "webhook": { "url": "https://api.example.com/customers/{{callAdditionalData.customerId}}/orders", "headers": { "Authorization": "Bearer your-webhook-key", "X-Call-Id": "{{callId}}" }, "customSettings": { "httpMethod": "GET", "queryParams": { "status": ["{{arguments.status}}"], "tenant": ["{{agentAdditionalData.tenant}}"] } } } } ``` The same `webhook` object shape is used by `config.resultWebhook`, `config.startWebhook.webhook` and the HTTP transfer `webhook`. > [!WARNING] > > Variables are replaced **only when the webhook has `customSettings`**. Without it, the URL and headers are sent exactly as written, including the braces. If you only need variables, add the minimal setting `"customSettings": { "httpMethod": "POST" }`. The dashboard adds this for you when a URL or header contains a variable. > [accordion] customSettings reference > > | Field | Type | Description | > | - | - | - | > | `httpMethod` | `string` | `GET`, `POST`, `PUT`, `PATCH` or `DELETE`. Required. | > | `queryParams` | `object` | Map of parameter name to a list of values. A name with several values is repeated in the query string. | > | `bodyFormat` | `object` | Omit it to send the standard payload. | > | `bodyFormat.type` | `string` | `Text`, `Json` or `Form` | > | `bodyFormat.template` | `string` or `array` | For `Text`, the text template. For `Json` and `Form`, a list of field mappings. | > > Each field mapping has: > > | Field | Description | > | - | - | > | `jsonPath` | Output path (JSON) or field name (form). Required. | > | `argumentJsonPath` | Path in the webhook payload to copy from, without braces, such as `arguments.units`. Keeps the value's type. | > | `defaultValue` | Used when `argumentJsonPath` is not set or the path is missing. Text inside it may contain variables. | > [accordion] Example: build a JSON body > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "customSettings": { > "httpMethod": "POST", > "bodyFormat": { > "type": "Json", > "template": [ > { "jsonPath": "customer.id", "argumentJsonPath": "callAdditionalData.customerId" }, > { "jsonPath": "units", "argumentJsonPath": "arguments.units", "defaultValue": "metric" }, > { "jsonPath": "source", "defaultValue": "voice-agent" }, > { "jsonPath": "reference", "defaultValue": "call-{{callId}}" } > ] > } > } > } > ``` > > Request body: > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "customer": { "id": "c-42" }, > "units": "imperial", > "source": "voice-agent", > "reference": "call-67890abcdef123456789" > } > ``` *** ## Test with sample values `callAdditionalData` and `agentAdditionalData` exist only on a real call, so a test needs stand-in values. **In the dashboard:** the editor shows **Test values for custom data** with one input for every custom-data variable the webhook uses. Sample values are never saved. A blank `agentAdditionalData` value falls back to the agent's real Additional Data. The test result includes **Request Sent**, the exact URL, headers and body that were sent. **Via API:** pass the values to the test endpoint: ```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({ webhookType: 'ToolWebHookPayload', toolName: 'get_orders', toolArguments: { status: 'open' }, callAdditionalData: { customerId: 'c-42' }, agentAdditionalData: { tenant: 'acme' }, webHook: { url: 'https://api.example.com/customers/{{callAdditionalData.customerId}}/orders', customSettings: { httpMethod: 'GET', queryParams: { status: ['{{arguments.status}}'] } } } }) }); const result = await response.json(); console.log(result.sentRequest.url); // https://api.example.com/customers/c-42/orders?status=open ``` See [Testing Webhooks](/docs/webhooks-and-events/testing-webhooks) for more testing methods. *** ## Good to know * **One result webhook, three payloads.** A variable that a payload does not have is sent as written. Use variables that exist for every outcome, such as `{{status}}` or `{{callAdditionalData.<key>}}`, in the URL of a result webhook. * **The URL is rebuilt when `customSettings` is set.** Ordinary URLs are unchanged. A query parameter with an empty value, such as `?flag=`, is left out, and an encoded slash (`%2F`) in the path is decoded. Give parameters a value and avoid encoded slashes in templated webhook URLs. * **Query parameters merge.** A parameter in both the URL and the advanced settings is sent with both values. * **Secrets stay in headers.** Put API keys in a header value, not in the URL, so they do not appear in access logs. *** ## Troubleshooting | Symptom | Cause and fix | | - | - | | Your API receives a literal `{{callAdditionalData.orderId}}` | The call did not supply that key, or the key name differs in case. Check the call's `additionalData`. | | No variable is replaced at all | The webhook was configured via API without `customSettings`. Add `"customSettings": { "httpMethod": "POST" }`. | | A result webhook works for completed calls but not failed ones | The variable exists only for completed calls. See the **Result** tab in [Variable reference](#variable-reference). | | Your API receives no body | The method is `GET`. Use `POST`, or move the data into query parameters. | | A query parameter is missing | Its value rendered to empty text. Check the variable's value on that call. | *** ## What's next > [card] [Webhook Events](/docs/webhooks-and-events/webhook-events) > > Every payload field you can reference > [card] [Tools & Functions](/docs/create/tools-and-functions) > > Define tools and their webhooks > [card] [HTTP Transfer](/docs/advanced-features/call-transfers/http-transfer) > > Route transfers with your own API > [card] [Testing Webhooks](/docs/webhooks-and-events/testing-webhooks) > > Testing and debugging # Receive Real-Time Event Notifications Source: https://blackbox.dasha.ai/docs/webhooks-and-events/webhooks-overview Real-time event notifications and integration with external systems. Receive instant HTTP callbacks when calls complete, fail, or require tool execution. Get real-time notifications when events happen. Webhooks push HTTP callbacks to your server when calls complete, fail, or need tool execution. **What you'll learn:** How webhooks work and event types. *** ## How webhooks work **1. Event occurs** Call ends, agent updated, or tool called **2. Webhook triggered** BlackBox constructs HTTP POST with event payload **3. Delivery attempted** Request sent to your configured endpoint **4. Your endpoint responds** Return HTTP 200 to acknowledge *** ## Webhook types ### Event webhooks Notify about call lifecycle events. Configured in agent's "Webhooks" tab. | Event | Description | | - | - | | `StartWebHookPayload` | Call initiated or received | | `CompletedWebHookPayload` | Call finished with transcript | | `FailedWebHookPayload` | Call encountered error | | `TransferWebHookPayload` | Transfer decision requested | ### Tool webhooks Execute functions called by the agent during conversations. Configured in agent's "Tools" tab. > [card] [Tools & Functions](/docs/create/tools-and-functions) > > Complete tool configuration guide *** ## Security * **Use HTTPS** — Encrypt data in transit * **Respond quickly** — Return HTTP 200 within 30 seconds * **Handle duplicates** — Webhooks may be retried; use idempotency keys * **Validate payloads** — Check required fields before processing ### Endpoint requirements * URL must be publicly accessible * Cannot use localhost or loopback addresses (127.0.0.1, ::1) *** ## What's next > [card] [Configuring Webhooks](/docs/webhooks-and-events/configuring-webhooks) > > Setup guide > [card] [Request Templating](/docs/webhooks-and-events/webhook-request-templating) > > Call data in URLs, headers and bodies > [card] [Webhook Events](/docs/webhooks-and-events/webhook-events) > > Complete event reference > [card] [Testing Webhooks](/docs/webhooks-and-events/testing-webhooks) > > Testing and debugging # Build a Real-Time Text Chat Interface Source: https://blackbox.dasha.ai/docs/websockets/chat-implementation Build real-time text chat with AI agents using WebSocket connections for instant messaging. Build a text chat interface with WebSockets. Establish connections, send messages, receive agent responses, and handle conversation lifecycle. **What you'll learn:** Connection setup, message exchange, response handling, and conversation cleanup. > [!NOTE] > > **Testing requires a valid API key.** Generate a web integration token from your agent's Web Integrations settings in the Dasha BlackBox dashboard before starting. ## Prerequisites Before you start, ensure you have: * A Dasha BlackBox agent with chat enabled * A web integration token (from Dashboard → Agent → Web Integrations) * The `AllowWebChat` feature enabled on your web integration > [accordion] Connection flow > > Text chat follows this message sequence: > > ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} > sequenceDiagram > participant Client > participant Server as Dasha BlackBox Server > participant Agent as AI Agent > > Client->>Server: WebSocket connect > Server->>Client: Connection established > Client->>Server: initialize (callType: "chat") > Server->>Client: event (name: "connection") > > Client->>Server: incomingChatMessage ("Hello") > Server->>Client: text (source: "user", echo) > Agent->>Server: Generate response > Server->>Client: text (source: "assistant", response) > > Client->>Server: terminate > Server->>Client: conversationResult > Server->>Client: event (name: "closed") > ``` *** ## Step 1: Establish connection Connect to the WebSocket endpoint and send the `initialize` message: > [accordion] Example: WebSocket connection for chat > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const token = 'YOUR_WEB_INTEGRATION_TOKEN'; > const ws = new WebSocket( > `wss://blackbox.dasha.ai/api/v1/ws/webCall?token=${token}` > ); > > ws.onopen = () => { > // Send initialize message to start chat session > ws.send(JSON.stringify({ > type: 'initialize', > timestamp: new Date().toISOString(), > request: { > callType: 'chat', > additionalData: { > // Custom data passed to agent prompts > userId: 'user-123', > context: 'support' > } > } > })); > }; > ``` The server responds with a `connection` event when the agent session is ready: > [accordion] Example: Connection event response > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "event", > "name": "connection", > "timestamp": "2025-01-20T10:00:01Z", > "data": { > "recordId": "call-abc123" > } > } > ``` *** ## Step 2: Send messages Use the `incomingChatMessage` type to send text messages: > [accordion] Example: Send chat message > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > function sendMessage(text) { > if (ws.readyState !== WebSocket.OPEN) { > console.error('WebSocket not connected'); > return; > } > > ws.send(JSON.stringify({ > type: 'incomingChatMessage', > content: text, > timestamp: new Date().toISOString() > })); > } > > // Usage > sendMessage('Hello, I need help with my order'); > ``` ### IncomingChatMessage schema | Field | Type | Required | Description | | - | - | - | - | | `type` | `"incomingChatMessage"` | Yes | Message type identifier | | `content` | `string` | Yes | Text message content | | `timestamp` | `string` (ISO 8601) | Yes | Message timestamp | | `channelId` | `string \| null` | No | Optional channel identifier | *** ## Step 3: Receive messages Handle incoming messages from the server: > [accordion] Example: Handle incoming messages > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > ws.onmessage = (event) => { > const message = JSON.parse(event.data); > > switch (message.type) { > case 'event': > handleEvent(message); > break; > case 'text': > handleTextMessage(message); > break; > case 'toolCall': > handleToolCall(message); > break; > case 'toolCallResult': > handleToolResult(message); > break; > case 'conversationResult': > handleConversationResult(message); > break; > case 'error': > handleError(message); > break; > } > }; > > function handleEvent(message) { > switch (message.name) { > case 'connection': > console.log('Agent session ready'); > break; > case 'opened': > console.log('Conversation opened'); > break; > case 'closed': > console.log('Conversation closed'); > break; > } > } > > function handleTextMessage(message) { > const { source, text } = message.content; > > if (source === 'assistant') { > // Agent response > displayAgentMessage(text); > } else if (source === 'user') { > // Echo of user message (for transcript) > console.log('Message confirmed:', text); > } > } > > function handleError(message) { > console.error('Error:', message.data.message); > showErrorToUser(message.data.message); > } > ``` ### TextHistoryMessage schema | Field | Type | Description | | - | - | - | | `type` | `"text"` | Message type identifier | | `timestamp` | `string` (ISO 8601) | Message timestamp | | `content.source` | `"assistant" \| "user"` | Message sender | | `content.text` | `string \| null` | Message text content | | `content.name` | `string \| null` | Optional sender name | | `content.type` | `"potential" \| "confident" \| "final"` | Recognition confidence (user messages) | | `content.segmentId` | `string` | Segment identifier (user messages) | > [accordion] TextHistoryMessage example > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "text", > "timestamp": "2025-01-20T10:00:05Z", > "content": { > "source": "assistant", > "text": "Hello! I'd be happy to help you with your order. Could you provide your order number?", > "name": null > } > } > ``` *** ## Step 4: End conversation Send a `terminate` message and wait for the conversation result: > [accordion] Example: End conversation gracefully > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > function endConversation() { > return new Promise((resolve, reject) => { > let conversationResult = null; > const timeout = setTimeout(() => { > reject(new Error('Timeout waiting for conversation result')); > }, 5000); > > const originalHandler = ws.onmessage; > ws.onmessage = (event) => { > const message = JSON.parse(event.data); > > if (message.type === 'conversationResult') { > conversationResult = message.result; > clearTimeout(timeout); > ws.onmessage = originalHandler; > resolve(conversationResult); > } else { > originalHandler(event); > } > }; > > ws.send(JSON.stringify({ > type: 'terminate', > timestamp: new Date().toISOString() > })); > }); > } > > // Usage > const result = await endConversation(); > console.log('Conversation summary:', result); > ws.close(); > ``` > [accordion] ConversationResultHistoryMessage example > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "conversationResult", > "timestamp": "2025-01-20T10:05:00Z", > "result": { > "status": "completed", > "duration": 300, > "metadata": { > "callId": "call-abc123", > "agentId": "agent-xyz" > } > } > } > ``` *** ## Next steps > [card] [Message Reference](/docs/websockets/message-reference) > > Complete schema documentation for all WebSocket messages > [card] [Voice Call Implementation](/docs/websockets/voice-call-implementation) > > Add WebRTC voice calls to your integration > [card] [Tool Execution](/docs/websockets/tool-execution) > > Handle agent tool calls via WebSocket > [card] [Error Handling](/docs/websockets/error-handling) > > Handle connection errors and edge cases # Error Handling Source: https://blackbox.dasha.ai/docs/websockets/error-handling WebSocket error messages and recovery. ## Error format ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "type": "error", "timestamp": "2025-01-20T10:00:00Z", "data": { "message": "Invalid token" } } ``` ## Error messages | Error | Cause | | - | - | | `Missing token` | No token in query string | | `Invalid token` | Token invalid or expired | | `Web integration is not enabled` | Integration disabled in dashboard | | `Origin not allowed` | Domain not in allowed origins | | `Init message not received` | Didn't send `initialize` message | | `Multiple init messages received` | Sent `initialize` more than once | | `Too large message` | Message exceeds size limit | ## Recovery * **Token errors**: Generate new token, reconnect * **Config errors**: Check settings in dashboard * **Connection lost**: Reconnect with exponential backoff (1s → 2s → 4s, max 30s) # WebSocket Message Types and Schemas Source: https://blackbox.dasha.ai/docs/websockets/message-reference Complete reference for all WebSocket message types, schemas, and their JSON structures. Reference for all WebSocket message types. Use this when building integrations to understand the exact JSON format for every message you send and receive. **What you'll learn:** Base message structure, client-to-server messages, server-to-client messages, and event payloads. > [!NOTE] > > **Testing requires a valid API key.** All examples in this section require authentication with either a web integration token or API key for Dasha BlackBox. > [accordion] Base message structure > > All WebSocket messages share these common fields: > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "messageType", > "timestamp": "2025-01-20T10:00:00Z", > "channelId": null > } > ``` | Field | Type | Required | Description | | - | - | - | - | | `type` | `string` | Yes | Message type identifier | | `timestamp` | `string` (ISO 8601) | Yes | Message timestamp | | `channelId` | `string \| null` | No | Optional channel identifier for routing | ## Client to server messages Messages you send to the Dasha BlackBox server. > [accordion] initialize > > Start a new conversation with an agent. Send immediately after WebSocket connection opens. > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "initialize", > "timestamp": "2025-01-20T10:00:00Z", > "request": { > "callType": "chat", > "additionalData": { > "userId": "user-123", > "context": "support" > } > } > } > ``` #### WebCallStartMessage schema | Field | Type | Required | Description | | - | - | - | - | | `type` | `"initialize"` | Yes | Message type | | `timestamp` | `string` (ISO 8601) | Yes | Message timestamp | | `channelId` | `string \| null` | No | Channel identifier | | `request` | `object` | Yes\* | Call configuration (production endpoint) | | `request.callType` | `"chat" \| "webCall" \| "onPhone"` | Yes | Type of conversation | | `request.additionalData` | `object` | No | Custom data passed to agent prompts | | `request.endpoint` | `string \| null` | No | Phone number for `onPhone` calls | | `devRequest` | `object` | Yes\* | Call configuration (dev endpoint) | \*Either `request` (production) or `devRequest` (development) is required, depending on which endpoint you're using. *** > [accordion] incomingChatMessage > > Send a text message to the agent during chat conversations. > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "incomingChatMessage", > "content": "Hello, I need help with my order", > "timestamp": "2025-01-20T10:01:00Z" > } > ``` #### IncomingChatMessage schema | Field | Type | Required | Description | | - | - | - | - | | `type` | `"incomingChatMessage"` | Yes | Message type | | `content` | `string` | Yes | Text message content | | `timestamp` | `string` (ISO 8601) | Yes | Message timestamp | | `channelId` | `string \| null` | No | Channel identifier | *** > [accordion] sdpAnswer > > Respond to WebRTC SDP offer for voice calls. Send in response to `sdpInvite` message. > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "sdpAnswer", > "timestamp": "2025-01-20T10:00:02Z", > "data": { > "sdpAnswer": "v=0\r\no=- 1234567890 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE audio\r\n..." > } > } > ``` #### SdpAnswerMessage schema | Field | Type | Required | Description | | - | - | - | - | | `type` | `"sdpAnswer"` | Yes | Message type | | `timestamp` | `string` (ISO 8601) | Yes | Message timestamp | | `channelId` | `string \| null` | No | Channel identifier | | `data.sdpAnswer` | `string` | Yes | WebRTC SDP answer string | *** > [accordion] websocketToolResponse > > Return the result of a tool execution requested via WebSocket. Send in response to `websocketToolRequest` message. > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "websocketToolResponse", > "timestamp": "2025-01-20T10:00:05Z", > "content": { > "id": "tool-request-abc123", > "result": { > "status": "success", > "customer": { > "id": "cust-456", > "name": "John Smith", > "email": "john@example.com" > } > } > } > } > ``` #### WebsocketToolResponseMessage schema | Field | Type | Required | Description | | - | - | - | - | | `type` | `"websocketToolResponse"` | Yes | Message type | | `timestamp` | `string` (ISO 8601) | Yes | Message timestamp | | `channelId` | `string \| null` | No | Channel identifier | | `content.id` | `string` | Yes | Request ID from `websocketToolRequest` | | `content.result` | `unknown` | Yes | Tool execution result (any JSON value) | *** > [accordion] terminate > > End the conversation gracefully. Wait for `conversationResult` before closing the WebSocket. > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "terminate", > "timestamp": "2025-01-20T10:05:00Z" > } > ``` #### TerminateMessage schema | Field | Type | Required | Description | | - | - | - | - | | `type` | `"terminate"` | Yes | Message type | | `timestamp` | `string` (ISO 8601) | Yes | Message timestamp | | `channelId` | `string \| null` | No | Channel identifier | *** ## Server to client messages Messages you receive from the Dasha BlackBox server. > [accordion] event > > System events indicating connection state and lifecycle changes. > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "event", > "name": "connection", > "timestamp": "2025-01-20T10:00:01Z", > "data": { > "recordId": "call-abc123", > "endpoint": null > } > } > ``` #### EventHistoryMessage schema | Field | Type | Description | | - | - | - | | `type` | `"event"` | Message type | | `name` | `string` | Event name (see below) | | `timestamp` | `string` (ISO 8601) | Event timestamp | | `channelId` | `string \| null` | Channel identifier | | `data.recordId` | `string \| null` | Call record ID | | `data.endpoint` | `string \| null` | Phone endpoint (for `onPhone` calls) | | `data.startEstablishConnectionTimeISO` | `string \| null` | Connection start time | | `data.endEstablishConnectionTimeISO` | `string \| null` | Connection established time | #### Event names | Event | Description | When Triggered | | - | - | - | | `connection` | Agent session ready | After `initialize` is processed | | `opened` | Conversation started | Voice call connected or chat opened | | `closed` | Conversation ended | After `terminate` or natural completion | | `failedOpen` | Failed to open conversation | Agent unavailable, auth failed, etc. | *** ### text Text messages from agent or user speech transcription. > [accordion] Agent response > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "text", > "timestamp": "2025-01-20T10:01:05Z", > "content": { > "source": "assistant", > "text": "Hello! I'd be happy to help you with your order. Could you provide your order number?", > "name": null, > "synthStartISOTimes": "2025-01-20T10:01:03Z", > "synthEndISOTimes": "2025-01-20T10:01:04Z", > "playStartISOTimes": "2025-01-20T10:01:04Z", > "playEndISOTimes": "2025-01-20T10:01:08Z" > } > } > ``` > [accordion] User message (echo/transcription) > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "text", > "timestamp": "2025-01-20T10:01:00Z", > "content": { > "source": "user", > "text": "Hello, I need help with my order", > "name": null, > "type": "final", > "segmentId": "seg-abc123", > "startISOTimes": "2025-01-20T10:00:58Z", > "endISOTimes": "2025-01-20T10:01:00Z" > } > } > ``` #### TextHistoryMessage schema | Field | Type | Description | | - | - | - | | `type` | `"text"` | Message type | | `timestamp` | `string` (ISO 8601) | Message timestamp | | `channelId` | `string \| null` | Channel identifier | | `content.source` | `"assistant" \| "user"` | Message sender | | `content.text` | `string \| null` | Message text content | | `content.name` | `string \| null` | Sender name (optional) | **Additional fields for assistant messages:** | Field | Type | Description | | - | - | - | | `content.synthStartISOTimes` | `string \| null` | TTS synthesis start time | | `content.synthEndISOTimes` | `string \| null` | TTS synthesis end time | | `content.playStartISOTimes` | `string \| null` | Audio playback start time | | `content.playEndISOTimes` | `string \| null` | Audio playback end time | **Additional fields for user messages:** | Field | Type | Description | | - | - | - | | `content.type` | `"potential" \| "confident" \| "final"` | Recognition confidence | | `content.segmentId` | `string` | Speech segment identifier | | `content.startISOTimes` | `string` | Speech start time | | `content.endISOTimes` | `string \| null` | Speech end time | #### Recognition types | Type | Description | Use Case | | - | - | - | | `potential` | Low confidence interim result | Show real-time transcription | | `confident` | Medium confidence interim result | Update transcription display | | `final` | Final confirmed transcription | Store in conversation history | *** > [accordion] sdpInvite > > WebRTC SDP offer for voice call setup. Respond with `sdpAnswer`. > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "sdpInvite", > "timestamp": "2025-01-20T10:00:02Z", > "data": { > "sdpOffer": "v=0\r\no=- 1234567890 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE audio\r\nm=audio 9 UDP/TLS/RTP/SAVPF 111\r\n..." > } > } > ``` #### SdpInviteMessage schema | Field | Type | Description | | - | - | - | | `type` | `"sdpInvite"` | Message type | | `timestamp` | `string` (ISO 8601) | Message timestamp | | `channelId` | `string \| null` | Channel identifier | | `data.sdpOffer` | `string` | WebRTC SDP offer string | *** > [accordion] toolCall > > Notification that the agent is calling a tool/function. > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "toolCall", > "timestamp": "2025-01-20T10:02:00Z", > "name": "lookupOrder", > "args": { > "orderId": "ORD-12345" > }, > "callId": "tc-abc123", > "startISOTimes": "2025-01-20T10:02:00Z" > } > ``` #### ToolCallHistoryMessage schema | Field | Type | Description | | - | - | - | | `type` | `"toolCall"` | Message type | | `timestamp` | `string` (ISO 8601) | Message timestamp | | `channelId` | `string \| null` | Channel identifier | | `name` | `string` | Tool name | | `args` | `object` | Tool arguments | | `callId` | `string` | Unique call identifier | | `startISOTimes` | `string` (ISO 8601) | Tool call start time | *** > [accordion] toolCallResult > > Result of a tool execution. > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "toolCallResult", > "timestamp": "2025-01-20T10:02:03Z", > "name": "lookupOrder", > "callId": "tc-abc123", > "startISOTimes": "2025-01-20T10:02:00Z", > "endISOTimes": "2025-01-20T10:02:03Z", > "result": { > "orderId": "ORD-12345", > "status": "shipped", > "trackingNumber": "1Z999AA10123456784", > "estimatedDelivery": "2025-01-22" > } > } > ``` #### ToolCallResultHistoryMessage schema | Field | Type | Description | | - | - | - | | `type` | `"toolCallResult"` | Message type | | `timestamp` | `string` (ISO 8601) | Message timestamp | | `channelId` | `string \| null` | Channel identifier | | `name` | `string` | Tool name | | `callId` | `string` | Unique call identifier (matches `toolCall`) | | `startISOTimes` | `string` (ISO 8601) | Tool call start time | | `endISOTimes` | `string` (ISO 8601) | Tool call end time | | `result` | `unknown` | Tool execution result | *** > [accordion] websocketToolRequest > > Request to execute a tool via WebSocket (for tools configured with WebSocket execution). Respond with `websocketToolResponse`. > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "websocketToolRequest", > "timestamp": "2025-01-20T10:02:00Z", > "channelId": null, > "content": { > "id": "wtr-abc123", > "toolName": "updateCart", > "args": { > "action": "add", > "productId": "PROD-789", > "quantity": 2 > } > } > } > ``` #### WebsocketToolRequestHistoryMessage schema | Field | Type | Description | | - | - | - | | `type` | `"websocketToolRequest"` | Message type | | `timestamp` | `string` (ISO 8601) | Message timestamp | | `channelId` | `string \| null` | Channel identifier | | `content.id` | `string` | Request ID (use in response) | | `content.toolName` | `string` | Tool name to execute | | `content.args` | `unknown` | Tool arguments | *** > [accordion] conversationResult > > Final conversation summary and metadata. Sent after `terminate` or when conversation ends. > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "conversationResult", > "timestamp": "2025-01-20T10:05:00Z", > "result": { > "status": "completed", > "duration": 240, > "callId": "call-abc123", > "agentId": "agent-xyz789", > "transcript": [ > {"role": "user", "content": "Hello, I need help with my order"}, > {"role": "assistant", "content": "Hello! I'd be happy to help you with your order..."} > ], > "metadata": { > "resolvedIssue": true, > "sentiment": "positive" > } > } > } > ``` #### ConversationResultHistoryMessage schema | Field | Type | Description | | - | - | - | | `type` | `"conversationResult"` | Message type | | `timestamp` | `string` (ISO 8601) | Message timestamp | | `channelId` | `string \| null` | Channel identifier | | `result` | `object` | Conversation result payload | The `result` object structure depends on your agent configuration. *** > [accordion] error > > Error notification from the server. Terminal conversation errors include the same optional customer-safe `failure` object returned by result webhooks and Call Results. > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "error", > "timestamp": "2025-01-20T10:00:00Z", > "channelId": null, > "data": { > "message": "Your configured LLM provider rejected the request. Provider response: model access denied", > "failure": { > "stage": "llm", > "reason": "forbidden", > "upstreamOwner": "customer", > "protocol": "http", > "statusCode": 403, > "retryable": false, > "message": "Your configured LLM provider rejected the request.", > "upstreamMessage": "model access denied" > } > } > } > ``` #### ErrorHistoryMessage schema | Field | Type | Description | | - | - | - | | `type` | `"error"` | Message type | | `timestamp` | `string` (ISO 8601) | Message timestamp | | `channelId` | `string \| null` | Channel identifier | | `data.message` | `string` | Error message | | `data.failure` | `ConversationFailureDto \| null` | Structured, customer-safe terminal failure attribution, when available | Authentication, validation, and other non-conversation errors may omit `data.failure` or return it as `null`. Clients must continue to handle the required `data.message` fallback. #### Common error messages | Error | Cause | Resolution | | - | - | - | | `Invalid token` | Authentication failed | Check token validity in dashboard | | `Token expired` | Token has expired | Generate new token | | `Agent not found` | Invalid agent reference | Verify agent ID | | `Rate limit exceeded` | Too many requests | Implement backoff, reduce frequency | | `Connection timeout` | Session timed out | Reconnect with new session | | `Invalid message format` | Malformed JSON | Validate message structure | *** ## Message flow diagrams > [accordion] Chat conversation > > ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} > sequenceDiagram > participant Client > participant Server as Dasha BlackBox Server > participant Agent > > Client->>Server: initialize (callType: "chat") > Server->>Client: event (name: "connection") > > Client->>Server: incomingChatMessage > Server->>Client: text (source: "user", echo) > Agent->>Server: Generate response > Server->>Client: text (source: "assistant") > > Client->>Server: terminate > Server->>Client: conversationResult > Server->>Client: event (name: "closed") > ``` > [accordion] Voice call > > ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} > sequenceDiagram > participant Client > participant Server as Dasha BlackBox Server > participant Agent > > Client->>Server: initialize (callType: "webCall") > Server->>Client: event (name: "connection") > Server->>Client: sdpInvite > Client->>Server: sdpAnswer > Server->>Client: event (name: "opened") > > Note over Client,Agent: WebRTC audio streaming > > Server->>Client: text (source: "user", transcription) > Server->>Client: text (source: "assistant", response) > > Client->>Server: terminate > Server->>Client: conversationResult > Server->>Client: event (name: "closed") > ``` > [accordion] Tool execution via WebSocket > > ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} > sequenceDiagram > participant Client > participant Server as Dasha BlackBox Server > participant Agent > > Client->>Server: incomingChatMessage > Server->>Client: text (source: "user", echo) > > Agent->>Server: Decide to call tool > Server->>Client: toolCall (notification) > Server->>Client: websocketToolRequest > > Client->>Client: Execute tool > Client->>Server: websocketToolResponse > > Server->>Client: toolCallResult > Agent->>Server: Generate response with result > Server->>Client: text (source: "assistant") > ``` > [accordion] TypeScript types > > Use these types for type-safe message handling: > > ```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}} > // Base message structure > interface BaseMessage { > type: string; > timestamp: string; > channelId?: string | null; > } > > // Client to server messages > interface InitializeMessage extends BaseMessage { > type: 'initialize'; > request?: { > callType: 'chat' | 'webCall' | 'onPhone'; > additionalData?: Record<string, unknown>; > endpoint?: string | null; > }; > } > > interface IncomingChatMessage extends BaseMessage { > type: 'incomingChatMessage'; > content: string; > } > > interface SdpAnswerMessage extends BaseMessage { > type: 'sdpAnswer'; > data: { sdpAnswer: string }; > } > > interface WebsocketToolResponseMessage extends BaseMessage { > type: 'websocketToolResponse'; > content: { > id: string; > result: unknown; > }; > } > > interface TerminateMessage extends BaseMessage { > type: 'terminate'; > } > > type ClientMessage = > | InitializeMessage > | IncomingChatMessage > | SdpAnswerMessage > | WebsocketToolResponseMessage > | TerminateMessage; > > // Server to client messages > interface EventMessage extends BaseMessage { > type: 'event'; > name: 'connection' | 'opened' | 'closed' | 'failedOpen'; > data?: { > recordId?: string | null; > endpoint?: string | null; > }; > } > > interface TextMessage extends BaseMessage { > type: 'text'; > content: { > source: 'assistant' | 'user'; > text: string | null; > name?: string | null; > type?: 'potential' | 'confident' | 'final'; > segmentId?: string; > }; > } > > interface SdpInviteMessage extends BaseMessage { > type: 'sdpInvite'; > data: { sdpOffer: string }; > } > > interface ToolCallMessage extends BaseMessage { > type: 'toolCall'; > name: string; > args: Record<string, unknown>; > callId: string; > startISOTimes: string; > } > > interface ToolCallResultMessage extends BaseMessage { > type: 'toolCallResult'; > name: string; > callId: string; > result: unknown; > startISOTimes: string; > endISOTimes: string; > } > > interface WebsocketToolRequestMessage extends BaseMessage { > type: 'websocketToolRequest'; > content: { > id: string; > toolName: string; > args: unknown; > }; > } > > interface ConversationResultMessage extends BaseMessage { > type: 'conversationResult'; > result: Record<string, unknown>; > } > > interface ErrorMessage extends BaseMessage { > type: 'error'; > data: { > message: string; > failure?: { > stage: string; > reason: string; > upstreamOwner?: 'customer' | 'platform'; > protocol?: 'http' | 'sip' | 'grpc' | 'unknown'; > statusCode?: number; > retryable?: boolean; > message: string; > upstreamMessage?: string; > }; > }; > } > > type ServerMessage = > | EventMessage > | TextMessage > | SdpInviteMessage > | ToolCallMessage > | ToolCallResultMessage > | WebsocketToolRequestMessage > | ConversationResultMessage > | ErrorMessage; > > // Type guard helper > function isServerMessage(msg: unknown): msg is ServerMessage { > return ( > typeof msg === 'object' && > msg !== null && > 'type' in msg && > typeof (msg as { type: unknown }).type === 'string' > ); > } > ``` ## Next steps > [card] [Chat Implementation](/docs/websockets/chat-implementation) > > Build a complete chat interface with these messages > [card] [Tool Execution](/docs/websockets/tool-execution) > > Handle tool calls via WebSocket > [card] [Error Handling](/docs/websockets/error-handling) > > Handle errors and edge cases > [card] [Voice Implementation](/docs/websockets/voice-call-implementation) > > WebRTC voice call message flow # Execute Agent Tools in the Browser Source: https://blackbox.dasha.ai/docs/websockets/tool-execution Handle agent tool calls via WebSocket for real-time browser-based function execution. Execute agent tools in the browser via WebSocket. Handle real-time tool requests from the agent and return results — for UI interactions, form manipulation, and client-side state access. **What you'll learn:** WebSocket vs webhook tools, tool configuration, request handling, response format, and error handling. > [!NOTE] > > **Testing requires a valid API key.** Generate a web integration token from your agent's Web Integrations settings in the Dasha BlackBox dashboard before starting. ## When to use WebSocket tools WebSocket tool execution is designed for tools that need direct access to the user's browser or application state: **Use WebSocket tools for:** * UI interactions (clicking buttons, navigating tabs, scrolling) * Form manipulation (filling inputs, selecting options) * Browser actions (opening windows, navigating URLs) * Client-side state (localStorage, sessionStorage, DOM access) * Real-time user feedback (animations, notifications) **Use webhook tools for:** * Server-side API calls * Database queries * Email sending * Payment processing * Any operation requiring server-side secrets > [!WARNING] > > WebSocket tools execute in the browser. Never use them for operations requiring server-side secrets or authentication credentials. > [accordion] Tool execution flow > > ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} > sequenceDiagram > participant User > participant Client > participant Server as Dasha BlackBox Server > participant Agent > > User->>Client: Message to agent > Client->>Server: incomingChatMessage > Server->>Agent: Process message > > Agent->>Server: Decide to call tool > Server->>Client: toolCall (notification) > Server->>Client: websocketToolRequest > > Client->>Client: Execute tool function > Client->>Server: websocketToolResponse > > Server->>Client: toolCallResult > Agent->>Server: Generate response with result > Server->>Client: text (agent response) > ``` ## Step 1: Configure tools for WebSocket Tools must be explicitly configured for WebSocket execution in your web integration. ### Via dashboard 1. Go to **Dashboard → Agents → \[Your Agent] → Web Integrations** 2. Select your integration 3. Navigate to **Features** tab 4. Under **Tools**, add tool names to execute via WebSocket > [accordion] Via API > > Include tool names in your web integration's `tools` array: > > ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} > curl -X PATCH https://blackbox.dasha.ai/api/v1/webIntegrations/{integrationId} \ > -H "Authorization: Bearer YOUR_API_KEY" \ > -H "Content-Type: application/json" \ > -d '{ > "tools": ["scrollToElement", "fillFormField", "clickButton"] > }' > ``` > [accordion] Step 2: Handle tool requests > > Listen for `websocketToolRequest` messages and respond with `websocketToolResponse`: > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const ws = new WebSocket( > `wss://blackbox.dasha.ai/api/v1/ws/webCall?token=${token}` > ); > > // Tool handler registry > const toolHandlers = { > scrollToElement: async ({ selector }) => { > const element = document.querySelector(selector); > if (!element) { > return { success: false, error: 'Element not found' }; > } > element.scrollIntoView({ behavior: 'smooth' }); > return { success: true }; > }, > > fillFormField: async ({ selector, value }) => { > const element = document.querySelector(selector); > if (!element) { > return { success: false, error: 'Element not found' }; > } > element.value = value; > element.dispatchEvent(new Event('input', { bubbles: true })); > return { success: true, value }; > }, > > clickButton: async ({ selector }) => { > const element = document.querySelector(selector); > if (!element) { > return { success: false, error: 'Element not found' }; > } > element.click(); > return { success: true }; > } > }; > > ws.onmessage = async (event) => { > const message = JSON.parse(event.data); > > switch (message.type) { > case 'websocketToolRequest': > await handleToolRequest(message); > break; > > case 'text': > if (message.content.source === 'assistant') { > displayMessage(message.content.text); > } > break; > > case 'toolCall': > console.log(`Agent calling tool: ${message.name}`); > showToolIndicator(message.name); > break; > > case 'toolCallResult': > console.log(`Tool completed: ${message.name}`); > hideToolIndicator(message.name); > break; > } > }; > > async function handleToolRequest(message) { > const { id, toolName, args } = message.content; > > try { > const handler = toolHandlers[toolName]; > if (!handler) { > throw new Error(`Unknown tool: ${toolName}`); > } > > const result = await handler(args); > > ws.send(JSON.stringify({ > type: 'websocketToolResponse', > timestamp: new Date().toISOString(), > content: { id, result } > })); > } catch (error) { > ws.send(JSON.stringify({ > type: 'websocketToolResponse', > timestamp: new Date().toISOString(), > content: { > id, > result: { > success: false, > error: error.message > } > } > })); > } > } > ``` > [accordion] Request message format > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "websocketToolRequest", > "timestamp": "2025-01-20T10:02:00Z", > "channelId": null, > "content": { > "id": "wtr-abc123", > "toolName": "fillFormField", > "args": { > "selector": "#email-input", > "value": "user@example.com" > } > } > } > ``` > [accordion] Response message format > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "websocketToolResponse", > "timestamp": "2025-01-20T10:02:01Z", > "content": { > "id": "wtr-abc123", > "result": { > "success": true, > "value": "user@example.com" > } > } > } > ``` ## Step 3: Tool implementation examples > [accordion] Form automation tools > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const formTools = { > // Fill any form field by selector > setFieldValue: async ({ selector, value }) => { > const element = document.querySelector(selector); > if (!element) { > return { success: false, error: `Element not found: ${selector}` }; > } > > // Handle different input types > if (element.tagName === 'SELECT') { > element.value = value; > element.dispatchEvent(new Event('change', { bubbles: true })); > } else if (element.type === 'checkbox' || element.type === 'radio') { > element.checked = Boolean(value); > element.dispatchEvent(new Event('change', { bubbles: true })); > } else { > element.value = value; > element.dispatchEvent(new Event('input', { bubbles: true })); > } > > return { success: true, selector, value }; > }, > > // Get current form values > getFormData: async ({ formSelector }) => { > const form = document.querySelector(formSelector); > if (!form) { > return { success: false, error: 'Form not found' }; > } > > const formData = new FormData(form); > const data = Object.fromEntries(formData.entries()); > > return { success: true, data }; > }, > > // Submit a form > submitForm: async ({ formSelector }) => { > const form = document.querySelector(formSelector); > if (!form) { > return { success: false, error: 'Form not found' }; > } > > form.submit(); > return { success: true }; > } > }; > ``` > [accordion] Navigation tools > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const navigationTools = { > // Navigate to URL > navigateTo: async ({ url, newTab = false }) => { > if (newTab) { > window.open(url, '_blank'); > } else { > window.location.href = url; > } > return { success: true, url, newTab }; > }, > > // Scroll to element > scrollTo: async ({ selector, behavior = 'smooth' }) => { > const element = selector > ? document.querySelector(selector) > : window; > > if (selector && !element) { > return { success: false, error: 'Element not found' }; > } > > if (selector) { > element.scrollIntoView({ behavior, block: 'center' }); > } else { > window.scrollTo({ top: 0, behavior }); > } > > return { success: true }; > }, > > // Switch tabs in a tabbed interface > switchTab: async ({ tabId }) => { > const tab = document.querySelector(`[data-tab="${tabId}"]`); > if (!tab) { > return { success: false, error: `Tab not found: ${tabId}` }; > } > > // Hide all tab panels > document.querySelectorAll('.tab-panel').forEach(panel => { > panel.classList.remove('active'); > }); > > // Show selected panel > const panel = document.querySelector(`#${tabId}`); > if (panel) { > panel.classList.add('active'); > } > > // Update tab buttons > document.querySelectorAll('.tab-button').forEach(btn => { > btn.classList.remove('active'); > }); > tab.classList.add('active'); > > return { success: true, tabId }; > } > }; > ``` > [accordion] Data retrieval tools > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const dataTools = { > // Read displayed content > getElementText: async ({ selector }) => { > const element = document.querySelector(selector); > if (!element) { > return { success: false, error: 'Element not found' }; > } > > return { > success: true, > text: element.textContent?.trim() || '', > html: element.innerHTML > }; > }, > > // Get cart items (e-commerce example) > getCartItems: async () => { > const items = Array.from(document.querySelectorAll('.cart-item')).map(item => ({ > name: item.querySelector('.item-name')?.textContent, > price: item.querySelector('.item-price')?.textContent, > quantity: item.querySelector('.item-quantity')?.value > })); > > const total = document.querySelector('.cart-total')?.textContent; > > return { > success: true, > items, > total, > itemCount: items.length > }; > }, > > // Get page state > getPageState: async () => { > return { > success: true, > url: window.location.href, > title: document.title, > scrollPosition: { > x: window.scrollX, > y: window.scrollY > } > }; > } > }; > ``` ## Step 4: Complete implementation > [accordion] Complete implementation examples > > > [tab] React > > > > ```tsx theme={"theme":{"light":"github-light","dark":"github-dark"}} > > import { useState, useEffect, useRef, useCallback } from 'react'; > > > > interface ToolExecution { > > id: string; > > name: string; > > status: 'pending' | 'executing' | 'completed' | 'error'; > > args: unknown; > > result?: unknown; > > } > > > > interface ChatWithToolsProps { > > token: string; > > tools: Record<string, (args: unknown) => Promise<unknown>>; > > } > > > > export function ChatWithTools({ token, tools }: ChatWithToolsProps) { > > const [messages, setMessages] = useState<Array<{ > > sender: 'user' | 'agent'; > > text: string; > > }>>([]); > > const [executions, setExecutions] = useState<ToolExecution[]>([]); > > const [input, setInput] = useState(''); > > const wsRef = useRef<WebSocket | null>(null); > > > > const handleToolRequest = useCallback(async ( > > id: string, > > toolName: string, > > args: unknown > > ) => { > > // Update execution status > > setExecutions(prev => [ > > ...prev, > > { id, name: toolName, status: 'executing', args } > > ]); > > > > try { > > const handler = tools[toolName]; > > if (!handler) { > > throw new Error(`Unknown tool: ${toolName}`); > > } > > > > const result = await handler(args); > > > > setExecutions(prev => prev.map(e => > > e.id === id ? { ...e, status: 'completed', result } : e > > )); > > > > wsRef.current?.send(JSON.stringify({ > > type: 'websocketToolResponse', > > timestamp: new Date().toISOString(), > > content: { id, result } > > })); > > } catch (error) { > > const errorResult = { > > success: false, > > error: error instanceof Error ? error.message : 'Unknown error' > > }; > > > > setExecutions(prev => prev.map(e => > > e.id === id ? { ...e, status: 'error', result: errorResult } : e > > )); > > > > wsRef.current?.send(JSON.stringify({ > > type: 'websocketToolResponse', > > timestamp: new Date().toISOString(), > > content: { id, result: errorResult } > > })); > > } > > }, [tools]); > > > > useEffect(() => { > > const ws = new WebSocket( > > `wss://blackbox.dasha.ai/api/v1/ws/webCall?token=${token}` > > ); > > wsRef.current = ws; > > > > ws.onopen = () => { > > ws.send(JSON.stringify({ > > type: 'initialize', > > timestamp: new Date().toISOString(), > > request: { callType: 'chat', additionalData: {} } > > })); > > }; > > > > ws.onmessage = (event) => { > > const message = JSON.parse(event.data); > > > > switch (message.type) { > > case 'text': > > if (message.content.source === 'assistant' && message.content.text) { > > setMessages(prev => [...prev, { > > sender: 'agent', > > text: message.content.text > > }]); > > } > > break; > > > > case 'websocketToolRequest': > > handleToolRequest( > > message.content.id, > > message.content.toolName, > > message.content.args > > ); > > break; > > > > case 'toolCall': > > setExecutions(prev => [ > > ...prev, > > { id: message.callId, name: message.name, status: 'pending', args: message.args } > > ]); > > break; > > } > > }; > > > > return () => ws.close(); > > }, [token, handleToolRequest]); > > > > const sendMessage = () => { > > const text = input.trim(); > > if (!text || !wsRef.current) return; > > > > setMessages(prev => [...prev, { sender: 'user', text }]); > > wsRef.current.send(JSON.stringify({ > > type: 'incomingChatMessage', > > content: text, > > timestamp: new Date().toISOString() > > })); > > setInput(''); > > }; > > > > return ( > > <div className="chat-with-tools"> > > <div className="messages"> > > {messages.map((msg, i) => ( > > <div key={i} className={`message ${msg.sender}`}> > > {msg.text} > > </div> > > ))} > > </div> > > > > {executions.length > 0 && ( > > <div className="tool-executions"> > > <h4>Tool Executions</h4> > > {executions.map(exec => ( > > <div key={exec.id} className={`execution ${exec.status}`}> > > <span className="tool-name">{exec.name}</span> > > <span className="tool-status">{exec.status}</span> > > </div> > > ))} > > </div> > > )} > > > > <div className="input-area"> > > <input > > type="text" > > value={input} > > onChange={(e) => setInput(e.target.value)} > > onKeyPress={(e) => e.key === 'Enter' && sendMessage()} > > placeholder="Type a message..." > > /> > > <button onClick={sendMessage}>Send</button> > > </div> > > </div> > > ); > > } > > > > // Usage example > > const myTools = { > > highlightElement: async ({ selector }: { selector: string }) => { > > const el = document.querySelector(selector); > > if (!el) return { success: false, error: 'Not found' }; > > (el as HTMLElement).style.outline = '3px solid yellow'; > > return { success: true }; > > }, > > > > showNotification: async ({ message }: { message: string }) => { > > alert(message); > > return { success: true }; > > } > > }; > > > > // <ChatWithTools token="YOUR_TOKEN" tools={myTools} /> > > ``` > > > [tab] Vanilla JavaScript > > > > ```html theme={"theme":{"light":"github-light","dark":"github-dark"}} > > <!DOCTYPE html> > > <html> > > <head> > > <title>WebSocket Tool Execution > > > > > > > >
> >

Chat with Tool Execution

> >
> >
> > > > > >
> >
> > > > > > > > > > ``` > [accordion] Error handling > > Always return structured error responses: > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > async function handleToolRequest(message) { > const { id, toolName, args } = message.content; > > try { > // Validate tool exists > const handler = toolHandlers[toolName]; > if (!handler) { > throw new ToolError('UNKNOWN_TOOL', `Unknown tool: ${toolName}`); > } > > // Validate arguments > const validation = validateArgs(toolName, args); > if (!validation.valid) { > throw new ToolError('INVALID_ARGS', validation.errors.join(', ')); > } > > // Execute with timeout > const result = await Promise.race([ > handler(args), > new Promise((_, reject) => > setTimeout(() => reject(new ToolError('TIMEOUT', 'Tool execution timeout')), 30000) > ) > ]); > > ws.send(JSON.stringify({ > type: 'websocketToolResponse', > timestamp: new Date().toISOString(), > content: { id, result } > })); > > } catch (error) { > ws.send(JSON.stringify({ > type: 'websocketToolResponse', > timestamp: new Date().toISOString(), > content: { > id, > result: { > success: false, > error: error.message, > code: error.code || 'UNKNOWN_ERROR' > } > } > })); > } > } > > class ToolError extends Error { > constructor(code, message) { > super(message); > this.code = code; > } > } > ``` ## Best practices > [accordion] Validate arguments before execution > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > function validateArgs(toolName, args) { > const schemas = { > fillFormField: { selector: 'string', value: 'string' }, > scrollToElement: { selector: 'string' }, > navigateTo: { url: 'string' } > }; > > const schema = schemas[toolName]; > if (!schema) return { valid: true }; > > const errors = []; > for (const [key, type] of Object.entries(schema)) { > if (typeof args[key] !== type) { > errors.push(`${key} must be a ${type}`); > } > } > > return { valid: errors.length === 0, errors }; > } > ``` > [accordion] Add logging for debugging > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > async function handleToolRequest(message) { > const { id, toolName, args } = message.content; > const startTime = performance.now(); > > console.log(`[Tool] ${toolName} started`, { id, args }); > > try { > const result = await toolHandlers[toolName](args); > const duration = Math.round(performance.now() - startTime); > console.log(`[Tool] ${toolName} completed in ${duration}ms`, { result }); > > // Send response... > } catch (error) { > const duration = Math.round(performance.now() - startTime); > console.error(`[Tool] ${toolName} failed after ${duration}ms`, { error }); > > // Send error response... > } > } > ``` > [accordion] Handle async operations safely > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const asyncTools = { > // Wait for element to appear > waitForElement: async ({ selector, timeout = 5000 }) => { > const startTime = Date.now(); > > while (Date.now() - startTime < timeout) { > const element = document.querySelector(selector); > if (element) { > return { success: true, found: true }; > } > await new Promise(resolve => setTimeout(resolve, 100)); > } > > return { success: false, error: 'Element not found within timeout' }; > }, > > // Retry operation > retryOperation: async ({ toolName, args, maxRetries = 3 }) => { > for (let attempt = 1; attempt <= maxRetries; attempt++) { > try { > const result = await toolHandlers[toolName](args); > return { ...result, attempts: attempt }; > } catch (error) { > if (attempt === maxRetries) { > return { success: false, error: error.message, attempts: attempt }; > } > await new Promise(resolve => setTimeout(resolve, 1000 * attempt)); > } > } > } > }; > ``` ## Troubleshooting ### Tool not being called **Possible causes:** * Tool not configured in web integration * Tool name mismatch between agent config and handler * Agent doesn't understand when to use the tool **Solution:** Verify tool name in dashboard matches exactly, check agent's tool descriptions are clear. > [accordion] Tool request times out > > **Possible causes:** > > * Handler takes too long to execute > > * Handler never returns > > * DOM operation fails silently > > **Solution:** Add timeouts, logging, and error boundaries: > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const withTimeout = (fn, ms = 10000) => async (...args) => { > const timeout = new Promise((_, reject) => > setTimeout(() => reject(new Error('Timeout')), ms) > ); > return Promise.race([fn(...args), timeout]); > }; > > const safeTools = Object.fromEntries( > Object.entries(tools).map(([name, fn]) => [name, withTimeout(fn)]) > ); > ``` > [accordion] Agent doesn't use tool result > > **Possible causes:** > > * Result format doesn't match what agent expects > > * Error in result not clearly communicated > > * Agent prompt doesn't instruct how to use results > > **Solution:** Use consistent result structure, include descriptive messages: > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > // Good: Clear, structured result > return { > success: true, > data: { orderId: 'ORD-123', status: 'shipped' }, > message: 'Order found and is currently shipped' > }; > > // Bad: Ambiguous result > return { orderId: 'ORD-123' }; > ``` ## Next steps > [card] [Message Reference](/docs/websockets/message-reference) > > Complete WebSocket message documentation > [card] [Error Handling](/docs/websockets/error-handling) > > Handle errors and edge cases # Implement Browser-Based Voice Calls with WebRTC Source: https://blackbox.dasha.ai/docs/websockets/voice-call-implementation Build browser-based voice calls with AI agents using WebRTC and WebSocket signaling. Build browser-based voice calls with WebRTC. Handle WebSocket signaling, SDP exchange, and audio streams — with complete code for the full call lifecycle. **What you'll learn:** WebRTC setup, SDP offer/answer exchange, audio handling, and call termination. > [!NOTE] > > **Testing requires a valid API key.** Generate a web integration token from your agent's Web Integrations settings in the Dasha BlackBox dashboard before starting. ## Prerequisites Before you start, ensure you have: * A Dasha BlackBox agent with voice enabled * A web integration token (from Dashboard → Agent → Web Integrations) * The `AllowWebCall` feature enabled on your web integration * HTTPS environment (WebRTC requires secure context) * User permission for microphone access > [accordion] Voice call architecture > > Voice calls use WebRTC for real-time audio and WebSocket for signaling: > > ```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}} > sequenceDiagram > participant Browser > participant WebSocket as Dasha BlackBox Server > participant Agent as AI Agent > > Browser->>WebSocket: WebSocket connect > WebSocket->>Browser: Connection established > Browser->>WebSocket: initialize (callType: "webCall") > WebSocket->>Browser: event (name: "connection") > WebSocket->>Browser: sdpInvite (SDP offer) > > Browser->>Browser: Create RTCPeerConnection > Browser->>Browser: Set remote description (offer) > Browser->>Browser: Get user media (microphone) > Browser->>Browser: Create SDP answer > > Browser->>WebSocket: sdpAnswer (SDP answer) > WebSocket->>Agent: WebRTC connection established > > Note over Browser,Agent: Bidirectional audio stream > > Browser->>WebSocket: terminate > WebSocket->>Browser: conversationResult > WebSocket->>Browser: event (name: "closed") > ``` *** ## Step 1: Establish WebSocket connection Connect and initialize with `callType: "webCall"`: > [accordion] Example: WebSocket connection for voice call > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const token = 'YOUR_WEB_INTEGRATION_TOKEN'; > const ws = new WebSocket( > `wss://blackbox.dasha.ai/api/v1/ws/webCall?token=${token}` > ); > > ws.onopen = () => { > ws.send(JSON.stringify({ > type: 'initialize', > timestamp: new Date().toISOString(), > request: { > callType: 'webCall', > additionalData: { > userId: 'user-123' > } > } > })); > }; > ``` *** ## Step 2: Handle SDP offer After initialization, the server sends an `sdpInvite` message with the WebRTC offer: > [accordion] Example: SDP invite message format > > ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} > { > "type": "sdpInvite", > "timestamp": "2025-01-20T10:00:02Z", > "data": { > "sdpOffer": "v=0\r\no=- 1234567890 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\n..." > } > } > ``` ### SdpInviteMessage schema | Field | Type | Description | | - | - | - | | `type` | `"sdpInvite"` | Message type identifier | | `timestamp` | `string` (ISO 8601) | Message timestamp | | `data.sdpOffer` | `string` | WebRTC SDP offer | *** ## Step 3: Create peer connection and send answer Create an `RTCPeerConnection`, set the remote offer, get microphone access, and send the answer: > [accordion] Example: Handle SDP offer and create peer connection > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > let peerConnection = null; > let localStream = null; > > ws.onmessage = async (event) => { > const message = JSON.parse(event.data); > > switch (message.type) { > case 'event': > if (message.name === 'connection') { > console.log('Agent session ready, waiting for SDP offer...'); > } > break; > > case 'sdpInvite': > await handleSdpInvite(message.data.sdpOffer); > break; > > case 'text': > if (message.content.source === 'assistant') { > console.log('Agent:', message.content.text); > } > break; > > case 'conversationResult': > console.log('Call ended:', message.result); > break; > > case 'error': > console.error('Error:', message.data?.message); > break; > } > }; > > async function handleSdpInvite(sdpOffer) { > // Create peer connection with STUN servers for NAT traversal > peerConnection = new RTCPeerConnection({ > iceServers: [ > { urls: 'stun:stun.l.google.com:19302' }, > { urls: 'stun:stun1.l.google.com:19302' } > ] > }); > > // Set remote description (server's offer) > await peerConnection.setRemoteDescription({ > type: 'offer', > sdp: sdpOffer > }); > > // Get microphone access > localStream = await navigator.mediaDevices.getUserMedia({ > audio: { > echoCancellation: true, > noiseSuppression: true, > autoGainControl: true > }, > video: false > }); > > // Add audio track to peer connection > localStream.getTracks().forEach(track => { > peerConnection.addTrack(track, localStream); > }); > > // Create and set local description (answer) > const answer = await peerConnection.createAnswer(); > await peerConnection.setLocalDescription(answer); > > // Send SDP answer to server > ws.send(JSON.stringify({ > type: 'sdpAnswer', > timestamp: new Date().toISOString(), > data: { > sdpAnswer: answer.sdp > } > })); > } > ``` ### SdpAnswerMessage schema | Field | Type | Required | Description | | - | - | - | - | | `type` | `"sdpAnswer"` | Yes | Message type identifier | | `timestamp` | `string` (ISO 8601) | Yes | Message timestamp | | `data.sdpAnswer` | `string` | Yes | WebRTC SDP answer | *** ## Step 4: Handle connection state changes Monitor WebRTC connection state and handle audio: > [accordion] Example: WebRTC connection state handlers > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > function setupPeerConnectionHandlers() { > // Handle connection state changes > peerConnection.onconnectionstatechange = () => { > console.log('Connection state:', peerConnection.connectionState); > > switch (peerConnection.connectionState) { > case 'connected': > console.log('Voice call connected'); > updateUI('connected'); > break; > case 'disconnected': > console.log('Voice call disconnected'); > updateUI('disconnected'); > break; > case 'failed': > console.error('Voice call failed'); > handleConnectionFailure(); > break; > } > }; > > // Handle ICE connection state > peerConnection.oniceconnectionstatechange = () => { > console.log('ICE state:', peerConnection.iceConnectionState); > > if (peerConnection.iceConnectionState === 'failed') { > // Attempt ICE restart > peerConnection.restartIce(); > } > }; > > // Handle incoming audio from agent > peerConnection.ontrack = (event) => { > const audioElement = document.getElementById('agent-audio'); > if (audioElement) { > audioElement.srcObject = event.streams[0]; > } > }; > > // Handle ICE candidates > peerConnection.onicecandidate = (event) => { > if (event.candidate) { > // ICE candidates are included in the SDP, no action needed > console.log('ICE candidate gathered'); > } > }; > } > ``` *** ## Step 5: End the call Clean up resources when ending the call: > [accordion] Example: End call and cleanup resources > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > function endCall() { > // Send terminate to server > if (ws && ws.readyState === WebSocket.OPEN) { > ws.send(JSON.stringify({ > type: 'terminate', > timestamp: new Date().toISOString() > })); > } > > // Stop local audio tracks > if (localStream) { > localStream.getTracks().forEach(track => track.stop()); > localStream = null; > } > > // Close peer connection > if (peerConnection) { > peerConnection.close(); > peerConnection = null; > } > } > > // Handle page unload > window.addEventListener('beforeunload', endCall); > ``` *** ## Next steps > [card] [Message Reference](/docs/websockets/message-reference) > > Complete schema documentation for all WebSocket messages > [card] [Error Handling](/docs/websockets/error-handling) > > Handle connection errors and edge cases > [card] [Chat Implementation](/docs/websockets/chat-implementation) > > Build text chat interfaces > [card] [Tool Execution](/docs/websockets/tool-execution) > > Handle agent tool calls via WebSocket # Build Real-Time Voice and Chat Experiences Source: https://blackbox.dasha.ai/docs/websockets/websockets-overview Build real-time voice and chat experiences with AI agents using WebSocket connections for instant bidirectional communication. Build real-time voice and chat experiences with Dasha BlackBox. WebSockets provide instant bidirectional communication with agents for browser-based voice calls, live chat, and client-side tool execution. **What you'll learn:** Connection lifecycle, call types, and when to use WebSockets vs REST. > [!NOTE] > > All WebSocket examples require authentication with a web integration token or API key. *** ## Connection lifecycle **1. Connect** Establish WebSocket connection to Dasha BlackBox server **2. Authenticate** Send `initialize` message with call configuration **3. Communicate** Exchange messages bidirectionally (chat or voice via WebRTC) **4. Disconnect** Send `terminate` to end gracefully *** ## Connection endpoints | Endpoint | Use case | Auth | | - | - | - | | `wss://blackbox.dasha.ai/api/v1/ws/webCall?token={TOKEN}` | Production | Web integration token | | `wss://blackbox.dasha.ai/api/v1/ws/dev?authorization={KEY}` | Development | API key | > [!WARNING] > > The dev endpoint requires your API key and should never be exposed in client-side code. *** ## Call types | Type | Value | Use case | | - | - | - | | **Text Chat** | `chat` | Customer support, FAQ bots | | **Web Call** | `webCall` | Browser-based voice support | | **Phone Call** | `onPhone` | Outbound campaigns, call centers | *** ## Quick start: Chat > [accordion] Example: Basic chat connection > > ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} > const ws = new WebSocket( > 'wss://blackbox.dasha.ai/api/v1/ws/webCall?token=YOUR_TOKEN' > ); > > ws.onopen = () => { > ws.send(JSON.stringify({ > type: 'initialize', > timestamp: new Date().toISOString(), > request: { callType: 'chat', additionalData: {} } > })); > }; > > ws.onmessage = (event) => { > const msg = JSON.parse(event.data); > if (msg.type === 'text' && msg.content.source === 'assistant') { > console.log('Agent:', msg.content.text); > } > }; > > function sendMessage(text) { > ws.send(JSON.stringify({ > type: 'incomingChatMessage', > content: text, > timestamp: new Date().toISOString() > })); > } > ``` *** ## When to use WebSockets vs REST **Use WebSockets for:** * Real-time chat conversations * Browser-based voice calls (WebRTC) * Tool execution with immediate results **Use REST API for:** * Creating and configuring agents * Enqueueing outbound phone calls * Fetching call history and results Most applications use both: REST for setup, WebSockets for runtime communication. *** ## Message types ### Client → Server | Type | Description | | - | - | | `initialize` | Start conversation | | `incomingChatMessage` | Send text message | | `sdpAnswer` | WebRTC SDP answer | | `websocketToolResponse` | Tool execution result | | `terminate` | End conversation | ### Server → Client | Type | Description | | - | - | | `event` | Connection lifecycle events | | `text` | Agent responses | | `sdpInvite` | WebRTC SDP offer | | `websocketToolRequest` | Tool execution request | | `conversationResult` | Conversation summary | | `error` | Error notification | > [card] [Message Reference](/docs/websockets/message-reference) > > Complete schema documentation *** ## What's next > [card] [Chat Implementation](/docs/websockets/chat-implementation) > > Build a complete text chat interface > [card] [Voice Call Implementation](/docs/websockets/voice-call-implementation) > > Add WebRTC voice calls > [card] [Message Reference](/docs/websockets/message-reference) > > Complete message schemas > [card] [Tool Execution](/docs/websockets/tool-execution) > > Handle agent tool calls