Call Queues

Call queues hold inbound contacts until an eligible agent is free. Each queue defines a routing strategy, wait limits, hold music, announcements, and overflow behavior.

Overview

A queue connects callers to agents. AfriRoute supports skills-based matching, priority levels for VIP callers, in-queue callbacks, and configurable overflow to voicemail or another destination. Queues are managed entirely over the REST API.

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

Endpoints

Create Queue

POST /v1/voice/queue

Field	Type	Required	Description
`name`	string	Yes	Queue display name
`routing_strategy`	string	Yes	`round_robin`, `skills_based`, `longest_idle`, `priority`, `geographic`
`skills_required`	array	No	Skills an agent must have (skills_based)
`max_wait_time`	integer	No	Seconds before overflow, default `300`
`callback_enabled`	boolean	No	Offer queued callers a callback
`queue_music`	string	No	URL to hold music
`overflow_action`	string	No	`voicemail`, `transfer`, `hangup`
`overflow_destination`	string	No	Target when overflow triggers
`announcements`	array	No	In-queue messages with intervals

curl -X POST https://api.afriroute.ai/api/v1/voice/queue \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Technical Support",
    "routing_strategy": "skills_based",
    "skills_required": ["technical_support"],
    "max_wait_time": 300,
    "callback_enabled": true,
    "queue_music": "https://cdn.afriroute.ai/hold.mp3",
    "overflow_action": "voicemail",
    "overflow_destination": "vm_support",
    "announcements": [
      { "message": "Thank you for waiting.", "interval": 30 },
      { "message": "Estimated wait is {wait_time} minutes.", "interval": 60 }
    ]
  }'

{
  "queue_id": "queue_support",
  "name": "Technical Support",
  "routing_strategy": "skills_based",
  "status": "active",
  "created_at": "2026-05-28T09:00:00Z"
}

List Queues

GET /v1/voice/queue

const res = await fetch('https://api.afriroute.ai/api/v1/voice/queue', {
  headers: { 'Authorization': 'Bearer $AFRIROUTE_API_KEY' }
});
const { queues } = await res.json();

Get Queue Status

GET /v1/voice/queue/:queue_id

import requests

r = requests.get(
    'https://api.afriroute.ai/api/v1/voice/queue/queue_support',
    headers={'Authorization': 'Bearer $AFRIROUTE_API_KEY'}
)
print(r.json())

{
  "queue_id": "queue_support",
  "calls_waiting": 5,
  "agents_available": 3,
  "longest_wait_time": 125,
  "average_wait_time": 45,
  "service_level": 87.5
}

Update Queue

PATCH /v1/voice/queue/:queue_id

curl -X PATCH https://api.afriroute.ai/api/v1/voice/queue/queue_support \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "max_wait_time": 180 }'

Routing Strategies

Strategy	Behavior
`round_robin`	Distribute calls evenly across agents
`skills_based`	Match `skills_required` to agent skills
`longest_idle`	Route to the least recently active agent
`priority`	Serve higher-priority callers first
`geographic`	Match caller region to agent

Best Practices

Set max_wait_time realistically and always define an overflow_action so callers are never stranded.
Use priority levels to fast-track VIP and postpaid customers.
Keep hold music short and loop-friendly; long files increase storage and bandwidth.
Enable callbacks for queues that regularly exceed 60 seconds of wait time.

Error Handling

Code	Description	Action
`INVALID_ROUTING_STRATEGY`	Unknown strategy value	Use a supported strategy
`QUEUE_NOT_FOUND`	Unknown `queue_id`	Verify the ID
`OVERFLOW_DESTINATION_INVALID`	Target does not exist	Create the destination first

Last Updated: May 2026

Overview​

Endpoints​

Create Queue​

List Queues​

Get Queue Status​

Update Queue​

Routing Strategies​

Best Practices​

Error Handling​

Related Links​