Guides

Multi-Agent Routing

Assign multiple specialized agents to a single phone number. Voicebip routes each inbound call to the right agent based on the caller’s first utterance, using keyword matching, regex patterns, or a default fallback.

How It Works

  1. A call arrives on a number with routing rules configured
  2. The caller speaks their first utterance (e.g., “I need help with my loan”)
  3. Voicebip evaluates routing rules in priority order (lowest number first)
  4. The first matching rule routes the call to the target agent
  5. If no rule matches within the 3-second latency budget, the default rule is used
  6. If there is no default rule, DTMF fallback prompts the caller to press a digit

Create a Routing Rule

$curl -X POST "https://api.voicebip.com/v1/routing-rules" \
>  -H "Authorization: Bearer pk_live_your_key" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "number_id": "num_xxx",
>    "priority": 1,
>    "match_type": "keyword",
>    "match_value": "loan",
>    "target_agent_id": "agt_loan_recovery"
>  }'

Match Types

TypeDescriptionExample
keywordCase-insensitive substring match against the first utterance"loan" matches “I need help with my loan”
regexRegular expression match against the first utterance`“(pay
defaultCatches all calls that don’t match any other rulematch_value is ignored

Example: Multi-Agent Setup

Route a single number to three specialized agents:

$# Rule 1: Loan-related calls go to the loan agent
$curl -X POST "https://api.voicebip.com/v1/routing-rules" \
>  -H "Authorization: Bearer pk_live_your_key" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "number_id": "num_lagos_001",
>    "priority": 1,
>    "match_type": "keyword",
>    "match_value": "loan",
>    "target_agent_id": "agt_loan_recovery"
>  }'
$
$# Rule 2: Payment-related calls go to the payment agent
$curl -X POST "https://api.voicebip.com/v1/routing-rules" \
>  -H "Authorization: Bearer pk_live_your_key" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "number_id": "num_lagos_001",
>    "priority": 2,
>    "match_type": "regex",
>    "match_value": "(pay|payment|bill|balance)",
>    "target_agent_id": "agt_payment_reminder"
>  }'
$
$# Rule 3: Everything else goes to the general support agent
$curl -X POST "https://api.voicebip.com/v1/routing-rules" \
>  -H "Authorization: Bearer pk_live_your_key" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "number_id": "num_lagos_001",
>    "priority": 99,
>    "match_type": "default",
>    "target_agent_id": "agt_customer_support"
>  }'

List Rules for a Number

$curl "https://api.voicebip.com/v1/routing-rules?number_id=num_lagos_001" \
>  -H "Authorization: Bearer pk_live_your_key"

Response:

1{
2  "routing_rules": [
3    {
4      "id": "rule_abc123",
5      "number_id": "num_lagos_001",
6      "priority": 1,
7      "match_type": "keyword",
8      "match_value": "loan",
9      "target_agent_id": "agt_loan_recovery",
10      "created_at": "2026-04-10T10:00:00Z"
11    },
12    {
13      "id": "rule_def456",
14      "number_id": "num_lagos_001",
15      "priority": 2,
16      "match_type": "regex",
17      "match_value": "(pay|payment|bill|balance)",
18      "target_agent_id": "agt_payment_reminder",
19      "created_at": "2026-04-10T10:01:00Z"
20    },
21    {
22      "id": "rule_ghi789",
23      "number_id": "num_lagos_001",
24      "priority": 99,
25      "match_type": "default",
26      "match_value": null,
27      "target_agent_id": "agt_customer_support",
28      "created_at": "2026-04-10T10:02:00Z"
29    }
30  ]
31}

Update a Rule

$curl -X PUT "https://api.voicebip.com/v1/routing-rules/rule_abc123" \
>  -H "Authorization: Bearer pk_live_your_key" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "priority": 0,
>    "match_value": "loan|recovery"
>  }'

Delete a Rule

$curl -X DELETE "https://api.voicebip.com/v1/routing-rules/rule_abc123" \
>  -H "Authorization: Bearer pk_live_your_key"

Latency Budget

Routing decisions have a 3-second latency budget. If the caller’s first utterance takes longer than 3 seconds to arrive (or the caller stays silent), the default rule is activated. If no default rule exists, a DTMF menu prompts the caller to select an agent by pressing a digit.

Best Practices

  • Always create a default rule as a catch-all
  • Use low priority numbers (1, 2, 3) for specific rules and high numbers (99) for the default
  • Prefer keyword over regex for simpler, faster matching
  • Test routing rules with the sandbox API (pk_test_ keys) before going live