Call Flows and Routing

Call flows define how inbound calls are routed through your system. They support conditional routing, time-based logic, and integration with external services.

Call Flow Basics

A call flow consists of:

Phone number: Which incoming number triggers the flow
Routing rules: How to route the call
Conditions: When each rule applies
Actions: What happens when a rule matches

Incoming Call
     │
     ▼
Match Phone Number
     │
     ▼
Evaluate Routing Rules (in order)
     │
     ├─► Condition 1: Time during business hours?
     │   └─► Route to Support Team
     │
     ├─► Condition 2: High priority caller?
     │   └─► Route to Priority Queue
     │
     └─► Default: Route to Voicemail

Creating a Call Flow

curl -X POST https://api.audian.com:8443/v2/call-flows \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Routing",
    "phone_number": "+14155552671",
    "description": "Route support calls to appropriate queues",
    "active": true,
    "routing": [
      {
        "pattern": "*",
        "destination": "+14155552673",
        "destination_type": "phone_number"
      }
    ]
  }'

Routing Rules

Rules are evaluated in order. The first matching rule is used.

Rule Structure

{
  "pattern": "PATTERN",
  "destination": "DESTINATION_ID",
  "destination_type": "DESTINATION_TYPE",
  "conditions": {
    // Optional conditions
  }
}

Pattern Matching

Patterns match DTMF input after an IVR menu:

Pattern	Matches
`*`	Any input (wildcard/default)
`1`	Digit 1
`2`	Digit 2
`[0-9]`	Any single digit
`[1-3]`	Digits 1, 2, or 3

Simple Routing

Route to a single destination:

curl -X POST https://api.audian.com:8443/v2/call-flows \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Direct Line",
    "routing": [
      {
        "pattern": "*",
        "destination": "+14155552673",
        "destination_type": "phone_number"
      }
    ]
  }'

Route based on IVR menu selection:

curl -X POST https://api.audian.com:8443/v2/call-flows \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Department Routing",
    "routing": [
      {
        "pattern": "*",
        "destination": "menu_departments",
        "destination_type": "ivr_menu"
      },
      {
        "pattern": "1",
        "destination": "+14155552673",
        "destination_type": "phone_number"
      },
      {
        "pattern": "2",
        "destination": "+14155552674",
        "destination_type": "phone_number"
      },
      {
        "pattern": "3",
        "destination": "+14155552675",
        "destination_type": "phone_number"
      }
    ]
  }'

Time-Based Routing

Route differently based on time of day and day of week:

curl -X POST https://api.audian.com:8443/v2/call-flows \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Business Hours Routing",
    "routing": [
      {
        "pattern": "*",
        "destination": "+14155552673",
        "destination_type": "phone_number",
        "conditions": {
          "time_range": {
            "start": "09:00",
            "end": "17:00",
            "timezone": "America/New_York",
            "days": ["MON", "TUE", "WED", "THU", "FRI"]
          }
        }
      },
      {
        "pattern": "*",
        "destination": "voicemail_default",
        "destination_type": "voicemail"
      }
    ]
  }'

Time Range Parameters

Parameter	Type	Description	Example
`start`	string	Start time (24-hour format)	`09:00`
`end`	string	End time (24-hour format)	`17:00`
`timezone`	string	IANA timezone	`America/New_York`
`days`	array	Days of week	`["MON", "WED", "FRI"]`

Supported timezones:

America/New_York
America/Chicago
America/Denver
America/Los_Angeles
Europe/London
Europe/Paris
Asia/Tokyo
And all IANA timezones

Caller ID Screening

Route based on caller information:

curl -X POST https://api.audian.com:8443/v2/call-flows \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP Caller Routing",
    "routing": [
      {
        "pattern": "*",
        "destination": "queue_vip",
        "destination_type": "queue",
        "conditions": {
          "vip_numbers": ["+14155552699", "+14155552698"]
        }
      },
      {
        "pattern": "*",
        "destination": "voicemail_blocked",
        "destination_type": "voicemail",
        "conditions": {
          "blocked_numbers": ["+14155552690"]
        }
      },
      {
        "pattern": "*",
        "destination": "queue_standard",
        "destination_type": "queue"
      }
    ]
  }'

Screening Parameters

Parameter	Type	Description
`vip_numbers`	array	High-priority numbers
`blocked_numbers`	array	Blocked/spam numbers
`allowed_area_codes`	array	Allow only specific area codes
`require_caller_id`	boolean	Require valid caller ID

Webhook-Based Dynamic Routing

Forward call info to your API for custom logic:

curl -X POST https://api.audian.com:8443/v2/call-flows \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Smart Routing",
    "routing": [
      {
        "pattern": "*",
        "destination": "https://your-api.example.com/route-call",
        "destination_type": "webhook"
      }
    ]
  }'

Your webhook receives:

{
  "call_id": "call_xyz789",
  "from": "+14155552672",
  "to": "+14155552671",
  "call_type": "inbound",
  "timestamp": "2024-01-15T10:30:00Z"
}

Respond with routing decision:

{
  "destination": "+14155552673",
  "destination_type": "phone_number",
  "tags": {
    "routed_by": "webhook",
    "queue": "support"
  }
}

Webhook Implementation

// Express.js example
app.post('/route-call', (req, res) => {
  const { call_id, from, to } = req.body;

  // Lookup customer
  const customer = lookupCustomer(from);

  if (customer && customer.is_vip) {
    // Route VIP to priority queue
    return res.json({
      destination: 'queue_vip',
      destination_type: 'queue',
      tags: { priority: 'high' }
    });
  }

  // Route standard caller
  res.json({
    destination: 'queue_standard',
    destination_type: 'queue'
  });
});

Geographic Routing

Route based on calling location:

curl -X POST https://api.audian.com:8443/v2/call-flows \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Geographic Routing",
    "routing": [
      {
        "pattern": "*",
        "destination": "+14155552673",
        "destination_type": "phone_number",
        "conditions": {
          "area_codes": ["415", "510", "707"]
        }
      },
      {
        "pattern": "*",
        "destination": "+18005551234",
        "destination_type": "phone_number"
      }
    ]
  }'

Load Balancing

Distribute calls across multiple destinations:

curl -X POST https://api.audian.com:8443/v2/call-flows \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Load Balanced Routing",
    "routing": [
      {
        "pattern": "*",
        "destinations": [
          { "number": "+14155552673", "weight": 50 },
          { "number": "+14155552674", "weight": 30 },
          { "number": "+14155552675", "weight": 20 }
        ],
        "destination_type": "load_balanced"
      }
    ]
  }'

Calls are distributed based on weight (percentage).

Fallback Routing

Define what happens if primary route fails:

curl -X POST https://api.audian.com:8443/v2/call-flows \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Failover Routing",
    "routing": [
      {
        "pattern": "*",
        "destination": "queue_support",
        "destination_type": "queue",
        "fallback": {
          "timeout": 30,
          "action": "transfer",
          "action_data": {
            "destination": "+14155552673"
          }
        }
      }
    ]
  }'

Fallback Actions

Action	Description	Data
`transfer`	Transfer to a number	`{"destination": "+..."}`
`voicemail`	Send to voicemail	`{"box_id": "..."}`
`hangup`	End the call	-
`repeat`	Repeat the menu	-

Conditional Routing Example

Complex routing with multiple conditions:

curl -X POST https://api.audian.com:8443/v2/call-flows \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Complex Routing",
    "routing": [
      {
        "pattern": "1",
        "destination": "queue_billing",
        "destination_type": "queue",
        "conditions": {
          "time_range": {
            "start": "08:00",
            "end": "18:00",
            "timezone": "America/New_York",
            "days": ["MON", "TUE", "WED", "THU", "FRI"]
          }
        }
      },
      {
        "pattern": "1",
        "destination": "voicemail_billing",
        "destination_type": "voicemail"
      },
      {
        "pattern": "2",
        "destination": "queue_support",
        "destination_type": "queue",
        "conditions": {
          "vip_numbers": ["+14155552699"]
        }
      },
      {
        "pattern": "2",
        "destination": "queue_support",
        "destination_type": "queue"
      },
      {
        "pattern": "*",
        "destination": "voicemail_default",
        "destination_type": "voicemail"
      }
    ]
  }'

Managing Call Flows

List Call Flows

curl https://api.audian.com:8443/v2/call-flows \
  -H "X-Auth-Token: YOUR_API_KEY"

Get Call Flow Details

curl https://api.audian.com:8443/v2/call-flows/cf_abc123 \
  -H "X-Auth-Token: YOUR_API_KEY"

Update Call Flow

curl -X PATCH https://api.audian.com:8443/v2/call-flows/cf_abc123 \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routing": [
      {
        "pattern": "*",
        "destination": "+14155552673",
        "destination_type": "phone_number"
      }
    ]
  }'

Delete Call Flow

curl -X DELETE https://api.audian.com:8443/v2/call-flows/cf_abc123 \
  -H "X-Auth-Token: YOUR_API_KEY"

Testing Call Flows

Test a call flow without making a real call:

curl -X POST https://api.audian.com:8443/v2/call-flows/cf_abc123/test \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+14155552672",
    "time": "2024-01-15T10:30:00Z"
  }'

Response shows which route would be selected:

{
  "matched_route": {
    "pattern": "1",
    "destination": "+14155552673",
    "destination_type": "phone_number"
  }
}

Analyzing Call Flow Performance

Get statistics on how calls are routed:

curl "https://api.audian.com:8443/v2/call-flows/cf_abc123/analytics?period=week" \
  -H "X-Auth-Token: YOUR_API_KEY"

Response:

{
  "period": "week",
  "total_calls": 1250,
  "routes": [
    {
      "pattern": "1",
      "calls_routed": 750,
      "percentage": 60,
      "avg_duration": 245
    },
    {
      "pattern": "2",
      "calls_routed": 400,
      "percentage": 32,
      "avg_duration": 180
    },
    {
      "pattern": "*",
      "calls_routed": 100,
      "percentage": 8,
      "avg_duration": 0
    }
  ]
}

Error Handling

Invalid Routing Configuration

{
  "error": "invalid_routing",
  "message": "No matching route for pattern",
  "code": 400
}

Route Not Available

{
  "error": "route_unavailable",
  "message": "Destination is currently unavailable",
  "code": 503
}

Best Practices

Order rules carefully: Place specific rules before general ones
Always have a default: Use "*" as the last rule
Test thoroughly: Test all routing paths
Monitor performance: Check analytics regularly
Use webhooks: Leverage dynamic routing for complex logic
Implement fallbacks: Define behavior when routes fail
Document flows: Add descriptions to flows for clarity

Call Flows and Routing

Call Flow Basics

Creating a Call Flow

Routing Rules

Rule Structure

Pattern Matching

Simple Routing

Menu-Based Routing

Time-Based Routing

Time Range Parameters

Caller ID Screening

Screening Parameters

Webhook-Based Dynamic Routing

Webhook Implementation

Geographic Routing

Load Balancing

Fallback Routing

Fallback Actions

Conditional Routing Example

Managing Call Flows

List Call Flows

Get Call Flow Details

Update Call Flow

Delete Call Flow

Testing Call Flows

Analyzing Call Flow Performance

Error Handling

Invalid Routing Configuration

Route Not Available

Best Practices

Next Steps

Call Flow Basics​

Creating a Call Flow​

Routing Rules​

Rule Structure​

Pattern Matching​

Simple Routing​

Menu-Based Routing​

Time-Based Routing​

Time Range Parameters​

Caller ID Screening​

Screening Parameters​

Webhook-Based Dynamic Routing​

Webhook Implementation​

Geographic Routing​

Load Balancing​

Fallback Routing​

Fallback Actions​

Conditional Routing Example​

Managing Call Flows​

List Call Flows​

Get Call Flow Details​

Update Call Flow​

Delete Call Flow​

Testing Call Flows​

Analyzing Call Flow Performance​

Error Handling​

Invalid Routing Configuration​

Route Not Available​

Best Practices​

Next Steps​

Call Flow Basics

Creating a Call Flow

Routing Rules

Rule Structure

Pattern Matching

Simple Routing

Menu-Based Routing

Time-Based Routing

Time Range Parameters

Caller ID Screening

Screening Parameters

Webhook-Based Dynamic Routing

Webhook Implementation

Geographic Routing

Load Balancing

Fallback Routing

Fallback Actions

Conditional Routing Example

Managing Call Flows

List Call Flows

Get Call Flow Details

Update Call Flow

Delete Call Flow

Testing Call Flows

Analyzing Call Flow Performance

Error Handling

Invalid Routing Configuration

Route Not Available

Best Practices

Next Steps