Call Routing

Call routing decides which agent receives each contact. AfriRoute combines queue routing strategies, skills matching, business hours, and priority rules into a single, configurable engine.

Overview

Routing is evaluated in this order:

1. Number routing — the dialed number points to an IVR or directly to a queue
2. Time rules — business hours and holiday schedules decide if the queue is open
3. Priority — VIP/priority callers are placed ahead in the queue
4. Agent selection — the queue's strategy picks an eligible, available agent

Base URL: https://api.afriroute.ai — Auth: Authorization: Bearer $AFRIROUTE_API_KEY

Endpoints

Define a Routing Rule

POST /v1/voice/routing/rules

Field	Type	Required	Description
name	string	Yes	Rule name
match	object	Yes	Conditions (time, caller_region, vip)
strategy	string	Yes	round_robin, skills_based, longest_idle, priority, geographic
destination	string	Yes	Queue or agent group to route to
priority	integer	No	Lower number wins on conflicts

curl -X POST https://api.afriroute.ai/api/v1/voice/routing/rules \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP fast-track",
    "match": { "vip": true },
    "strategy": "priority",
    "destination": "queue_vip",
    "priority": 1
  }'

{
  "rule_id": "rule_vip_001",
  "name": "VIP fast-track",
  "status": "active",
  "created_at": "2026-05-28T09:00:00Z"
}

Set Business Hours

POST /v1/voice/routing/business-hours

await fetch('https://api.afriroute.ai/api/v1/voice/routing/business-hours', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer $AFRIROUTE_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    queue_id: 'queue_support',
    timezone: 'Africa/Addis_Ababa',
    hours: [
      { day: 'mon-fri', open: '08:00', close: '18:00' },
      { day: 'sat', open: '09:00', close: '13:00' }
    ],
    closed_action: 'voicemail',
    closed_destination: 'vm_support'
  })
});

import requests

requests.post(
    'https://api.afriroute.ai/api/v1/voice/routing/business-hours',
    headers={'Authorization': 'Bearer $AFRIROUTE_API_KEY'},
    json={
        'queue_id': 'queue_support',
        'timezone': 'Africa/Nairobi',
        'hours': [{'day': 'mon-fri', 'open': '08:00', 'close': '17:00'}],
        'closed_action': 'voicemail'
    }
)

Test a Route

POST /v1/voice/routing/simulate

curl -X POST https://api.afriroute.ai/api/v1/voice/routing/simulate \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "+254712345678", "to": "+254204440000", "vip": true }'

{
  "matched_rule": "rule_vip_001",
  "destination": "queue_vip",
  "selected_agent": "agent_john_m",
  "reason": "priority + skills_based match"
}

Routing Strategies

Strategy	Best For
round_robin	Even workload distribution
skills_based	Specialized teams (billing, technical)
longest_idle	Fairness across shifts
priority	VIP and SLA-bound callers
geographic	Region-specific language/agents

Best Practices

• Order rules with explicit priority values so VIP and SLA routes always win.
• Always set a closed_action for after-hours so calls are not dropped.
• Use the simulate endpoint in CI to catch misrouted numbers before deploying.
• Combine skills-based routing with longest_idle as a tiebreaker for fairness.

Error Handling

Code	Description	Action
NO_MATCHING_RULE	No rule matched the call	Add a catch-all default rule
INVALID_TIMEZONE	Unknown IANA timezone	Use a valid Africa/... zone
DESTINATION_UNAVAILABLE	Queue closed and no fallback	Define closed_action

Related Links

• Call Queues
• IVR Builder
• Monitoring
• Call Center API Reference

---

Last Updated: May 2026