Ring Groups

A ring group is a hunt group: one dialable name that rings a set of endpoints according to a strategy, with a mandatory fallback when nobody answers. Front desks, sales queues without queuing, on-call rotations, and “ring everyone in the shop” all live here.

ring-groups:
  front-desk:
    mode: lines
    lines: ["1001", "1002", "1003"]
    strategy: serial
    ring-for: 15
    no-answer:
      resource-type: voicemail-box
      resource-id: "1000"

Calls reach a ring group as a translation target (resource-type: ring-group), or through a line that fronts the group with ring-group: — the usual way to give a hunt group a directory number.

Field reference

Field	Required	Meaning
mode	no	Where the ring targets come from: device (default) or lines (below).
devices	device mode	The device endpoints to ring, in order.
lines	lines mode	The member lines to ring, in order.
strategy	yes	serial, random, or parallel (below).
ring-for	no	Seconds each ring step is given before moving on. Default 25.
no-answer	yes	Where the call goes when the whole group fails to answer — a resource-type / resource-id pair accepting any dialable target (voicemail box, another ring group, a line, a treatment, …).

The two modes

Mode decides what one “ring target” is; it does not change how strategies behave.

device mode (the default) rings individual devices from the devices: list — each device is its own step. Use it when membership is “these specific phones”: a warehouse’s overhead ringers, the two handsets at a reception counter.

lines mode rings member lines — each step is one line, meaning all of that line’s devices ring together, with the line’s codec preferences applied. Use it when membership is “these people”, so a member with a desk phone and a softphone gets both.

Lines mode selects the line, not its features

A hunt call to a member line ignores that member’s personal features: DND, call-forwards, and the member’s own voicemail are not consulted — an unanswered step simply advances the hunt. Personal features apply to calls addressed to the line, not to hunt-group membership. If members expect their DND to remove them from the hunt, that is not how this release behaves — membership changes are a configuration edit.

This may change with a new mode in future releases.

In lines mode, a member that resolves to no ringable devices — a pointer line, a line that itself fronts a ring group, a line with an empty device list — is skipped. Members must be ordinary device-bearing lines.

Strategies

Strategy	Behavior
serial	Ring targets one at a time in declared order; an unanswered or busy step advances to the next.
random	Same one-at-a-time hunt, but in a freshly shuffled order per call — informal load balancing across members.
parallel	Ring every target at once; first answer wins and the others stop ringing.

Timing: each step gets ring-for seconds — in serial/random that is per target, so the caller’s worst case is roughly ring-for × number of targets before the fallback; in parallel the whole group shares one ring-for window. Size ring-for accordingly: 15–20 seconds per serial step keeps a four-member hunt under a minute.

Busy members don’t stall the hunt — a busy step advances just like an unanswered one.

Parallel mode and codec preferences

In lines mode with parallel, per-line codec preferences are applied only when every member shares the same list (i.e. the members use the same line profile). Members with differing codec lists still ring, but without a per-call codec constraint — negotiation falls back to the endpoint defaults.

The no-answer fallback

no-answer is required and fires when the entire group is exhausted (serial/random) or the parallel window expires. It accepts any dialable target, so common shapes are all expressible:

# Overflow to a shared mailbox:
no-answer:
  resource-type: voicemail-box
  resource-id: "1000"

# Escalate to another group (day team → duty manager):
no-answer:
  resource-type: ring-group
  resource-id: managers

# Announce-and-release after hours:
no-answer:
  resource-type: treatment
  resource-id: closed-announcement     # custom treatment recording

Chaining groups via no-answer is supported and useful for escalation tiers. Chains must be straight lines: a cycle (group A overflows to B, B back to A, or a group targeting itself) has no answer waiting at the end of the loop, and the configuration validator rejects one, naming the groups on the cycle.

Worked examples

Reception with voicemail overflow

ring-groups:
  front-desk:
    mode: lines
    lines: ["1001", "1002"]
    strategy: parallel
    ring-for: 20
    no-answer:
      resource-type: voicemail-box
      resource-id: "1000"

lines:
  "1000":
    line-profile: standard
    ring-group: front-desk        # the group's directory number

Callers dial 1000; both receptionists’ phones (all devices each) ring for 20 seconds; unanswered calls land in the shared mailbox.

Round-robin-ish sales hunt

ring-groups:
  sales:
    mode: lines
    lines: ["2001", "2002", "2003", "2004"]
    strategy: random
    ring-for: 15
    no-answer:
      resource-type: ring-group
      resource-id: sales-overflow

  sales-overflow:
    mode: device
    devices: [sales-manager-desk]
    strategy: parallel
    ring-for: 20
    no-answer:
      resource-type: voicemail-box
      resource-id: "2000"

Each call hunts the team in a different order; misses escalate to the manager’s desk phone, then to the sales mailbox.

Overhead ringers (device mode)

ring-groups:
  shop-floor:
    strategy: parallel            # mode defaults to device
    devices: [bay1-ringer, bay2-ringer, office-phone]
    ring-for: 30
    no-answer:
      resource-type: treatment
      resource-id: reorder

Validation summary

• strategy must be serial, random, or parallel.
• Device mode requires at least one device, and every device must exist; listing lines in device mode is an error (set mode: lines).
• Lines mode requires at least one line, and every line must exist; listing devices in lines mode is an error.
• no-answer must reference a valid dialable resource, and the no-answer graph across ring groups must be cycle-free.