> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.voicebip.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.voicebip.com/_mcp/server.

# Multi-Agent Routing

> Route inbound calls on a single phone number to different specialized agents based on caller intent.

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 (or the caller stays silent), the `default` rule is used
6. If there is no `default` rule, the call routes to the number's default agent

## Create a Routing Rule

```bash
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

| Type      | Description                                                  | Example                                         |         |                                                 |
| --------- | ------------------------------------------------------------ | ----------------------------------------------- | ------- | ----------------------------------------------- |
| `keyword` | Case-insensitive substring match against the first utterance | `"loan"` matches "I need help with my **loan**" |         |                                                 |
| `regex`   | Regular expression match against the first utterance         | \`"(pay                                         | payment | bill)"\` matches "I want to make a **payment**" |
| `default` | Catches all calls that don't match any other rule            | `match_value` is ignored                        |         |                                                 |

## Example: Multi-Agent Setup

Route a single number to three specialized agents:

```bash
# 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

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

Response:

```json
{
  "routing_rules": [
    {
      "id": "rule_abc123",
      "number_id": "num_lagos_001",
      "priority": 1,
      "match_type": "keyword",
      "match_value": "loan",
      "target_agent_id": "agt_loan_recovery",
      "created_at": "2026-04-10T10:00:00Z"
    },
    {
      "id": "rule_def456",
      "number_id": "num_lagos_001",
      "priority": 2,
      "match_type": "regex",
      "match_value": "(pay|payment|bill|balance)",
      "target_agent_id": "agt_payment_reminder",
      "created_at": "2026-04-10T10:01:00Z"
    },
    {
      "id": "rule_ghi789",
      "number_id": "num_lagos_001",
      "priority": 99,
      "match_type": "default",
      "match_value": null,
      "target_agent_id": "agt_customer_support",
      "created_at": "2026-04-10T10:02:00Z"
    }
  ]
}
```

## Update a Rule

```bash
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

```bash
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, the call falls through to the number's default agent.

## 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