> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IVR Auto-Attendants

> Build menu-driven call routing with time conditions and TTS

An IVR (Interactive Voice Response) is the menu callers hear when they dial in: "Press 1 for sales, 2 for support, 3 for billing." It's the front door of any phone system that handles more than one type of call. Hiveku IVRs support time-based routing, holiday schedules, recorded or text-to-speech prompts, and multi-level menus.

Manage IVRs in `/dashboard/communications/` under the **IVRs** tab.

## Anatomy of an IVR

<CardGroup cols={2}>
  <Card title="Greeting prompt" icon="microphone-lines">
    Plays first when a caller reaches the IVR. Recorded audio file or text-to-speech.
  </Card>

  <Card title="Menu prompt" icon="list-ol">
    "Press 1 for sales, 2 for support…" — usually right after the greeting.
  </Card>

  <Card title="Key mappings" icon="keyboard">
    Each digit (0-9, \*, #) routes to a destination — extension, ring group, queue, sub-IVR, or external number.
  </Card>

  <Card title="Timeout and invalid">
    What to do if the caller doesn't press anything, or presses an unmapped key.
  </Card>

  <Card title="Time conditions" icon="clock">
    Different routing during business hours vs after-hours.
  </Card>

  <Card title="Holiday calendar" icon="party-horn">
    Override the schedule on specific dates.
  </Card>
</CardGroup>

## Build a basic IVR

<Steps>
  <Step title="Create the IVR">
    From the **IVRs** tab, click **New IVR** and give it a name like "Main Menu".
  </Step>

  <Step title="Record or set the greeting">
    Either upload a `.wav`/`.mp3` file or type the script and pick a TTS voice. "Thanks for calling Acme."
  </Step>

  <Step title="Record or set the menu">
    "For sales, press 1. For support, press 2. To leave a message, press 3."
  </Step>

  <Step title="Map keys">
    1 → Ring Group "Sales", 2 → Queue "Support Hold", 3 → Voicemail.
  </Step>

  <Step title="Set timeout and invalid">
    Timeout (no key pressed in 8 seconds) → re-play the menu (max 2 retries). Invalid key → "That's not a valid option, please try again."
  </Step>

  <Step title="Point a DID at the IVR">
    On the **Numbers** tab, set your main DID to route to this IVR.
  </Step>
</Steps>

## Prompt options

<Tabs>
  <Tab title="Text-to-speech">
    Type your script, pick a voice (multiple US/UK English voices, plus other languages). Hiveku generates the audio.

    Pros: easy to update — change the script and the audio re-renders.

    Cons: TTS doesn't quite match a professional human voice for branding-critical greetings.
  </Tab>

  <Tab title="Upload your own">
    Record on your phone or in a studio, upload `.wav` or `.mp3`. Hiveku transcodes and uses it as the prompt.

    Pros: human voice, full brand control, professional polish.

    Cons: changes require re-recording.
  </Tab>

  <Tab title="Hire a voiceover">
    Hiveku integrates with several voiceover services. Order a recording from inside the IVR builder; it lands as an upload when complete.

    Pros: studio-quality without DIY.

    Cons: paid service, takes hours-days to deliver.
  </Tab>
</Tabs>

## Time conditions

Most businesses don't operate 24/7, and the menu (or destination) should change accordingly.

```
Business hours (Mon-Fri 9 AM-5 PM):
  - Greeting: "Thanks for calling Acme!"
  - 1 → Sales ring group
  - 2 → Support queue

After hours (everything else):
  - Greeting: "Thanks for calling Acme. Our office is closed."
  - 1 → Voicemail
  - 2 → Forward to on-call cell
```

Configure time conditions per IVR. Multiple bands supported — for example, lunch closure 12-1 PM with a different message.

## Holiday calendar

Override the schedule on specific dates. Hiveku ships a US federal holiday preset; add or remove dates as needed.

<Tip>
  For the "office closed for the holiday" greeting, use a separate IVR rather than another time condition — easier to test and toggle on/off ahead of time.
</Tip>

## Multi-level menus

Sub-IVRs let you build trees:

```
Main IVR
├── 1: Sales IVR
│   ├── 1: New customers (Ring Group "New Sales")
│   └── 2: Existing customers (Ring Group "Account Mgmt")
├── 2: Support IVR
│   ├── 1: Billing (Queue "Billing")
│   └── 2: Technical (Queue "Tech Support")
└── 0: Operator (Extension 100)
```

Keep menus to 2 levels max. Past that, callers get lost and abandon.

## Best practices

<CardGroup cols={2}>
  <Card title="Lead with the option" icon="arrow-up-right-from-square">
    "For sales, press 1" beats "Press 1 for sales." The action is what they're listening for.
  </Card>

  <Card title="Limit to 4-5 options" icon="circle-minus">
    More than 5 options and callers can't remember by the time they finish hearing them.
  </Card>

  <Card title="Always offer 0 for operator" icon="phone">
    A live human escape hatch reduces abandon and frustration.
  </Card>

  <Card title="Keep prompts under 30 seconds" icon="hourglass">
    Long greetings make callers hang up. Shave every word that doesn't earn its place.
  </Card>
</CardGroup>

## Time-of-day forwarding without an IVR

If you don't need a menu — just different routing during business vs after-hours — you can use a time condition directly on a DID without building a full IVR. Cleaner for simple cases.

## API

```bash theme={null}
# Create an IVR with key mappings
curl -X POST https://api.hiveku.com/api/communications/ivrs \
  -H "Authorization: Bearer hk_live_xxx" \
  -d '{
    "name": "Main Menu",
    "greeting": { "type": "tts", "text": "Thanks for calling Acme.", "voice": "en-US-Polly-Joanna" },
    "menu": { "type": "tts", "text": "For sales, press 1. For support, press 2." },
    "keys": {
      "1": "ring_group:sales",
      "2": "queue:support",
      "0": "extension:100"
    },
    "timeout_seconds": 8,
    "max_retries": 2
  }'
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Callers say the menu cuts them off">
    Increase the timeout (default 8 seconds). Older callers and people in noisy environments need more time to react.
  </Accordion>

  <Accordion title="DTMF presses aren't being detected">
    Some softphones over poor connections lose DTMF. Hiveku supports both in-band and RFC2833 DTMF. If you're seeing this on calls from specific carriers, switch the DTMF mode in the IVR's advanced settings.
  </Accordion>

  <Accordion title="Time conditions aren't switching at the right time">
    Check the IVR's time zone setting — defaults to your account TZ but can be overridden. Daylight savings transitions are handled automatically.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Set up a complete IVR" icon="rocket" href="/how-tos/setup-ivr">
    End-to-end walkthrough.
  </Card>

  <Card title="Queues" icon="users-line" href="/communications/queues">
    Send IVR overflow to a queue with hold music.
  </Card>
</CardGroup>