Route Calls Dynamically with Webhooks - Dasha BlackBox Documentation

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

Agent determines the caller needs transfer
Agent calls your webhook endpoint with conversation context
Your webhook returns routing decision: destination, type (warm/cold), and configuration
Agent executes the transfer as specified by webhook response
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

Open your agent’s configuration
Navigate to the Features tab
Scroll to Call Transfers section
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

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)

Static parameters passed with every request
Example: api_version=v1&source=voice_agent

Step 4: Webhook Request Format

Your webhook receives a TransferWebHookPayload with conversation context:

{
  "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": {
    "from": "+1234567890",
    "to": "+1987654321"
  }
}

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: SIP headers for inbound calls (from, to, domain, diversion)

Step 5: Webhook Response Format

Your webhook returns a TransferWebhookResponse with routing instructions:

{
  "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:

{
  "isSuccess": true,
  "transfer": {
    "type": "cold",
    "description": "Transfer to support queue",
    "endpointDestination": "+15550200"
  }
}

To cancel the transfer and continue the conversation:

{
  "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

Example: Complete HTTP Transfer Configuration

This shows the config.features.transfer object structure for HTTP transfer:

{
  "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

Skill-Based Routing

Route to agents with specific expertise:

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

Priority-Based Routing

VIP customers get routed to senior agents:

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

Workload Balancing

Route to least busy agent:

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

Geographic Routing

Route to agents in customer’s region:

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

Warm Transfer

What HTTP transfer returns for warm routing

Cold Transfer

What HTTP transfer returns for cold routing

Call Transfers Overview

Compare all transfer types

Webhooks

Receive call events

Documentation Index

​How HTTP Transfer Works

​When to Use HTTP Transfer

​Configuring HTTP Transfer

​Step 1: Enable HTTP Transfer

​Step 2: Configure Transfer Description

​Step 6: Configure Fallback Transfer

​Configuration Example

​Webhook Implementation Examples

​Use Cases

​Skill-Based Routing

​Priority Routing

​Geographic Routing

​Workload Balancing

​Language Matching

​Business Hours Routing

​Troubleshooting

​Problem: Webhook Times Out

​Problem: Webhook Returns Errors

​Problem: Fallback Transfer Used Often

​Problem: Wrong Agent Receives Transfer

​Next steps

Warm Transfer

Cold Transfer

Call Transfers Overview

Webhooks

How HTTP Transfer Works

When to Use HTTP Transfer

Configuring HTTP Transfer

Step 1: Enable HTTP Transfer

Step 2: Configure Transfer Description

Step 6: Configure Fallback Transfer

Configuration Example

Webhook Implementation Examples

Use Cases

Skill-Based Routing

Priority Routing

Geographic Routing

Workload Balancing

Language Matching

Business Hours Routing

Troubleshooting

Problem: Webhook Times Out

Problem: Webhook Returns Errors

Problem: Fallback Transfer Used Often

Problem: Wrong Agent Receives Transfer

Next steps