IVR Builder

Build interactive voice menus that greet callers, collect input, and route them to queues, agents, or sub-menus — with text-to-speech in 40+ languages and no code required.

Overview

An IVR (Interactive Voice Response) flow is a tree of menus. Each menu plays a greeting, waits for DTMF or speech input, and maps each digit to an action. Flows support multi-level nesting, business-hours routing, and callback offers.

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

Endpoints

Create IVR

POST /v1/voice/ivr

Field	Type	Required	Description
name	string	Yes	IVR display name
greeting	string	Yes	TTS prompt or audio file URL
language	string	No	BCP-47 code, e.g. en-US, am-ET, sw-KE
voice	string	No	male or female
options	array	Yes	Digit-to-action mappings
timeout	integer	No	Seconds to wait for input, default 10
max_retries	integer	No	Retries before failover, default 3
invalid_option_message	string	No	Played on invalid input

Each option supports: digit, action (transfer, submenu, voicemail, hangup, repeat), and destination.

curl -X POST https://api.afriroute.ai/api/v1/voice/ivr \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Menu",
    "greeting": "Welcome to AfriRoute. Press 1 for Sales, 2 for Support, 3 for Billing.",
    "language": "en-US",
    "voice": "female",
    "options": [
      { "digit": "1", "action": "transfer", "destination": "queue_sales" },
      { "digit": "2", "action": "transfer", "destination": "queue_support" },
      { "digit": "3", "action": "transfer", "destination": "queue_billing" },
      { "digit": "0", "action": "transfer", "destination": "agent_group_supervisors" }
    ],
    "timeout": 10,
    "max_retries": 3,
    "invalid_option_message": "Invalid selection. Please try again."
  }'

{
  "ivr_id": "ivr_main_menu",
  "name": "Main Menu",
  "status": "active",
  "created_at": "2026-05-28T09:00:00Z"
}

Multi-Language TTS

await fetch('https://api.afriroute.ai/api/v1/voice/ivr', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer $AFRIROUTE_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Amharic Menu',
    greeting: 'እንኳን ወደ አፍሪሩት በደህና መጡ።',
    language: 'am-ET',
    voice: 'female',
    options: [{ digit: '1', action: 'transfer', destination: 'queue_support' }]
  })
});

Nested Menu (Submenu)

import requests

requests.post(
    'https://api.afriroute.ai/api/v1/voice/ivr',
    headers={'Authorization': 'Bearer $AFRIROUTE_API_KEY'},
    json={
        'name': 'Billing Submenu',
        'greeting': 'Press 1 for payments, 2 for invoices.',
        'options': [
            {'digit': '1', 'action': 'transfer', 'destination': 'queue_payments'},
            {'digit': '2', 'action': 'submenu', 'destination': 'ivr_invoices'}
        ]
    }
)

Update IVR

PATCH /v1/voice/ivr/:ivr_id

curl -X PATCH https://api.afriroute.ai/api/v1/voice/ivr/ivr_main_menu \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "timeout": 8 }'

IVR Capabilities

• Multi-level menus and submenus
• Text-to-speech in 40+ languages, plus prerecorded audio
• DTMF collection and speech recognition (ASR)
• Business-hours and holiday-schedule routing
• In-queue callback offers
• Configurable retries and invalid-input handling

Best Practices

• Keep top-level menus to 4 or fewer options to reduce caller confusion.
• Offer a 0 shortcut to a live agent or supervisor group.
• Localize greetings; match language to the dialed number's region.
• Set max_retries to 3 and route persistent failures to voicemail rather than hanging up.

Error Handling

Code	Description	Action
INVALID_LANGUAGE	Unsupported TTS locale	Use a supported BCP-47 code
DESTINATION_NOT_FOUND	Option target missing	Create the queue/IVR first
DUPLICATE_DIGIT	Two options share a digit	Make digits unique

Related Links

• Call Queues
• Call Routing
• Quick Start
• Call Center API Reference

---

Last Updated: May 2026