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

# Ring Groups

> Route inbound calls to multiple extensions with hunt strategies

A ring group is a set of extensions that share inbound routing. When a DID is pointed at a ring group, an incoming call rings the extensions in the group according to the strategy you choose — all at once, one after another, in rotation, or to whoever's been idle longest.

Configure ring groups in `/dashboard/communications/` under the **Ring Groups** tab.

## Strategies

<Tabs>
  <Tab title="Sequential">
    Rings extensions in order, one at a time. If extension 101 doesn't answer in N seconds, ring 102. If 102 doesn't answer, ring 103. Continue down the list until someone picks up or all extensions exhaust.

    Best for: tiered escalation (junior reps first, senior reps next), small teams where one person is the primary contact.
  </Tab>

  <Tab title="Simultaneous">
    All extensions in the group ring at the same time. First to pick up takes the call.

    Best for: small teams (2-5 people) where coverage matters more than fairness. Beware: at scale, simultaneous ring is jarring for everyone.
  </Tab>

  <Tab title="Round-robin">
    Rotates through extensions in turn order. Call 1 goes to A, call 2 to B, call 3 to C, then wraps. Skips anyone offline or on a call.

    Best for: equal distribution among reps. Sales floors, support teams.
  </Tab>

  <Tab title="Longest-idle">
    Rings whoever has been off-call the longest. Load-balances by elapsed-since-last-call rather than turn order.

    Best for: support teams where you want each agent to take roughly the same volume regardless of when they joined the shift.
  </Tab>

  <Tab title="Random">
    Picks a random extension on each call. Useful when you want neither strict rotation nor strict ordering.
  </Tab>
</Tabs>

## Create a ring group

<Steps>
  <Step title="Pick a name">
    "Sales", "Support Tier 1", "After Hours" — whatever maps to how you'll think about it.
  </Step>

  <Step title="Add extensions">
    Add each user's extension. Order matters for sequential and round-robin.
  </Step>

  <Step title="Pick a strategy">
    Sequential, simultaneous, round-robin, longest-idle, or random.
  </Step>

  <Step title="Set ring time">
    How long each extension rings before moving on (sequential) or before the whole group times out (simultaneous). Default is 20 seconds.
  </Step>

  <Step title="Configure failover">
    What happens if no one in the group answers — voicemail, queue, IVR, another ring group, or external forward.
  </Step>
</Steps>

## Failover (no answer behavior)

When the ring group exhausts without an answer, the call falls through to a failover destination.

| Failover           | When to use                                                           |
| ------------------ | --------------------------------------------------------------------- |
| Voicemail          | Default. Caller leaves a message that gets emailed to a recipient.    |
| Queue              | Caller waits on hold with music until someone in the group is free.   |
| IVR                | Replay menu, offer "press 1 to leave a message, 2 to be called back". |
| Another ring group | Escalate to a senior team.                                            |
| External number    | Forward to a cell, answering service, or backup line.                 |

## Skip-on-busy and skip-offline

Two important toggles:

* **Skip on busy** — If an extension is currently on a call, skip to the next one. Default `on`. Turn off if you want call-waiting tone instead.
* **Skip offline** — If an extension's device isn't registered, skip it. Default `on`. Turn off only if you want the call to fail fast when nobody's logged in.

<Tip>
  Round-robin with skip-on-busy is the gold-standard for sales floors — fair distribution, no double-rings, no call ever waits on someone busy.
</Tip>

## Caller ID prepending

Optionally prepend a tag to the caller ID display so agents know which group the call came from. Useful when one person is in multiple groups.

```
Inbound: +1 415-555-0100  →  Display: [Sales] +1 415-555-0100
Inbound: +1 415-555-0100  →  Display: [Support] +1 415-555-0100
```

The original caller ID is preserved on the call record; only the device display changes.

## Music on transfer

When sequential ringing fails over to the next extension, you can play hold music to the caller during the transfer pause (typically 1-2 seconds). Reduces the perceived dead air and keeps the caller engaged. Disabled by default.

## Pickup groups

A pickup group is a related concept: any extension in the group can pick up a ringing call from any other extension in the group with a single shortcut (`*8` by default). Useful in physical office settings where you can hear a coworker's phone ringing and want to grab it without walking over.

Configure pickup groups in the **Extensions** tab — each extension can belong to one pickup group.

## API

```bash theme={null}
# Create a ring group
curl -X POST https://api.hiveku.com/api/communications/ring-groups \
  -H "Authorization: Bearer hk_live_xxx" \
  -d '{
    "name": "Sales",
    "strategy": "round_robin",
    "ring_time_seconds": 20,
    "extensions": ["101", "102", "103"],
    "failover": "queue:sales-hold"
  }'
```

## Common patterns

<Tabs>
  <Tab title="Small team coverage">
    3 reps, simultaneous ring, 25-second timeout, fail to voicemail. Whoever picks up first takes the call.
  </Tab>

  <Tab title="Sales floor">
    8 reps, round-robin, skip-on-busy on, fail to a queue with hold music. Even distribution, no call goes unanswered for long.
  </Tab>

  <Tab title="Tiered support">
    Sequential. Tier 1 (3 agents) first; if no answer in 30 sec, fail to a Tier 2 ring group (2 agents); if still no answer, fail to voicemail.
  </Tab>

  <Tab title="After-hours">
    Single sequential group with one extension (the on-call person), then fail to an external answering service.
  </Tab>
</Tabs>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Ring group calls aren't reaching anyone">
    Check that the extensions are registered (devices online) and skip-offline isn't excluding them all. Live registration status is visible in the **Extensions** tab.
  </Accordion>

  <Accordion title="Round-robin keeps picking the same agent">
    Round-robin honors skip-on-busy and skip-offline, so when others are on calls or offline, one person can take many in a row. Add more extensions or adjust strategies during peak hours.
  </Accordion>

  <Accordion title="Simultaneous ring is jarring with 8 phones">
    Switch to round-robin or longest-idle for groups bigger than \~5 extensions. Simultaneous works best for tight teams.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Queues" icon="users-line" href="/communications/queues">
    Hold music and callback when ring groups are exhausted.
  </Card>

  <Card title="IVR" icon="list-tree" href="/communications/ivr">
    Route to ring groups via a menu.
  </Card>
</CardGroup>