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

# Call Queues

> Hold music, callbacks, agent presence, and queue analytics

A call queue holds inbound callers in line until an agent is available. Unlike a ring group (which rings phones now), a queue parks callers with hold music, announces their position, offers a callback option, and routes to whichever agent comes free first.

Manage queues in `/dashboard/communications/` under the **Queues** tab.

## When to use a queue vs a ring group

| Use a ring group             | Use a queue                                 |
| ---------------------------- | ------------------------------------------- |
| Small team (2-5 agents)      | Larger team (5+ agents)                     |
| Predictable, low call volume | Variable or high volume                     |
| Caller hangs up if no answer | Caller waits with hold music                |
| No callback feature needed   | Callbacks reduce abandons                   |
| Simple routing               | Position announcements, ETA, agent presence |

You can chain them — a ring group **fails into** a queue when no one answers in 20 seconds.

## Anatomy of a queue

<CardGroup cols={2}>
  <Card title="Hold music" icon="music">
    Plays while the caller waits. Default options or upload your own.
  </Card>

  <Card title="Position announcement" icon="hashtag">
    "You are caller number 3 in line." Optional, configurable interval.
  </Card>

  <Card title="Estimated wait time" icon="hourglass">
    "Your estimated wait is 4 minutes." Computed from rolling average handle time.
  </Card>

  <Card title="Callback option" icon="phone-rotary">
    "Press 1 to keep your place and we'll call you back." Recovers \~30% of would-be abandons.
  </Card>

  <Card title="Agent presence" icon="user-clock">
    Agents log in/out, set break, set busy. Routing skips unavailable agents.
  </Card>

  <Card title="Strategy" icon="shuffle">
    Round-robin, longest-idle, fewest-calls, random — same as ring groups.
  </Card>
</CardGroup>

## Create a queue

<Steps>
  <Step title="Name and describe">
    "Sales Hold", "Support — Tier 1", "Billing".
  </Step>

  <Step title="Add agents">
    Pick the extensions that can take calls from this queue. An extension can be in multiple queues.
  </Step>

  <Step title="Pick a strategy">
    Round-robin, longest-idle, fewest-calls today, or random.
  </Step>

  <Step title="Set hold music">
    Pick from default playlists or upload your own.
  </Step>

  <Step title="Configure announcements">
    Position announcement on/off + interval (e.g., every 30 seconds), ETA on/off.
  </Step>

  <Step title="Configure callbacks">
    Allow callbacks on/off, after how long in queue (e.g., offer after 60 seconds).
  </Step>

  <Step title="Set max wait and overflow">
    After N minutes in queue, what happens — voicemail, another queue, an IVR, hang up.
  </Step>
</Steps>

## Hold music

Three options:

<Tabs>
  <Tab title="Default playlists">
    Hiveku ships several royalty-free playlists — calm, upbeat, classical, jazz. Switch instantly.
  </Tab>

  <Tab title="Upload your own">
    `.mp3` or `.wav` files. Total playlist length should be at least 5 minutes to avoid noticeable looping.

    <Warning>
      Use only music you have rights to. Royalty-free libraries (Epidemic Sound, Artlist, etc.) are safe; popular music played to callers without a license is a copyright violation.
    </Warning>
  </Tab>

  <Tab title="Mixed audio (music + announcements)">
    Interleave music with periodic announcements: "We appreciate your patience. Your call will be answered shortly. Visit acme.com/help while you wait." Hiveku ducks the music under the voice automatically.
  </Tab>
</Tabs>

## Position and ETA announcements

| Setting                | Effect                                                                  |
| ---------------------- | ----------------------------------------------------------------------- |
| Position every 30 sec  | Caller hears "You are caller 3" then "now caller 2" then "now caller 1" |
| Position only at entry | One announcement, then music                                            |
| ETA every 60 sec       | Caller hears "Estimated wait 4 minutes" updates                         |
| Both                   | Position + ETA each interval                                            |
| Neither                | Pure music                                                              |

ETA is computed from the rolling average handle time of recent calls in this queue, multiplied by your position. It's an estimate, not a guarantee — but it's far more useful than silence.

## Callback option

When enabled, after N seconds in queue (default 60), callers hear: "Press 1 to keep your place in line and we'll call you back when an agent is available."

When the caller presses 1:

1. They hang up
2. Their position is preserved in the queue
3. When an agent becomes free for their turn, the system **first** calls the agent, then bridges to the caller
4. If the caller doesn't answer the callback, they're skipped and the next caller (or callback) is offered

Callbacks recover roughly 30% of would-be abandons in our analytics. They're the single highest-impact queue feature.

## Agent presence

Agents have presence states they toggle from their phone or browser:

| State     | Effect                                                                                     |
| --------- | ------------------------------------------------------------------------------------------ |
| Available | Eligible to receive queue calls                                                            |
| On call   | Currently on a call (set automatically)                                                    |
| On break  | Logged out for break — no calls                                                            |
| Wrap-up   | Post-call work — temporary skip, auto-returns to Available after configurable wrap-up time |
| Busy      | Manual hold — no calls until manually returned to Available                                |

The Queues tab shows live presence for each queue: "3 agents available, 1 on call, 1 on break".

## Wrap-up time

After a call ends, the agent is auto-set to "Wrap-up" for N seconds (default 15) so they can finish notes before the next call. Configure per queue. Set to 0 to disable.

## Overflow

When a caller has been in queue past `max_wait_seconds`, the call fails over to the configured overflow:

* **Voicemail** — Default. Caller leaves a message.
* **Another queue** — Spill to a backup team.
* **IVR** — "Sorry for the wait, press 1 to leave a message or 2 to be called back."
* **External number** — Forward to an answering service.

## Service-level alerts

Get alerted when queue health degrades:

* Average wait time exceeds N minutes
* Abandon rate exceeds N%
* Available agents drops to 0

Alerts go to email, Slack, or webhook. Configure in the queue's detail page.

## Analytics

The **Analytics** tab shows per-queue metrics:

* **Inbound volume** — calls offered, answered, abandoned
* **Service level** — % answered within N seconds (default 30)
* **Average wait time**
* **Average handle time**
* **Abandon rate**
* **Per-agent performance** — calls taken, avg handle time, idle time

Filter by date range, hour-of-day, day-of-week.

## API

```bash theme={null}
# Create a queue
curl -X POST https://api.hiveku.com/api/communications/queues \
  -H "Authorization: Bearer hk_live_xxx" \
  -d '{
    "name": "Sales Hold",
    "strategy": "longest_idle",
    "agents": ["101", "102", "103"],
    "hold_music_playlist": "default-calm",
    "callback_enabled": true,
    "callback_offer_after_seconds": 60,
    "max_wait_seconds": 600
  }'

# Live queue status
curl https://api.hiveku.com/api/communications/queues/q_01HQ/status \
  -H "Authorization: Bearer hk_live_xxx"
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="ETA is way off">
    ETA is based on the last 20 calls' average handle time. Right after launch, or after a routing change, the sample is small and ETA is noisy. It stabilizes after a couple dozen calls.
  </Accordion>

  <Accordion title="Callbacks aren't being attempted">
    Check that at least one agent is "Available" and the queue has cleared the original caller's position. Callbacks fire when their slot reaches the front.
  </Accordion>

  <Accordion title="Hold music sounds choppy">
    Hold music is transcoded to PCMU/PCMA for compatibility. If you hear glitches, the source file may be corrupted or have an unusual sample rate — re-export at 8 kHz mono and re-upload.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Ring groups" icon="users" href="/communications/ring-groups">
    Smaller, simpler routing for low-volume teams.
  </Card>

  <Card title="Compliance" icon="shield-check" href="/communications/compliance">
    Recording controls and retention for queue calls.
  </Card>
</CardGroup>